From 6b5ecb49b116555668ebdfc97d9586d5697bb6a8 Mon Sep 17 00:00:00 2001
From: Charles Plessy <plessy@debian.org>
Date: Sat, 29 May 2010 12:49:34 +0900
Subject: [PATCH] Clarification of the Format field in control files -- patch
 for #547272.

The Format field has a different meaning for Debian source control files and
Debian changes files. This patch :

 - documents the use and syntax of the Format field for these two types
   of control files.

 - Specifies the format 1.8 of Debian changes files, adds descriptions for
   the Checksums-Sha1 and Checksums-Sha256 files, and provides some history
   for the Closes, Changed-By and Maintainer fields.
---
 policy.sgml | 49 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 43 insertions(+), 6 deletions(-)

diff --git a/policy.sgml b/policy.sgml
index d489738..74f94e8 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2534,6 +2534,11 @@ Package: libc6
 	  (and version-dependent) information about a binary package.
 	</p>
 
+	<p>
+	  The structure of the Debian changes files is versionned, and
+	  this document describes the format 1.8.
+	</p>
+
 	<p>
 	  The fields in this file are:
 
@@ -2615,10 +2620,10 @@ Package: libc6
 	    <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
 	    <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
 	    <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (recommended)</item>
-	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref></item>
+	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory) <footnote>The meaning of that field changed in version 1.7.</footnote></item>
+	    <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref> <footnote>Introduced in format 1.7.</footnote></item>
 	    <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
-	    <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
+	    <item><qref id="f-Closes"><tt>Closes</tt></qref> <footnote>Introduced in format 1.6.</footnote></item>
 	    <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
 	    <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
 		and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
@@ -3259,13 +3264,25 @@ Package: libc6
 	  <heading><tt>Format</tt></heading>
 
 	  <p>
-	    This field specifies a format revision for the file.
-	    The most current format described in the Policy Manual
-	    is version <strong>1.5</strong>.  The syntax of the
+	    In <qref id="debianchangesfiles">changes</qref> files, this field
+	    specifies a format revision for the file. The syntax of the
 	    format value is the same as that of a package version
 	    number except that no epoch or Debian revision is allowed
 	    - see <ref id="f-Version">.
 	  </p>
+
+	  <p>
+	    In <qref id="debiansourcecontrolfiles"> Debian source control</qref>
+	    files, this field specifies a format revision for the source package.
+	    The syntax of the format value is the same as that of a package version
+	    number, except that no epoch or Debian revision is allowed
+	    and that it can optionally be followed by a parenthesis with a name
+	    <footnote>dpkg-source uses the major number and the content of the
+	    parenthesis to decide which perl module to use to build or unpack
+	    the source package. For instance, Dpkg::Source::Package::V1 for format
+	    1.0 and Dpkg::Source::Package::V3::quilt for format 3.0 (quilt)
+	    </footnote>.
+	  <p>
 	</sect1>
 
 	<sect1 id="f-Urgency">
@@ -3526,6 +3543,26 @@ Checksums-Sha256:
 	  </p>
 	</sect1>
 
+	<sect1 id="f-Checksums-Sha1">
+	  <heading><tt>Checksums-Sha1</tt></heading>
+
+	  <p>
+	    This field is similar to the <qref id="f-Files">Files</qref>
+	    field, except that it uses the Sha1 algorithm instead of MD5
+	    for the checksums.
+	  </p>
+	</sect1>
+
+	<sect1 id="f-Checksums-Sha256">
+	  <heading><tt>Checksums-Sha256</tt></heading>
+
+	  <p>
+	    This field is similar to the <qref id="f-Files">Files</qref>
+	    field, except that it uses the Sha1 algorithm instead of MD5
+	    for the checksums.
+	  </p>
+	</sect1>
+
       </sect>
 
       <sect>
-- 
2.39.2