Bug#547272: Clarification of the Format field in control files
charles@kunpuu.plessy.org (Charles Plessy) writes:
> 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.
Thanks, Charles! Here's a somewhat modified version of that patch which I
propose. Changes:
* I don't think the history of the .changes format is something we should
try to maintain in Policy. There's a lot of other history information
that we're not currently maintaining, and I have a hard time seeing when
anyone would really care. If we get better at maintaining this going
forward, people will be able to see the history from upgrading-checklist
and the Policy repository. I therefore dropped the version footnotes.
* The Checksums-* fields were documented as part of a separate bug, so I
dropped those changes.
* I thought referring to the Version field for the syntax of .dsc Format
fields was a bit confusing since that field doesn't really behave like a
version number and has things both removed and added to the syntax, so I
just wrote the syntax description out separately. I also added a
footnote specifying the currently supported source package versions and
removed the information specific to the current dpkg-source
implementation method, since it seemed a bit too specific for Policy to
me.
Charles, are you happy with those changes? Everyone else, objections or
seconds?
diff --git a/policy.sgml b/policy.sgml
index d489738..77850d6 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2595,15 +2595,21 @@ Package: libc6
<heading>Debian changes files -- <file>.changes</file></heading>
<p>
- The .changes files are used by the Debian archive maintenance
- software to process updates to packages. They contain one
- paragraph which contains information from the
+ The <file>.changes</file> files are used by the Debian archive
+ maintenance software to process updates to packages. They
+ contain one paragraph which contains information from the
<tt>debian/control</tt> file and other data about the
source package gathered via <tt>debian/changelog</tt>
and <tt>debian/rules</tt>.
</p>
<p>
+ <file>.changes</file> files have a format version that is
+ incremented whenever the documented fields or their meaning
+ change. This document describes format 1.8.
+ </p>
+
+ <p>
The fields in this file are:
<list compact="compact">
@@ -3259,12 +3265,29 @@ 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
- 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">.
+ In <qref id="debianchangesfiles"><file>.changes</file></qref>
+ files, this field declares the format version of that file.
+ The syntax of the field value is the same as that of
+ a <qref id="f-Version">package version number</qref> except
+ that no epoch or Debian revision is allowed. The format
+ described in this document is <tt>1.8</tt>.
+ </p>
+
+ <p>
+ In <qref id="debiansourcecontrolfiles"> Debian source
+ control</qref> files, this field declares the format of the
+ source package. The field value is used by programs acting on
+ a source package to interpret the list of files in the source
+ package and determine how to unpack it. The syntax of the
+ field value is a numeric major revision, a period, a numeric
+ minor revision, and then an optional subtype after whitespace,
+ which if specified is an alphanumeric word in parentheses.
+ The subtype is optional in the syntax but may be mandatory for
+ particular source format revisions.<footnote>
+ The source formats currently supported by the Debian archive
+ software are <tt>1.0</tt>, <tt>3.0 (native)</tt>,
+ and <tt>3.0 (quilt)</tt>.
+ </footnote>
</p>
</sect1>
@@ -3525,7 +3548,6 @@ Checksums-Sha256:
must match the list of files in the <tt>Files</tt> field.
</p>
</sect1>
-
</sect>
<sect>
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: