Improve Description and Changes specification for *.changes

* Change the wording of the Description and Changes field specifications
  for *.changes files to more closely match the wording for Files and
  add more details about the contents of the Description field in
  a *.changes file.

diff --git a/debian/changelog b/debian/changelog
index 9dafa0edeb82f47acda47b689a0c48b0de87824a..0a01f52291be9638e2444b122cf7a0708d6a549c 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -61,6 +61,10 @@ debian-policy (3.8.3.0) UNRELEASED; urgency=low
     and that there is no updated list of copyright holders for subsequent
     revisions available.  (Partly addresses #47438)
   * Clarify the description of the Files control field and add examples.
+  * Change the wording of the Description and Changes field specifications
+    for *.changes files to more closely match the wording for Files and
+    add more details about the contents of the Description field in
+    a *.changes file.
   * Merge the package name syntax requirements between the Package and
     Source field descriptions.
 

diff --git a/policy.sgml b/policy.sgml
index 50d28dbd4a2549df0f27efccd6d0c7e45177e289..26f035771d9653d55ced215de08d8e577985f444 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -3101,18 +3101,16 @@ Package: libc6
          </p>
 
          <p>
-           In a <file>.changes</file> file, the <tt>Description</tt> field
-           contains a summary of the descriptions for the packages being
-           uploaded.
+           In a <file>.changes</file> file, the <tt>Description</tt>
+           field contains a summary of the descriptions for the packages
+           being uploaded.  For this caes, the first line of the field
+           value (the part on the same line as <tt>Description:</tt>) is
+           always empty.  The content of the field is expressed as
+           continuation lines, one line per package.  Each line is
+           indented by one space and contains the name of a binary
+           package, a space, a hyphen (<tt>-</tt>), a space, and the
+           short description line from that package.
          </p>
-
-         <p>
-           The part of the field before the first newline is empty;
-           thereafter each line has the name of a binary package and
-           the summary description line from that binary package.
-           Each line is indented by one space.
-         </p>
-
        </sect1>
 
        <sect1 id="f-Distribution">
@@ -3229,10 +3227,12 @@ Package: libc6
          </p>
 
          <p>
-           There should be nothing in this field before the first
-           newline; all the subsequent lines must be indented by at
-           least one space; blank lines must be represented by a line
-           consisting only of a space and a full stop.
+           The first line of the field value (the part on the same line
+           as <tt>Changes:</tt>) is always empty.  The content of the
+           field is expressed as continuation lines, with each line
+           indented by at least one space.  Blank lines must be
+           represented by a line consisting only of a space and a full
+           stop (<tt>.</tt>).
          </p>
 
          <p>