Add more strict rules for the news file and fix offending entries.
---
 docs/news.xml | 41 ++++++++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 13 deletions(-)

diff --git a/docs/news.xml b/docs/news.xml
index 17186b954..024b659e8 100644
--- a/docs/news.xml
+++ b/docs/news.xml
@@ -5,9 +5,20 @@
      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 -->
+     Keep the style consistent with existing entries as much as possible.
+
+     Each change should be documented by a short, one-sentence one-line summary.
+     The summary should not contain any formatting tags.
+
+     Optionally use a description where the change can be explained in more
+     detail. The description may contain a <code> tag for switching to
+     non-proportional font. No other tags are allowed.
+
+     Each <release> tag is required to contain at least one <section> tag and
+     each <section> tag is required to contain at least one <change> tag.
+
+     Lines should be kept under 80 columns, and should not exceed 100 columns.
+     -->

 <libvirt>
   <release version="v3.2.0" date="unreleased">
@@ -355,7 +366,7 @@
       </change>
       <change>
         <summary>
-          nss: Introduce <code>libvirt_guest</code>
+          nss: Introduce libvirt_guest
         </summary>
         <description>
           New <code>libvirt_guest</code> nss module that translates libvirt
@@ -615,7 +626,7 @@
         <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>.
+          <code>qemu+libssh://server/system</code>.
         </description>
       </change>
       <change>
@@ -629,17 +640,22 @@
       </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
+          Allow debugging of gluster volumes in qemu
         </summary>
+        <description>
+          Users can now enable debug logging for native gluster
+          volumes in qemu using the "gluster_debug_level" option in qemu.conf
+        </description>
       </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
+          Pre-allocate memory slots for memory hotplug
         </summary>
+        <description>
+          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
+        </description>
       </change>
       <change>
         <summary>
@@ -669,8 +685,7 @@
       </change>
       <change>
         <summary>
-          virsh: Add support for passing an alternative persistent XML
-          to migrate command
+          virsh: Add support for passing an alternative persistent XML to migrate command
         </summary>
       </change>
       <change>
-- 
2.12.1

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

On Tue, 2017-03-28 at 13:58 +0200, Peter Krempa wrote:
> Add more strict rules for the news file and fix offending entries.

s/more strict/stricter/

> ---
>  docs/news.xml | 41 ++++++++++++++++++++++++++++-------------
>  1 file changed, 28 insertions(+), 13 deletions(-)
> 
> diff --git a/docs/news.xml b/docs/news.xml
> index 17186b954..024b659e8 100644
> --- a/docs/news.xml
> +++ b/docs/news.xml
> @@ -5,9 +5,20 @@
>       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 -->
> +     Keep the style consistent with existing entries as much as possible.
> +
> +     Each change should be documented by a short, one-sentence one-line summary.
> +     The summary should not contain any formatting tags.

"one-sentence one-line" is rather clunky, I would suggest
rewording it along the lines of

  Each change should be documented by a short, one-sentence
  summary, which should fit in a single line and should not
  contain any formatting tags.

> +     Optionally use a description where the change can be explained in more
> +     detail.

I think something along the lines of

  You can optionally add a description if you feel like
  the summary alone is not enough to document the change
  accurately.

would work better here.

> The description may contain a <code> tag for switching to
> +     non-proportional font. No other tags are allowed.
> +
> +     Each <release> tag is required to contain at least one <section> tag and
> +     each <section> tag is required to contain at least one <change> tag.

I'm not sure the above two line are really needed. I would
omit them.


ACK if you take care of at least the commit message and the
first suggestion, I leave the remaining two up to you.

-- 
Andrea Bolognani / Red Hat / Virtualization

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list