[libvirt] [PATCH v3 0/3] Improve release notes process
Dan raised some concerns, but it doesn't look like they're critical enough for him to NACK the series; moreover, it's all stuff that we can easily address later on, so I'd like to move forward with this before the freeze. Details of changes can be found in the single patches. Andrea Bolognani (3): NEWS: Improve building pipeline NEWS: Reformat at generation time docs: Document the release notes process for contributors .gitignore | 1 + HACKING | 7 ++ Makefile.am | 26 ++++-- docs/Makefile.am | 28 +++++- docs/hacking.html.in | 10 ++ docs/news-ascii.xsl | 68 ++++++++++++++ docs/news-html.xsl | 96 +++++++++++++++++++ docs/news.html.in | 164 -------------------------------- docs/news.xml | 252 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/news.xsl | 50 ---------- docs/reformat-news.py | 104 +++++++++++++++++++++ 11 files changed, 583 insertions(+), 223 deletions(-) create mode 100644 docs/news-ascii.xsl create mode 100644 docs/news-html.xsl delete mode 100644 docs/news.html.in create mode 100644 docs/news.xml delete mode 100644 docs/news.xsl create mode 100755 docs/reformat-news.py -- 2.7.4
Currently, building the NEWS file involves using a XSLT stylesheet to extract information from the same HTML file that's used on the libvirt website. The process works, but it's quite fiddly in that it requires the source HTML to be formatted in a very precise way, and a single missing newline can mess up the resulting plain text considerably. Moreover, the XSLT stylesheet itself encodes a lot of the details of converting to plain text in a way that's not necessarily easy to understand, tweak or fix. To improve the process, move all existing entries to a new XML file that contains exactly the information we care about in a simple structured format, and start generating both the HTML and plain text versions of the release notes using XSLT stylesheets that can now afford to be almost trivial. --- Changes from v2: * Address review comments - Update "bottom text" for both ASCII and HTML versions * XSLT stylesheet (ASCII version) - Prefix contents of the <description> element with a special marker in the output * Build system - Make sure all files are distributed - Tweak formatting * Release notes - Sync to current master Changes from v1: * Address review comments - Rename XSLT stylesheets to news-{ascii,html}.xsl - Add "do not edit" note to news.html.in - Add "older releases" note to NEWS * Rename XML elements - <change> instead of <item> - <libvirt> instead of <releases> .gitignore | 1 + Makefile.am | 11 ++- docs/Makefile.am | 28 +++++- docs/news-ascii.xsl | 68 ++++++++++++++ docs/news-html.xsl | 96 ++++++++++++++++++++ docs/news.html.in | 164 ---------------------------------- docs/news.xml | 252 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/news.xsl | 50 ----------- 8 files changed, 451 insertions(+), 219 deletions(-) create mode 100644 docs/news-ascii.xsl create mode 100644 docs/news-html.xsl delete mode 100644 docs/news.html.in create mode 100644 docs/news.xml delete mode 100644 docs/news.xsl diff --git a/.gitignore b/.gitignore index 984ad07..7b71bd1 100644 --- a/.gitignore +++ b/.gitignore @@ -72,6 +72,7 @@ /docs/libvirt-lxc-*.xml /docs/libvirt-qemu-*.xml /docs/libvirt-refs.xml +/docs/news.html.in /docs/search.php /docs/todo.html.in /examples/admin/client_close diff --git a/Makefile.am b/Makefile.am index 50c358c..fa45388 100644 --- a/Makefile.am +++ b/Makefile.am @@ -46,13 +46,18 @@ EXTRA_DIST = \ pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = libvirt.pc libvirt-qemu.pc libvirt-lxc.pc libvirt-admin.pc -NEWS: $(top_srcdir)/docs/news.xsl $(top_srcdir)/docs/news.html.in +NEWS: \ + $(srcdir)/docs/news.xml \ + $(srcdir)/docs/news-ascii.xsl $(AM_V_GEN)if [ -x $(XSLTPROC) ] ; then \ - $(XSLTPROC) --nonet $(top_srcdir)/docs/news.xsl \ - $(top_srcdir)/docs/news.html.in \ + $(XSLTPROC) --nonet $(srcdir)/docs/news-ascii.xsl \ + $(srcdir)/docs/news.xml \ | perl -0777 -pe 's/\n\n+$$/\n/' \ | perl -pe 's/[ \t]+$$//' \ > $@-t && mv $@-t $@ ; fi +EXTRA_DIST += \ + $(srcdir)/docs/news.xml \ + $(srcdir)/docs/news-ascii.xsl $(top_srcdir)/HACKING: $(top_srcdir)/docs/hacking1.xsl \ $(top_srcdir)/docs/hacking2.xsl \ diff --git a/docs/Makefile.am b/docs/Makefile.am index 790c0a2..62e069e 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -106,9 +106,10 @@ internals_html = $(internals_html_in:%.html.in=%.html) # Since we ship pre-built html in the tarball, we must also # ship the sources, even when those sources are themselves # generated. -# Generate hvsupport.html first, since it takes one extra step. +# Generate hvsupport.html and news.html first, since they take one extra step. dot_html_in = \ hvsupport.html.in \ + news.html.in \ $(notdir $(wildcard $(srcdir)/*.html.in)) dot_html = $(dot_html_in:%.html.in=%.html) @@ -156,7 +157,7 @@ schema_DATA = $(wildcard $(srcdir)/schemas/*.rng) EXTRA_DIST= \ apibuild.py genaclperms.pl \ - site.xsl subsite.xsl newapi.xsl news.xsl page.xsl \ + site.xsl subsite.xsl newapi.xsl page.xsl \ hacking1.xsl hacking2.xsl wrapstring.xsl \ $(dot_html) $(dot_html_in) $(gif) $(apihtml) $(apipng) \ $(devhelphtml) $(devhelppng) $(devhelpcss) $(devhelpxsl) \ @@ -200,6 +201,29 @@ $(srcdir)/hvsupport.html.in: $(srcdir)/hvsupport.pl $(api_DATA) \ $(AM_V_GEN)$(PERL) $(srcdir)/hvsupport.pl $(top_srcdir)/src > $@ \ || { rm $@ && exit 1; } +# xsltproc seems to add the xmlns="" attribute to random output elements: +# use sed to strip it out, as leaving it there triggers XML errors during +# further transformation steps +news.html.in: \ + $(srcdir)/news.xml \ + $(srcdir)/news-html.xsl + $(AM_V_GEN) \ + if [ -x $(XSLTPROC) ]; then \ + $(XSLTPROC) --nonet \ + $(srcdir)/news-html.xsl \ + $(srcdir)/news.xml \ + >$@-tmp \ + || { rm -f $@-tmp; exit 1; }; \ + sed 's/ xmlns=""//g' $@-tmp >$@ \ + || { rm -f $@-tmp; exit 1; }; \ + rm -f $@-tmp; \ + fi +EXTRA_DIST += \ + $(srcdir)/news.xml \ + $(srcdir)/news-html.xsl +MAINTAINERCLEANFILES += \ + $(srcdir)/news.html.in + %.png: %.fig convert -rotate 90 $< $@ diff --git a/docs/news-ascii.xsl b/docs/news-ascii.xsl new file mode 100644 index 0000000..637c432 --- /dev/null +++ b/docs/news-ascii.xsl @@ -0,0 +1,68 @@ +<?xml version="1.0"?> +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> + <xsl:output method="text" encoding="UTF-8"/> + + <!-- This XSLT stylesheet can be applied to the XML version of the release + notes to produce a plain text document. The output document is not + formatted properly and needs to be processed further --> + + <!-- Document --> + <xsl:template match="/libvirt"> + <xsl:text>libvirt releases +================ +</xsl:text> + <xsl:apply-templates select="release"/> + <xsl:text> +============================================================================== +Older libvirt releases didn't have proper release notes: if you are interested +in changes between them, you should check out ChangeLog* and docs/news-*.html. +</xsl:text> + </xsl:template> + + <!-- Release --> + <xsl:template match="release"> + <xsl:text> +# </xsl:text> + <xsl:value-of select="@version"/> + <xsl:text> (</xsl:text> + <xsl:value-of select="@date"/> + <xsl:text>) +</xsl:text> + <xsl:apply-templates select="section"/> + </xsl:template> + + <!-- Section --> + <xsl:template match="section"> + <xsl:text> +* </xsl:text> + <xsl:value-of select="@title"/> + <xsl:text> +</xsl:text> + <xsl:apply-templates select="change"/> + </xsl:template> + + <!-- Change --> + <xsl:template match="change"> + <xsl:text> +</xsl:text> + <xsl:apply-templates select="summary"/> + <xsl:apply-templates select="description"/> + </xsl:template> + + <!-- Change summary --> + <xsl:template match="summary"> + <xsl:text>- </xsl:text> + <xsl:value-of select="normalize-space()"/> + <xsl:text> +</xsl:text> + </xsl:template> + + <!-- Change description --> + <xsl:template match="description"> + <xsl:text>|</xsl:text> <!-- This will be removed when reformatting --> + <xsl:value-of select="normalize-space()"/> + <xsl:text> +</xsl:text> + </xsl:template> + +</xsl:stylesheet> diff --git a/docs/news-html.xsl b/docs/news-html.xsl new file mode 100644 index 0000000..2961106 --- /dev/null +++ b/docs/news-html.xsl @@ -0,0 +1,96 @@ +<?xml version="1.0"?> +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> + <xsl:output method="xml" indent="yes" encoding="UTF-8"/> + + <!-- This XSLT stylesheet can be applied to the XML version of the release + notes to produce an HTML document suitable for further processing. + In particular, the final output will end up on the libvirt website --> + + <!-- Document --> + <xsl:template match="/libvirt"> + <xsl:text disable-output-escaping="yes"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">; +</xsl:text> + <html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> + </head> + <body> + <xsl:text disable-output-escaping="yes"> + + <!-- DO NOT EDIT THIS FILE! It was generated automatically. + Edit the source file (news.xml) instead --> + + </xsl:text> + <h1>Releases</h1> + <p>This is the list of official releases for libvirt, along with an + overview of the changes introduced by each of them.</p> + <p>For a more fine-grained view, use the + <a href="http://libvirt.org/git/?p=libvirt.git;a=log">git log</a>. + </p> + <xsl:apply-templates select="release"/> + <p>Older libvirt releases didn't have proper release notes, + and as such are not included in this page: if you're looking + for information about them, start from those made in + <a href="news-2016.html">2016</a> and work your way back.</p> + </body> + </html> + </xsl:template> + + <!-- Release --> + <xsl:template match="release"> + <h3> + <strong> + <xsl:value-of select="@version"/> + <xsl:text> (</xsl:text> + <xsl:value-of select="@date"/> + <xsl:text>)</xsl:text> + </strong> + </h3> + <ul> + <xsl:apply-templates select="section"/> + </ul> + </xsl:template> + + <!-- Section --> + <xsl:template match="section"> + <li> + <strong> + <xsl:value-of select="@title"/> + </strong> + <ul> + <xsl:apply-templates select="change"/> + </ul> + </li> + </xsl:template> + + <!-- Change --> + <xsl:template match="change"> + <li> + <xsl:apply-templates select="summary"/> + <xsl:apply-templates select="description"/> + </li> + </xsl:template> + + <!-- Change summary --> + <xsl:template match="summary"> + <xsl:apply-templates/> + </xsl:template> + + <!-- Change description --> + <xsl:template match="description"> + <br/> + <xsl:apply-templates/> + </xsl:template> + + <!-- Misc HTML tags, add more as they are needed --> + <xsl:template match="code|i|tt"> + <xsl:text disable-output-escaping="yes"><</xsl:text> + <xsl:value-of select="name()"/> + <xsl:text disable-output-escaping="yes">></xsl:text> + <xsl:apply-templates/> + <xsl:text disable-output-escaping="yes"></</xsl:text> + <xsl:value-of select="name()"/> + <xsl:text disable-output-escaping="yes">></xsl:text> + </xsl:template> + +</xsl:stylesheet> diff --git a/docs/news.html.in b/docs/news.html.in deleted file mode 100644 index 8dccb48..0000000 --- a/docs/news.html.in +++ /dev/null @@ -1,164 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - </head> - <body> - <h1>Releases</h1> - <p>This is the list of official releases for libvirt, along with an - overview of the changes introduced by each of them.</p> - <p>For a more fine-grained view, use the - <a href="http://libvirt.org/git/?p=libvirt.git;a=log">git log</a>. - </p> - - <h3>v3.0.0 (<i>unreleased</i>)</h3> - <ul> - <li><strong>New features</strong> - <ul> - <li>New localPtr attribute for "ip" element in network XML - </li> - <li>qemu: Support QEMU group I/O throttling<br/> - Add the capability to allow group I/O throttling via a new - domain <disk> <iotune> subelement "group_name" - to allow sharing I/O throttling quota between multiple drives - </li> - <li>nss: Introduce <code>libvirt-guest</code><br/> - New <code>libvirt-guest</code> nss module that translates libvirt - guest names into IP addresses - </li> - <li>daemon: Add support for runtime logging settings adjustment<br/> - Logging-related settings like log outputs and filters can now be - adjusted during runtime using the admin interface without the - necessity of the daemon's restart - </li> - <li>storage: Add virStorageVolInfoFlags API<br/> - Add the API to support using the VIR_STORAGE_VOL_GET_PHYSICAL - flag in order to return the host physical size in bytes - of the image container in the allocation field of the - _virStorageVolInfo structure. The --physical flag has been - added to the virsh vol-info command to access the data - </li> - </ul> - </li> - <li><strong>Improvements</strong> - <ul> - <li>perf: Add more perf statistics<br/> - Add support to get the count of branch instructions - executed, branch misses, bus cycles, stalled frontend - cpu cycles, stalled backend cpu cycles, ref cpu - cycles and cache l1d by applications running on - the platform - </li> - <li>conf: Display <physical> for volume xml<br/> - Add a display of the <physical> size of a disk - volume in the output of the volume XML - </li> - <li>qemu: Use virtio-pci by default for aarch64 mach-virt guests<br/> - virtio-pci provides several advantages over virtio-mmio, such - as the ability to hotplug devices and improved performance. - While opting in to virtio-pci has been possible for a while, - newly-defined guests will now use it automatically - </li> - </ul> - </li> - <li><strong>Bug fixes</strong> - <ul> - <li>qemu: Correct GetBlockInfo values<br/> - For an active domain, correct the physical value provided for - a raw sparse file backed storage and the allocation value provided - for a qcow2 file backed storage that hasn't yet been opened on - the domain - </li> - <li>qemu: Make virtio console usable on ppc64 guests<br/> - The chardev detection code has been improved and can now handle this - configuration properly - </li> - <li>qemu: Enable mount namespace<br/> - To avoid funny races with udev relabelling devices under our hands and - to enhance security, libvirt now spawns each qemu process with its own - <code>/dev</code></li> - </ul> - </li> - </ul> - - <h3>v2.5.0 (2016-12-04)</h3> - <ul> - <li><strong>New features</strong> - <ul> - <li>shmem: Add support for additional models<br/> - The shmem device can now utilize QEMU's ivshmem-plain and - ivshmem-doorbell, more modern versions of ivshmem - </li> - <li>vbox: Add VirtualBox 5.1 support - </li> - <li>libssh: New transport<br/> - The new libssh transport allows one to connect to a running - libvirtd via SSH, using the libssh library; for example: - <tt>qemu+libssh://<i>server</i>/system</tt> - </li> - <li>vhost-scsi: Add support scsi_host hostdev passthrough<br/> - Add the capability to pass through a scsi_host HBA and the - associated LUNs to the guest - </li> - <li>qemu: Users can now enable debug logging for native gluster - volumes in qemu using the "gluster_debug_level" option in qemu.conf - </li> - <li>memory hotplug: Slot numbers for memory devices are now - automatically allocated and thus persistent. In addition slot numbers - can be specified without providing a base address, which simplifies - user configuration - </li> - <li>qemu: Express devices will be placed on PCIe bus by default<br/> - For machine types that use a PCI Express root bus - (e.g. x86_64/Q35 and aarch64/virt), any unaddressed PCI - device that is an Express device (all virtio-1.0 devices, - e1000e, nec-xhci, vfio assigned devices) will be placed on - an Express controller (i.e. a pcie-root-port) instead of a - legacy PCI controller (i.e. pci-bridge) with the root ports - added as needed - </li> - </ul> - </li> - <li><strong>Improvements</strong> - <ul> - <li>docs: Better documentation for migration APIs and flags - </li> - <li>vbox: Address thread safety issues - </li> - <li>virsh: Add support for passing an alternative persistent XML - to migrate command - </li> - <li>vhostuser: Allow hotplug of multiqueue devices - </li> - <li>NEWS: Switch to an improved format<br/> - List user-visible changes instead of single commits for a better - high-level overview of differences between libvirt releases - </li> - <li>website: Modernize layout and branding<br/> - The libvirt website looked very cluttered and outdated; it has now - been completely overhauled, resulting in a design that's better - organized and more pleasant to look at - </li> - </ul> - </li> - <li><strong>Bug fixes</strong> - <ul> - <li>vz: Fix migration in P2P mode - </li> - <li>Forbid newline character in names of some libvirt objects - </li> - <li>Fix compilation on macOS - </li> - </ul> - </li> - </ul> - - <p>Releases earlier than v2.5.0 detailed their changes using a different - format and as such are excluded from the list above. - You can read about those older release, starting from those made in - <a href="news-2016.html">2016</a>. - </p> - - </body> -</html> diff --git a/docs/news.xml b/docs/news.xml new file mode 100644 index 0000000..779fe66 --- /dev/null +++ b/docs/news.xml @@ -0,0 +1,252 @@ +<?xml version="1.0"?> + +<!-- libvirt release notes + + This file will be processed to produce both HTML and plain text versions + of the release notes. + + Keep the style consistent with existing entries as much as possible: + each change should be documented by a short, one-sentence summary + and optionally a description where it's explained in more detail --> + +<libvirt> + <release version="v3.0.0" date="unreleased"> + <section title="New features"> + <change> + <summary> + New localPtr attribute for "ip" element in network XML + </summary> + </change> + <change> + <summary> + qemu: Support QEMU group I/O throttling + </summary> + <description> + Add the capability to allow group I/O throttling via a new + domain <disk> <iotune> subelement "group_name" + to allow sharing I/O throttling quota between multiple drives + </description> + </change> + <change> + <summary> + nss: Introduce <code>libvirt-guest</code> + </summary> + <description> + New <code>libvirt-guest</code> nss module that translates libvirt + guest names into IP addresses + </description> + </change> + <change> + <summary> + daemon: Add support for runtime logging settings adjustment + </summary> + <description> + Logging-related settings like log outputs and filters can now be + adjusted during runtime using the admin interface without the + necessity of the daemon's restart + </description> + </change> + <change> + <summary> + storage: Add virStorageVolInfoFlags API + </summary> + <description> + Add the API to support using the VIR_STORAGE_VOL_GET_PHYSICAL + flag in order to return the host physical size in bytes + of the image container in the allocation field of the + _virStorageVolInfo structure. The --physical flag has been + added to the virsh vol-info command to access the data + </description> + </change> + </section> + <section title="Improvements"> + <change> + <summary> + perf: Add more perf statistics + </summary> + <description> + Add support to get the count of branch instructions + executed, branch misses, bus cycles, stalled frontend + cpu cycles, stalled backend cpu cycles, and ref cpu + cycles by applications running on the platform + </description> + </change> + <change> + <summary> + conf: Display <physical> for volume xml + </summary> + <description> + Add a display of the <physical> size of a disk + volume in the output of the volume XML + </description> + </change> + <change> + <summary> + qemu: Use virtio-pci by default for aarch64 mach-virt guests + </summary> + <description> + virtio-pci provides several advantages over virtio-mmio, such + as the ability to hotplug devices and improved performance. + While opting in to virtio-pci has been possible for a while, + newly-defined guests will now use it automatically + </description> + </change> + </section> + <section title="Bug fixes"> + <change> + <summary> + qemu: Correct GetBlockInfo values + </summary> + <description> + For an active domain, correct the physical value provided for + a raw sparse file backed storage and the allocation value provided + for a qcow2 file backed storage that hasn't yet been opened on + the domain + </description> + </change> + <change> + <summary> + qemu: Make virtio console usable on ppc64 guests + </summary> + <description> + The chardev detection code has been improved and can now handle this + configuration properly + </description> + </change> + <change> + <summary> + qemu: Enable mount namespace + </summary> + <description> + To avoid funny races with udev relabelling devices under our hands and + to enhance security, libvirt now spawns each qemu process with its own + <code>/dev</code>. + </description> + </change> + </section> + </release> + <release version="v2.5.0" date="2016-12-04"> + <section title="New features"> + <change> + <summary> + shmem: Add support for additional models + </summary> + <description> + The shmem device can now utilize QEMU's ivshmem-plain and + ivshmem-doorbell, more modern versions of ivshmem + </description> + </change> + <change> + <summary> + vbox: Add VirtualBox 5.1 support + </summary> + </change> + <change> + <summary> + libssh: New transport + </summary> + <description> + The new libssh transport allows one to connect to a running + libvirtd via SSH, using the libssh library; for example: + <tt>qemu+libssh://<i>server</i>/system</tt> + </description> + </change> + <change> + <summary> + vhost-scsi: Add support scsi_host hostdev passthrough + </summary> + <description> + Add the capability to pass through a scsi_host HBA and the + associated LUNs to the guest + </description> + </change> + <change> + <summary> + qemu: Users can now enable debug logging for native gluster + volumes in qemu using the "gluster_debug_level" option in qemu.conf + </summary> + </change> + <change> + <summary> + memory hotplug: Slot numbers for memory devices are now + automatically allocated and thus persistent. In addition slot numbers + can be specified without providing a base address, which simplifies + user configuration + </summary> + </change> + <change> + <summary> + qemu: Express devices will be placed on PCIe bus by default + </summary> + <description> + For machine types that use a PCI Express root bus + (e.g. x86_64/Q35 and aarch64/virt), any unaddressed PCI + device that is an Express device (all virtio-1.0 devices, + e1000e, nec-xhci, vfio assigned devices) will be placed on + an Express controller (i.e. a pcie-root-port) instead of a + legacy PCI controller (i.e. pci-bridge) with the root ports + added as needed + </description> + </change> + </section> + <section title="Improvements"> + <change> + <summary> + docs: Better documentation for migration APIs and flags + </summary> + </change> + <change> + <summary> + vbox: Address thread safety issues + </summary> + </change> + <change> + <summary> + virsh: Add support for passing an alternative persistent XML + to migrate command + </summary> + </change> + <change> + <summary> + vhostuser: Allow hotplug of multiqueue devices + </summary> + </change> + <change> + <summary> + NEWS: Switch to an improved format + </summary> + <description> + List user-visible changes instead of single commits for a better + high-level overview of differences between libvirt releases + </description> + </change> + <change> + <summary> + website: Modernize layout and branding + </summary> + <description> + The libvirt website looked very cluttered and outdated; it has now + been completely overhauled, resulting in a design that's better + organized and more pleasant to look at + </description> + </change> + </section> + <section title="Bug fixes"> + <change> + <summary> + vz: Fix migration in P2P mode + </summary> + </change> + <change> + <summary> + Forbid newline character in names of some libvirt objects + </summary> + </change> + <change> + <summary> + Fix compilation on macOS + </summary> + </change> + </section> + </release> +</libvirt> diff --git a/docs/news.xsl b/docs/news.xsl deleted file mode 100644 index 33506a9..0000000 --- a/docs/news.xsl +++ /dev/null @@ -1,50 +0,0 @@ -<?xml version="1.0"?> -<xsl:stylesheet version="1.0" - xmlns:html="http://www.w3.org/1999/xhtml" - xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> - <xsl:output method="text" encoding="UTF-8"/> - - <xsl:template match="/"> - <xsl:text>libvirt releases -================ -</xsl:text> - <xsl:apply-templates select="html:html/html:body/*"/> - </xsl:template> - - <xsl:template match="html:h1"/> - <xsl:template match="html:p"/> - - <xsl:template match="html:h3"> - <xsl:text> -</xsl:text> - <xsl:text># </xsl:text> - <xsl:apply-templates/> - <xsl:text> - -</xsl:text> - </xsl:template> - - <xsl:template match="html:ul"> - <xsl:apply-templates select="html:li"/> - </xsl:template> - - <xsl:template match="html:li"> - <xsl:text> * </xsl:text> - <xsl:apply-templates select="html:strong|*/html:li"/> - </xsl:template> - - <xsl:template match="html:li/*/html:li"> - <xsl:text> - </xsl:text> - <xsl:apply-templates/> - <xsl:text> -</xsl:text> - </xsl:template> - - <xsl:template match="html:strong"> - <xsl:apply-templates/> - <xsl:text> - -</xsl:text> - </xsl:template> - -</xsl:stylesheet> -- 2.7.4
Instead of encoding formatting information inside the corresponding XSLT stylesheet, use a Python script to reformat the text appropriately based on a few simple markers. Splitting the task between the XSLT stylesheet and the Python script allows us to keep both parts very simple. --- Changes from v2: * Python script - Consider all unmarked text as verbatim - Support new marker for description - Remove redundancy - Use print() instead of sys.stdout.write() Changes from v1: * Address review comments - Avoid breaking 'make syntax-check' Makefile.am | 23 +++++++---- docs/reformat-news.py | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+), 8 deletions(-) create mode 100755 docs/reformat-news.py diff --git a/Makefile.am b/Makefile.am index fa45388..c6324f5 100644 --- a/Makefile.am +++ b/Makefile.am @@ -48,16 +48,23 @@ pkgconfig_DATA = libvirt.pc libvirt-qemu.pc libvirt-lxc.pc libvirt-admin.pc NEWS: \ $(srcdir)/docs/news.xml \ - $(srcdir)/docs/news-ascii.xsl - $(AM_V_GEN)if [ -x $(XSLTPROC) ] ; then \ - $(XSLTPROC) --nonet $(srcdir)/docs/news-ascii.xsl \ - $(srcdir)/docs/news.xml \ - | perl -0777 -pe 's/\n\n+$$/\n/' \ - | perl -pe 's/[ \t]+$$//' \ - > $@-t && mv $@-t $@ ; fi + $(srcdir)/docs/news-ascii.xsl \ + $(srcdir)/docs/reformat-news.py + $(AM_V_GEN) \ + if [ -x $(XSLTPROC) ]; then \ + $(XSLTPROC) --nonet \ + $(srcdir)/docs/news-ascii.xsl \ + $(srcdir)/docs/news.xml \ + >$@-tmp \ + || { rm -f $@-tmp; exit 1; }; \ + $(srcdir)/docs/reformat-news.py $@-tmp >$@ \ + || { rm -f $@-tmp; exit 1; }; \ + rm -f $@-tmp; \ + fi EXTRA_DIST += \ $(srcdir)/docs/news.xml \ - $(srcdir)/docs/news-ascii.xsl + $(srcdir)/docs/news-ascii.xsl \ + $(srcdir)/docs/reformat-news.py $(top_srcdir)/HACKING: $(top_srcdir)/docs/hacking1.xsl \ $(top_srcdir)/docs/hacking2.xsl \ diff --git a/docs/reformat-news.py b/docs/reformat-news.py new file mode 100755 index 0000000..39499d9 --- /dev/null +++ b/docs/reformat-news.py @@ -0,0 +1,104 @@ +#!/usr/bin/env python + +# reformat-news.py: Reformat the NEWS file properly +# +# Copyright (C) 2017 Red Hat, Inc. +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library. If not, see +# <http://www.gnu.org/licenses/>. +# +# Authors: +# Andrea Bolognani <abologna@redhat.com> + +import sys + +COLUMNS = 80 + +def reformat_with_indent(text, initial_indent, indent): + + res = "" + line = initial_indent + + for word in text.split(): + + # If adding one more word (plus a whitespace, plus a newline) + # to the current line would push us over the desired number + # of columns we start a new line instead + if len(line) + len(word) > (COLUMNS - 2): + res = res + line + "\n" + line = indent + + # We need to take care when we've just started a new line, + # as we don't want to add any additional leading whitespace + # in that case + if line == indent or line == initial_indent: + line = line + word + else: + line = line + " " + word + + # Append whatever's left + res = res + line + + return res + + +def reformat(line): + + # Empty lines don't need to be reformatted or even inspected + if len(line) == 0: + return line + + # For all non-empty lines, we decide the indentation level based + # on the first character + marker = line[0] + + # Release + if marker == '#': + initial_indent = 0 + indent = 2 + # Section + elif marker == '*': + initial_indent = 2 + indent = 4 + # Change summary + elif marker == '-': + initial_indent = 4 + indent = 6 + # Change description + elif marker == '|': + initial_indent = 8 + indent = 8 + # In this one case, the marker should not ultimately show + # up in the output file, so we strip it before moving on + line = line[1:] + # Anything else should be left as-is + else: + return line + + return reformat_with_indent(line, " " * initial_indent, " " * indent) + + +def main(args): + + if len(args) < 2: + sys.stdout.write("Usage: " + args[0] + " FILE\n") + sys.exit(1) + + with open(args[1], 'r') as f: + for line in f: + print(reformat(line.strip())) + + +if __name__ == "__main__": + main(sys.argv) -- 2.7.4
Now that we have built a fairly solid process for dealing with release notes, we should start pushing for contributors to provide the relevant information along with their code: documenting the process is clearly a requirement for this to happen. --- Changes from v2: * Address review comments - Point to the source file in user documentation - Phrasing Changes from v1: * Address review comments - Remove ambiguity between merely documenting changes and adding entries to release notes - Move from "should" to "must" - Move new information to a separate <li> - Regenerate HACKING file HACKING | 7 +++++++ docs/hacking.html.in | 10 ++++++++++ 2 files changed, 17 insertions(+) diff --git a/HACKING b/HACKING index c2cb037..ff545a8 100644 --- a/HACKING +++ b/HACKING @@ -226,6 +226,13 @@ to "tests/.valgrind.supp" in order to suppress the warning: (10) Update tests and/or documentation, particularly if you are adding a new feature or changing the output of a program. +(11) Don't forget to update the release notes <news.html> by changing +"docs/news.xml" if your changes are significant. All user-visible changes, +such as adding new XML elements or fixing all but the most obscure bugs, must +be (briefly) described in a release notes entry; changes that are only +relevant to other libvirt developers, such as code refactoring, don't belong +in the release notes. + There is more on this subject, including lots of links to background reading on the subject, on Richard Jones' guide to working with open source projects <http://people.redhat.com/rjones/how-to-supply-code-to-open-source-projects/>. diff --git a/docs/hacking.html.in b/docs/hacking.html.in index 47475a2..c7bbcbd 100644 --- a/docs/hacking.html.in +++ b/docs/hacking.html.in @@ -294,6 +294,16 @@ <p>Update tests and/or documentation, particularly if you are adding a new feature or changing the output of a program.</p> </li> + + <li> + <p>Don't forget to update the <a href="news.html">release notes</a> + by changing <code>docs/news.xml</code> if your changes are + significant. All user-visible changes, such as adding new XML elements + or fixing all but the most obscure bugs, must be (briefly) described + in a release notes entry; changes that are only relevant to other + libvirt developers, such as code refactoring, don't belong in the + release notes.</p> + </li> </ol> <p> -- 2.7.4
On 01/10/2017 10:25 AM, Andrea Bolognani wrote:
Dan raised some concerns, but it doesn't look like they're critical enough for him to NACK the series; moreover, it's all stuff that we can easily address later on, so I'd like to move forward with this before the freeze.
Details of changes can be found in the single patches.
Andrea Bolognani (3): NEWS: Improve building pipeline NEWS: Reformat at generation time docs: Document the release notes process for contributors
.gitignore | 1 + HACKING | 7 ++ Makefile.am | 26 ++++-- docs/Makefile.am | 28 +++++- docs/hacking.html.in | 10 ++ docs/news-ascii.xsl | 68 ++++++++++++++ docs/news-html.xsl | 96 +++++++++++++++++++ docs/news.html.in | 164 -------------------------------- docs/news.xml | 252 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/news.xsl | 50 ---------- docs/reformat-news.py | 104 +++++++++++++++++++++ 11 files changed, 583 insertions(+), 223 deletions(-) create mode 100644 docs/news-ascii.xsl create mode 100644 docs/news-html.xsl delete mode 100644 docs/news.html.in create mode 100644 docs/news.xml delete mode 100644 docs/news.xsl create mode 100755 docs/reformat-news.py
I'm "mostly" fine with the changes - would like resolution sooner than later since I have a couple of things to add to news, but I didn't want to cause you extra merge cycles ;-) The *one* thing I'm really having a hard time with is not ending sentences with a period for <description>'s. Especially when there's two or more sentences within a <description> where the first one ends with a period, but the second one doesn't Not ending the previous paragraph without a period was really difficult for my fingers. I wouldn't hold up a ACK though for having or not having a period. John
On Tue, 2017-01-10 at 11:23 -0500, John Ferlan wrote:
I'm "mostly" fine with the changes - would like resolution sooner than later since I have a couple of things to add to news, but I didn't want to cause you extra merge cycles ;-)
Yeah, same here :)
The *one* thing I'm really having a hard time with is not ending sentences with a period for <description>'s.
What about <summary>?
Especially when there's two or more sentences within a <description> where the first one ends with a period, but the second one doesn't Not ending the previous paragraph without a period was really difficult for my fingers. I wouldn't hold up a ACK though for having or not having a period.
Patch 1/3 translates the current entries directly to the new format, without any kind of editing. As I've said before, I have zero problems having leading periods for all sentences in the release notes, especially if you feel so strongly about it :) We will have to change them all, though: an inconsistent style just won't do. So, will you ACK this series if I promise to follow up with a patch that adds leading periods to all <description>s? -- Andrea Bolognani / Red Hat / Virtualization
On 01/10/2017 11:55 AM, Andrea Bolognani wrote:
On Tue, 2017-01-10 at 11:23 -0500, John Ferlan wrote:
I'm "mostly" fine with the changes - would like resolution sooner than later since I have a couple of things to add to news, but I didn't want to cause you extra merge cycles ;-)
Yeah, same here :)
The *one* thing I'm really having a hard time with is not ending sentences with a period for <description>'s.
What about <summary>?
Especially when there's two or more sentences within a <description> where the first one ends with a period, but the second one doesn't
Not ending the previous paragraph without a period was really difficult for my fingers. I wouldn't hold up a ACK though for having or not having a period.
Patch 1/3 translates the current entries directly to the new format, without any kind of editing.
As I've said before, I have zero problems having leading periods for all sentences in the release notes, especially if you feel so strongly about it :) We will have to change them all, though: an inconsistent style just won't do.
So, will you ACK this series if I promise to follow up with a patch that adds leading periods to all <description>s?
Sure, ACK with the caveat that I barely know how to spell xlst. Let's see what we can break before the freeze ;-) John
-- Andrea Bolognani / Red Hat / Virtualization
On Tue, 2017-01-10 at 13:28 -0500, John Ferlan wrote:
So, will you ACK this series if I promise to follow up with a patch that adds leading periods to all <description>s? Sure, ACK with the caveat that I barely know how to spell xlst.
Is the misspelling intentional? If so, good one! If not, you've definitely proven your point ;)
Let's see what we can break before the freeze ;-)
I've pushed it now, so we'll know soon enough. Now, if you'll excuse me, there's a follow-up patch that I need to be working on... ;) -- Andrea Bolognani / Red Hat / Virtualization
participants (2)
-
Andrea Bolognani -
John Ferlan