Bug#547272: Clarification of the Format field in control files
Charles Plessy <plessy@debian.org> writes:
> I wonder if it is a good thing to have the format version number given
> two times. How about removing one instance, or adding SGML comments
> warning that modification has to be done in two places? Or using a SGML
> entity?
An SGML entity seems like a good idea.
> I also think that it makes the Policy clearer if it uses consistently
> one terminology. We have the choice between the short names that is
> used in most discussions on the Debian mailing lists (.changes, .dsc,
> debian/control), and the longer names that are not much used outside the
> Policy (Source package control, Binary package control, Debian source
> control, and Debian changes files).
> One problem of the short/causal names it that debian/control and
> DEBIAN/control are spoken the same (although it would be interesting to
> distinguish them by shouting Debian in the second case). Not to mention
> that “Debian control file” is (although not in practice) a vague term,
> since the Policy also sometimes refer to files like postinst as “control
> files”.
Everything in the DEBIAN directory of a binary package is a control file,
yes.
> So despite this does not reflect the practice in electronic
> communications, I would recommend to use the more formal long names to
> refer to the control data files of source and binary packages.
The problem there is "Debian source control file" is also very confusing,
since it sounds like it might be referring to debian/control in an
unpacked source package. Policy mostly refers to .changes and .dsc
files. I've added .dsc to the file name in the relevant bit of the
proposed patch.
> Ah, and lastly, here are two minor comments:
>> <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>
> Is there a reason for using a <file> markup for the .changes file, but a
> <tt> markup for debian/control, debian/changelog, and debian/rules?
Thanks, fixed those too, and one other instance that I noticed.
> More cosmetically, if the Debian changes file are always made of one
> paragraph only, perhaps we can avoid the repetition of ‘contain’ (‘They
> contain one paragraph which contains’) with the following sentence in
> replacement:
> “They consist in a single paragraph which which contains…”
I fiddled with this section and noted that it may also have a PGP
signature, and made similar changes to the .dsc section. I also added a
note that the binary package control file is also limited to a single
paragraph.
Here's an updated version of the proposed patch.
diff --git a/policy.sgml b/policy.sgml
index d489738..abb1a8e 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2,6 +2,8 @@
<!-- include version information so we don't have to hard code it
within the document -->
<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+<!-- current Debian changes file format -->
+<!entity changesversion "1.8">
]>
<debiandoc>
@@ -2497,7 +2499,7 @@ Package: libc6
These fields are used by <prgn>dpkg-gencontrol</prgn> to
generate control files for binary packages (see below), by
<prgn>dpkg-genchanges</prgn> to generate the
- <tt>.changes</tt> file to accompany the upload, and by
+ <file>.changes</file> file to accompany the upload, and by
<prgn>dpkg-source</prgn> when it creates the
<file>.dsc</file> source control file as part of a source
archive. Many fields are permitted to span multiple lines in
@@ -2531,7 +2533,8 @@ Package: libc6
<p>
The <file>DEBIAN/control</file> file contains the most vital
- (and version-dependent) information about a binary package.
+ (and version-dependent) information about a binary package. It
+ consists of a single paragraph.
</p>
<p>
@@ -2558,10 +2561,9 @@ Package: libc6
<heading>Debian source control files -- <tt>.dsc</tt></heading>
<p>
- This file contains a series of fields, identified and
- separated just like the fields in the control file of
- a binary package. The fields are listed below; their
- syntax is described above, in <ref id="pkg-controlfields">.
+ This file consists of a single paragraph, possibly surrounded by
+ a PGP signature. The fields of that paragraph are listed below.
+ Their syntax is described above, in <ref id="pkg-controlfields">.
<list compact="compact">
<item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
@@ -2595,12 +2597,19 @@ 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
- <tt>debian/control</tt> file and other data about the
- source package gathered via <tt>debian/changelog</tt>
- and <tt>debian/rules</tt>.
+ The <file>.changes</file> files are used by the Debian archive
+ maintenance software to process updates to packages. They
+ consist of a single paragraph, possibly surrounded by a PGP
+ signature. That paragraph contains information from the
+ <file>debian/control</file> file and other data about the
+ source package gathered via <file>debian/changelog</file>
+ and <file>debian/rules</file>.
+ </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 &changesversion;.
</p>
<p>
@@ -3259,12 +3268,30 @@ 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>&changesversion;</tt>.
+ </p>
+
+ <p>
+ In <qref id="debiansourcecontrolfiles"><file>.dsc</file>
+ 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 +3552,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: