From be36ea4b52c33c7472638b577fcdedf5183f4893 Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Tue, 3 Jan 2017 12:22:54 +0100 Subject: [PATCH] NEWS: Improve building pipeline 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. --- .gitignore | 1 + Makefile.am | 11 +- docs/Makefile.am | 28 ++++- docs/news-ascii.xsl | 68 ++++++++++++ docs/news-html.xsl | 96 +++++++++++++++++ docs/news.html.in | 166 ---------------------------- docs/news.xml | 257 ++++++++++++++++++++++++++++++++++++++++++++ docs/news.xsl | 50 --------- 8 files changed, 456 insertions(+), 221 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 984ad070c2..7b71bd1593 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 50c358c30d..fa45388803 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 790c0a20ef..62e069e15e 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 0000000000..637c432d67 --- /dev/null +++ b/docs/news-ascii.xsl @@ -0,0 +1,68 @@ + + + + + + + + + libvirt releases +================ + + + +============================================================================== +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. + + + + + + +# + + ( + + ) + + + + + + + +* + + + + + + + + + + + + + + + + + - + + + + + + + + | + + + + + + diff --git a/docs/news-html.xsl b/docs/news-html.xsl new file mode 100644 index 0000000000..2961106d89 --- /dev/null +++ b/docs/news-html.xsl @@ -0,0 +1,96 @@ + + + + + + + + + <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + + + + + + + + + <!-- DO NOT EDIT THIS FILE! It was generated automatically. + Edit the source file (news.xml) instead --> + + +

Releases

+

This is the list of official releases for libvirt, along with an + overview of the changes introduced by each of them.

+

For a more fine-grained view, use the + git log. +

+ +

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 + 2016 and work your way back.

+ + + + + + +

+ + + ( + + ) + +

+
    + +
+ + + + +
  • + + + +
      + +
    +
    • +     + + + +
  • + + +
    • +     + + + + + + + + +
    + +     + + + + < + + > + + </ + + > + + +     diff --git a/docs/news.html.in b/docs/news.html.in deleted file mode 100644 index 90b400b674..0000000000 --- a/docs/news.html.in +++ /dev/null @@ -1,166 +0,0 @@ - - - - - - - -

    Releases

    -

    This is the list of official releases for libvirt, along with an - overview of the changes introduced by each of them.

    -

    For a more fine-grained view, use the - git log. -

    - -

    v3.0.0 (unreleased)

    - - -

    v2.5.0 (2016-12-04)

    - - -

    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 - 2016. -

    - - - diff --git a/docs/news.xml b/docs/news.xml new file mode 100644 index 0000000000..909b4ca9fd --- /dev/null +++ b/docs/news.xml @@ -0,0 +1,257 @@ + + + + + + +
    + + + New localPtr attribute for "ip" element in network XML + + + + + qemu: Support QEMU group I/O throttling + + + 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 + + + + + nss: Introduce libvirt-guest + + + New libvirt-guest nss module that translates libvirt + guest names into IP addresses + + + + + daemon: Add support for runtime logging settings adjustment + + + 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 + + + + + storage: Add virStorageVolInfoFlags API + + + 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 + + + + + libxl: Implement virDomainGetMaxVcpus API + + +
    +
    + + + perf: Add more perf statistics + + + 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 + + + + + conf: Display <physical> for volume xml + + + Add a display of the <physical> size of a disk + volume in the output of the volume XML + + + + + qemu: Use virtio-pci by default for aarch64 mach-virt guests + + + 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 + + +
    +
    + + + qemu: Correct GetBlockInfo values + + + 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 + + + + + qemu: Make virtio console usable on ppc64 guests + + + The chardev detection code has been improved and can now handle this + configuration properly + + + + + qemu: Enable mount namespace + + + To avoid funny races with udev relabelling devices under our hands and + to enhance security, libvirt now spawns each qemu process with its own + /dev. + + +
    +     + +
    + + + shmem: Add support for additional models + + + The shmem device can now utilize QEMU's ivshmem-plain and + ivshmem-doorbell, more modern versions of ivshmem + + + + + vbox: Add VirtualBox 5.1 support + + + + + libssh: New transport + + + The new libssh transport allows one to connect to a running + libvirtd via SSH, using the libssh library; for example: + qemu+libssh://server/system + + + + + vhost-scsi: Add support scsi_host hostdev passthrough + + + Add the capability to pass through a scsi_host HBA and the + associated LUNs to the guest + + + + + qemu: Users can now enable debug logging for native gluster + volumes in qemu using the "gluster_debug_level" option in qemu.conf + + + + + 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 + + + + + qemu: Express devices will be placed on PCIe bus by default + + + 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 + + +
    +
    + + + docs: Better documentation for migration APIs and flags + + + + + vbox: Address thread safety issues + + + + + virsh: Add support for passing an alternative persistent XML + to migrate command + + + + + vhostuser: Allow hotplug of multiqueue devices + + + + + NEWS: Switch to an improved format + + + List user-visible changes instead of single commits for a better + high-level overview of differences between libvirt releases + + + + + website: Modernize layout and branding + + + 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 + + +
    +
    + + + vz: Fix migration in P2P mode + + + + + Forbid newline character in names of some libvirt objects + + + + + Fix compilation on macOS + + +
    +     +     diff --git a/docs/news.xsl b/docs/news.xsl deleted file mode 100644 index 33506a977b..0000000000 --- a/docs/news.xsl +++ /dev/null @@ -1,50 +0,0 @@ - - - - - - libvirt releases -================ - - - - - - - - - - - # - - - - - - - - - - - - * - - - - - - - - - - - - - - - - - - -