From b0d1146e5e75292ee5d95f2f62c7177d5275471d Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.org>
Date: Sat, 8 Aug 2009 01:14:46 -0700
Subject: [PATCH] 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.
---
 debian/changelog |  4 ++++
 policy.sgml      | 30 +++++++++++++++---------------
 2 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 9dafa0e..0a01f52 100644
--- 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 50d28db..26f0357 100644
--- 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>
-- 
2.39.5