Bug#647570: debian-policy: Conformance of Chapter 5 to RFC 2119.
Package: debian-policy
Version: 3.9.2.0
Severity: wishlist
Dear all,
following our discussion at the end of October about the vocabulary used in the
Policy, (20111025143614.GB14464@merveille.plessy.net), here is a first pass on
Chapter 5, to use the vocabulary of RFC 2119 (http://www.ietf.org/rfc/rfc2119.txt)
where applicable.
I am presenting my proposition as a patch for the words that change, and as a
serie of extracts centered on the words that do not change.
In most cases the change is a capitalisation, but in a few cases the words
themselves change, where for instance ‘may (not)’ becomes ‘MUST (NOT)’. I
focused on the key words defined by the RFC, with the exception of ‘mandatory’,
which I propose to change to ‘REQUIRED’ as it was used in the context other
‘RECOMMENDED’ key words. I also propose to change a ‘must never’ to ‘MUST NOT’.
I also made sure that ‘MUST NOT’ and ‘SHOULD NOT’ are never interrupted by a
new line, to facilitate searches in the source document.
@@ -2479,9 +2479,9 @@ endif
fields<footnote>
The paragraphs are also sometimes referred to as stanzas.
</footnote>.
- The paragraphs are separated by empty lines. Parsers may accept
+ The paragraphs are separated by empty lines. Parsers MAY accept
lines consisting solely of spaces and tabs as paragraph
- separators, but control files should use empty lines. Some control
+ separators, but control files SHOULD use empty lines. Some control
files allow only one paragraph; others allow several, in
which case each paragraph usually refers to a different
package. (For example, in source packages, the first
@@ -2496,10 +2496,10 @@ endif
then the data/value associated with that field. The field
name is composed of printable ASCII characters (i.e.,
characters that have values between 33 and 126, inclusive)
- except colon and must not with a begin with #. The
+ except colon and MUST NOT with a begin with #. The
field ends at the end of the line or at the end of the
last continuation line (see below). Horizontal whitespace
- (spaces and tabs) may occur immediately before or after the
+ (spaces and tabs) MAY occur immediately before or after the
value and is ignored there; it is conventional to put a
single space after the colon. For example, a field might
be:
@@ -2511,7 +2511,7 @@ Package: libc6
</p>
<p>
- A paragraph must not contain more than one instance of a
+ A paragraph MUST NOT contain more than one instance of a
particular field name.
</p>
@@ -2520,16 +2520,16 @@ Package: libc6
<taglist>
<tag>simple</tag>
<item>
- The field, including its value, must be a single line. Folding
+ The field, including its value, MUST be a single line. Folding
of the field is not permitted. This is the default field type
if the definition of the field does not specify a different
type.
</item>
<tag>folded</tag>
<item>
- The value of a folded field is a logical line that may span
+ The value of a folded field is a logical line that MAY span
several lines. The lines after the first are called
- continuation lines and must start with a space or a tab.
+ continuation lines and MUST start with a space or a tab.
Whitespace, including any newlines, is not significant in the
field values of folded fields.<footnote>
This folding method is similar to RFC 5322, allowing control
@@ -2539,7 +2539,7 @@ Package: libc6
</item>
<tag>multiline</tag>
<item>
- The value of a multiline field may comprise multiple continuation
+ The value of a multiline field MAY comprise multiple continuation
lines. The first line of the value, the part on the same line as
the field name, often has special significance or may have to be
empty. Other lines are added following the same syntax as the
@@ -2550,7 +2550,7 @@ Package: libc6
</p>
<p>
- Whitespace must not appear
+ Whitespace MUST NOT appear
inside names (of packages, architectures, files or anything
else) or version numbers, or between the characters of
multi-character version relationships.
@@ -2583,7 +2583,7 @@ Package: libc6
</p>
<p>
- All control files must be encoded in UTF-8.
+ All control files MUST be encoded in UTF-8.
</p>
</sect>
@@ -2607,15 +2607,15 @@ Package: libc6
package) are:
<list compact="compact">
- <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
- <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
- <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
- <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
- <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
- <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
- <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
- <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="f-Source"><tt>Source</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-Section"><tt>Section</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="f-Priority"><tt>Priority</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref> (OPTIONAL)</item>
+ <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref> (OPTIONAL)</item>
</list>
</p>
@@ -2623,14 +2623,14 @@ Package: libc6
The fields in the binary package paragraphs are:
<list compact="compact">
- <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
- <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
- <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
- <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
- <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
- <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
- <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
- <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="f-Package"><tt>Package</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Section"><tt>Section</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="f-Priority"><tt>Priority</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="f-Essential"><tt>Essential</tt></qref> (OPTIONAL)</item>
+ <item><qref id="binarydeps"><tt>Depends</tt> et al</qref> (OPTIONAL)</item>
+ <item><qref id="f-Description"><tt>Description</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref> (OPTIONAL)</item>
</list>
</p>
@@ -2653,7 +2653,7 @@ Package: libc6
</p>
<p>
- The fields here may contain variable references - their
+ The fields here MAY contain variable references - their
values will be substituted by <prgn>dpkg-gencontrol</prgn>,
<prgn>dpkg-genchanges</prgn> or <prgn>dpkg-source</prgn>
when they generate output control files.
@@ -2674,18 +2674,18 @@ Package: libc6
The fields in this file are:
<list compact="compact">
- <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
- <item><qref id="f-Source"><tt>Source</tt></qref></item>
- <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
- <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
- <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
- <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
- <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
- <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
- <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
- <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
- <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
- <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="f-Package"><tt>Package</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Source"><tt>Source</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Section"><tt>Section</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="f-Priority"><tt>Priority</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Essential"><tt>Essential</tt></qref> (OPTIONAL)</item>
+ <item><qref id="binarydeps"><tt>Depends</tt> et al</qref> (OPTIONAL)</item>
+ <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Description"><tt>Description</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref> (OPTIONAL)</item>
</list>
</p>
</sect>
@@ -2699,20 +2699,20 @@ Package: libc6
Their syntax is described above, in <ref id="pkg-controlfields">.
<list compact="compact">
- <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
- <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
- <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
- <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
- <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
- <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
- <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
- <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
- <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
- <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
+ <item><qref id="f-Format"><tt>Format</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Source"><tt>Source</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Binary"><tt>Binary</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref> (OPTIONAL)</item>
<item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
- and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
- <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+ and <tt>Checksums-Sha256</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="f-Files"><tt>Files</tt></qref> (REQUIRED)</item>
</list>
</p>
@@ -2750,22 +2750,22 @@ Package: libc6
The fields in this file are:
<list compact="compact">
- <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
- <item><qref id="f-Date"><tt>Date</tt></qref> (mandatory)</item>
- <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
- <item><qref id="f-Binary"><tt>Binary</tt></qref> (mandatory)</item>
- <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
- <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-Description"><tt>Description</tt></qref> (mandatory)</item>
- <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
- <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
+ <item><qref id="f-Format"><tt>Format</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Date"><tt>Date</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Source"><tt>Source</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Binary"><tt>Binary</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-Description"><tt>Description</tt></qref> (REQUIRED)</item>
+ <item><qref id="f-Closes"><tt>Closes</tt></qref> (OPTIONAL)</item>
+ <item><qref id="f-Changes"><tt>Changes</tt></qref> (REQUIRED)</item>
<item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
- and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
- <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+ and <tt>Checksums-Sha256</tt></qref> (RECOMMENDED)</item>
+ <item><qref id="f-Files"><tt>Files</tt></qref> (REQUIRED)</item>
</list>
</p>
</sect>
@@ -2782,31 +2782,31 @@ Package: libc6
<p>
In <file>debian/control</file> or a <file>.dsc</file> file,
- this field must contain only the name of the source package.
+ this field MUST contain only the name of the source package.
</p>
<p>
In a binary package control file or a <file>.changes</file>
- file, the source package name may be followed by a version
+ file, the source package name MAY be followed by a version
number in parentheses<footnote>
It is customary to leave a space after the package name
if a version number is specified.
</footnote>.
- This version number may be omitted (and is, by
+ This version number MAY be omitted (and is, by
<prgn>dpkg-gencontrol</prgn>) if it has the same value as
the <tt>Version</tt> field of the binary package in
- question. The field itself may be omitted from a binary
+ question. The field itself MAY be omitted from a binary
package control file when the source package has the same
name and version as the binary package.
</p>
<p>
Package names (both source and binary,
- see <ref id="f-Package">) must consist only of lower case
+ see <ref id="f-Package">) MUST consist only of lower case
letters (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus
(<tt>+</tt>) and minus (<tt>-</tt>) signs, and periods
- (<tt>.</tt>). They must be at least two characters long and
- must start with an alphanumeric character.
+ (<tt>.</tt>). They MUST be at least two characters long and
+ MUST start with an alphanumeric character.
</p>
</sect1>
@@ -2815,7 +2815,7 @@ Package: libc6
<p>
The package maintainer's name and email address. The name
- must come first, then the email address inside angle
+ MUST come first, then the email address inside angle
brackets <tt><></tt> (in RFC822 format).
</p>
@@ -2844,15 +2844,15 @@ Package: libc6
the one named in the <qref id="f-Maintainer">Maintainer
field</qref>, their names and email addresses should be listed
here. The format of each entry is the same as that of the
- Maintainer field, and multiple entries must be comma
+ Maintainer field, and multiple entries MUST be comma
separated.
</p>
<p>
- This is normally an optional field, but if
+ This is normally an OPTIONAL field, but if
the <tt>Maintainer</tt> control field names a group of people
- and a shared email address, the <tt>Uploaders</tt> field must
- be present and must contain at least one human with their
+ and a shared email address, the <tt>Uploaders</tt> field MUST
+ be present and MUST contain at least one human with their
personal email address.
</p>
@@ -2914,7 +2914,7 @@ Package: libc6
</p>
<p>
- Binary package names must follow the same syntax and
+ Binary package names MUST follow the same syntax and
restrictions as source package names. See <ref id="f-Source">
for the details.
</p>
@@ -2954,7 +2954,7 @@ Package: libc6
value <tt>all</tt>, the special architecture
wildcard <tt>any</tt>, or a list of specific and wildcard
architectures separated by spaces. If <tt>all</tt>
- or <tt>any</tt> appears, that value must be the entire
+ or <tt>any</tt> appears, that value MUST be the entire
contents of the field. Most packages will use
either <tt>all</tt> or <tt>any</tt>.
</p>
@@ -3028,8 +3028,8 @@ Package: libc6
package is also being uploaded, the special
entry <tt>source</tt> is also present. <tt>all</tt> will be
present if any architecture-independent packages are being
- uploaded. Architecture wildcards such as <tt>any</tt> must
- never occur in the <tt>Architecture</tt> field in
+ uploaded. Architecture wildcards such as <tt>any</tt>
+ MUST NOT occur in the <tt>Architecture</tt> field in
the <file>.changes</file> file.
</p>
@@ -3043,7 +3043,7 @@ Package: libc6
<heading><tt>Essential</tt></heading>
<p>
- This is a boolean field which may occur only in the
+ This is a boolean field which MAY occur only in the
control file of a binary package or in a per-package fields
paragraph of a source package control file.
</p>
@@ -3097,7 +3097,7 @@ Package: libc6
Thus only the first three components of the policy version
are significant in the <em>Standards-Version</em> control
field, and so either these three components or all four
- components may be specified.<footnote>
+ components MAY be specified.<footnote>
In the past, people specified the full version number
in the Standards-Version field, for example "2.3.0.0".
Since minor patch-level changes don't introduce new
@@ -3125,8 +3125,8 @@ Package: libc6
<item>
<p>
This is a single (generally small) unsigned integer. It
- may be omitted, in which case zero is assumed. If it is
- omitted then the <var>upstream_version</var> may not
+ MAY be omitted, in which case zero is assumed. If it is
+ omitted then the <var>upstream_version</var> MUST NOT
contain any colons.
</p>
@@ -3154,17 +3154,17 @@ Package: libc6
The comparison behavior of the package management system
with respect to the <var>upstream_version</var> is
described below. The <var>upstream_version</var>
- portion of the version number is mandatory.
+ portion of the version number is REQUIRED.
</p>
<p>
- The <var>upstream_version</var> may contain only
+ The <var>upstream_version</var> MUST contain only
alphanumerics<footnote>
Alphanumerics are <tt>A-Za-z0-9</tt> only.
</footnote>
and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
<tt>:</tt> <tt>~</tt> (full stop, plus, hyphen, colon,
- tilde) and should start with a digit. If there is no
+ tilde) and SHOULD start with a digit. If there is no
<var>debian_revision</var> then hyphens are not allowed;
if there is no <var>epoch</var> then colons are not
allowed.
@@ -3176,7 +3176,7 @@ Package: libc6
<p>
This part of the version number specifies the version of
the Debian package based on the upstream version. It
- may contain only alphanumerics and the characters
+ MUST contain only alphanumerics and the characters
<tt>+</tt> <tt>.</tt> <tt>~</tt> (plus, full stop,
tilde) and is compared in the same way as the
<var>upstream_version</var> is.
@@ -3184,7 +3184,7 @@ Package: libc6
<p>
It is optional; if it isn't present then the
- <var>upstream_version</var> may not contain a hyphen.
+ <var>upstream_version</var> MUST NOT contain a hyphen.
This format represents the case where a piece of
software was written specifically to be a Debian
package, where the Debian package source must always
@@ -3310,7 +3310,7 @@ Package: libc6
horizontally, the displaying program will line wrap them "hard"
(i.e., without taking account of word breaks). If it can they
will be allowed to trail off to the right. None, one or two
- initial spaces may be deleted, but the number of spaces
+ initial spaces MAY be deleted, but the number of spaces
deleted from each line will be the same (so that you can have
indenting work correctly, for example).
</item>
@@ -3404,7 +3404,7 @@ Package: libc6
<p>
This field includes the date the package was built or last
- edited. It must be in the same format as the <var>date</var>
+ edited. It MUST be in the same format as the <var>date</var>
in a <file>debian/changelog</file> entry.
</p>
@@ -3462,7 +3462,7 @@ Package: libc6
gives an indication of the importance of any fixes included
in the upload. <tt>Emergency</tt> and <tt>critical</tt> are
treated as synonymous.
- </footnote> (not case-sensitive) followed by an optional
+ </footnote> (not case-sensitive) followed by an OPTIONAL
commentary (separated by a space) which is usually in
parentheses. For example:
@@ -3491,7 +3491,7 @@ Package: libc6
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
+ 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>
@@ -3503,15 +3503,15 @@ Package: libc6
</p>
<p>
- Each version's change information should be preceded by a
+ Each version's change information SHOULD be preceded by a
"title" line giving at least the version, distribution(s)
and urgency, in a human-readable way.
</p>
<p>
If data from several versions is being returned the entry
- for the most recent version should be returned first, and
- entries should be separated by the representation of a
+ for the most recent version SHOULD be returned first, and
+ entries SHOULD be separated by the representation of a
blank line (the "title" line may also be followed by the
representation of a blank line).
</p>
@@ -3576,7 +3576,7 @@ Package: libc6
In all cases, Files is a multiline field. The first line of
the field value (the part on the same line as <tt>Files:</tt>)
is always empty. The content of the field is expressed as
- continuation lines, one line per file. Each line must be
+ continuation lines, one line per file. Each line MUST be
indented by one space and contain a number of sub-fields,
separated by spaces, as described below.
</p>
@@ -3611,7 +3611,7 @@ Files:
The <qref id="f-Section">section</qref>
and <qref id="f-Priority">priority</qref> are the values of
the corresponding fields in the main source control file. If
- no section or priority is specified then <tt>-</tt> should be
+ no section or priority is specified then <tt>-</tt> SHOULD be
used, though section and priority values must be specified for
new packages to be installed properly.
</p>
@@ -3621,18 +3621,18 @@ Files:
<tt>.changes</tt> file indicates that the file in question
is not an ordinary package file and must by installed by
hand by the distribution maintainers. If the section is
- <tt>byhand</tt> the priority should be <tt>-</tt>.
+ <tt>byhand</tt> the priority SHOULD be <tt>-</tt>.
</p>
<p>
If a new Debian revision of a package is being shipped and
no new original source archive is being distributed the
- <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+ <tt>.dsc</tt> MUST still contain the <tt>Files</tt> field
entry for the original source archive
<file><var>package</var>_<var>upstream-version</var>.orig.tar.gz</file>,
- but the <file>.changes</file> file should leave it out. In
+ but the <file>.changes</file> file SHOULD leave it out. In
this case the original source archive on the distribution
- site must match exactly, byte-for-byte, the original
+ site MUST match exactly, byte-for-byte, the original
source archive which was used to generate the
<file>.dsc</file> file and diff which are being uploaded.</p>
</sect1>
@@ -3696,11 +3696,11 @@ Checksums-Sha256:
</p>
<p>
- In the <file>.dsc</file> file, these fields should list all
+ In the <file>.dsc</file> file, these fields SHOULD list all
files that make up the source package. In
- the <file>.changes</file> file, these fields should list all
+ the <file>.changes</file> file, these fields SHOULD list all
files being uploaded. The list of files in these fields
- must match the list of files in the <tt>Files</tt> field.
+ MUST match the list of files in the <tt>Files</tt> field.
</p>
</sect1>
@@ -3709,7 +3709,7 @@ Checksums-Sha256:
<p>
The most recent version of a package uploaded to unstable or
- experimental must include the field <tt>DM-Upload-Allowed:
+ experimental MUST include the field <tt>DM-Upload-Allowed:
yes</tt> in the source section of its source control file for
the Debian archive to accept uploads signed with a key in the
Debian Maintainer keyring. See the General
@@ -3724,7 +3724,7 @@ Checksums-Sha256:
<heading>User-defined fields</heading>
<p>
- Additional user-defined fields may be added to the
+ Additional user-defined fields MAY be added to the
source package control file. Such fields will be
ignored, and not copied to (for example) binary or
Debian source control files or upload control files.
Here are the occurences of ‘must’ that I did not feel like or was unsure about
changing to upper case.
<p>
If the maintainer's name contains a full stop then the
whole field will not work directly as an email address due
to a misfeature in the syntax specified in RFC822; a
program using this field as an address must check for this
and correct the problem if necessary (for example by
putting the name in round brackets and moving it to the
end, and bringing the email address forward).
</p>
--
<p>
It is optional; if it isn't present then the
<var>upstream_version</var> MUST NOT contain a hyphen.
This format represents the case where a piece of
software was written specifically to be a Debian
package, where the Debian package source must always
be identical to the pristine source and therefore no
revision indication is required.
</p>
<p>
--
</example>
The <qref id="f-Section">section</qref>
and <qref id="f-Priority">priority</qref> are the values of
the corresponding fields in the main source control file. If
no section or priority is specified then <tt>-</tt> SHOULD be
used, though section and priority values must be specified for
new packages to be installed properly.
</p>
<p>
The special value <tt>byhand</tt> for the section in a
<tt>.changes</tt> file indicates that the file in question
is not an ordinary package file and must by installed by
hand by the distribution maintainers. If the section is
<tt>byhand</tt> the priority SHOULD be <tt>-</tt>.
</p>
For ‘should’:
<p>
List of the names and email addresses of co-maintainers of the
package, if any. If the package has other maintainers besides
the one named in the <qref id="f-Maintainer">Maintainer
field</qref>, their names and email addresses should be listed
here. The format of each entry is the same as that of the
Maintainer field, and multiple entries MUST be comma
separated.
</p>
--
architecture-dependent package on only those architectures
that match any of the specified architecture wildcards.
Specifying a list of architectures or architecture wildcards
other than <tt>any</tt> is for the minority of cases where a
program is not portable or is not useful on some
architectures. Where possible, the program should be made
portable instead.
</p>
<p>
In the Debian source control file <file>.dsc</file>, this
--
the <file>debian/control</file> in the source package.
</p>
<p>
Specifying only <tt>any</tt> indicates that the source package
isn't dependent on any particular architecture and should
compile fine on any one. The produced binary package(s)
will be specific to whatever the current build architecture is.
</p>
<p>
--
<heading><tt>Distribution</tt></heading>
<p>
In a <file>.changes</file> file or parsed changelog output
this contains the (space-separated) name(s) of the
distribution(s) where this version of the package should
be installed. Valid distributions are determined by the
archive maintainers.<footnote>
Example distribution names in the Debian archive used in
<file>.changes</file> files are:
<taglist compact="compact">
--
Debian source control files or upload control files.
</p>
<p>
If you wish to add additional unsupported fields to
these output files you should use the mechanism
described here.
</p>
<p>
Fields in the main source control information file with
For ‘may’:
</item>
<tag>multiline</tag>
<item>
The value of a multiline field MAY comprise multiple continuation
lines. The first line of the value, the part on the same line as
the field name, often has special significance or may have to be
empty. Other lines are added following the same syntax as the
continuation lines of the folded fields. Whitespace, including newlines,
is significant in the values of multiline fields.
</item>
</taglist>
--
multi-character version relationships.
</p>
<p>
The presence and purpose of a field, and the syntax of its
value may differ between types of control files.
</p>
<p>
Field names are not case-sensitive, but it is usual to
capitalize the field names using mixed case as shown below.
--
</list>
</p>
<p>
In the main <file>debian/control</file> file in the source
package, this field may contain the special
value <tt>all</tt>, the special architecture
wildcard <tt>any</tt>, or a list of specific and wildcard
architectures separated by spaces. If <tt>all</tt>
or <tt>any</tt> appears, that value MUST be the entire
contents of the field. Most packages will use
--
architecture wildcard <tt>any</tt>, the only other value
allowed in the list is <tt>all</tt>.
</p>
<p>
The list may include (or consist solely of) the special
value <tt>all</tt>. In other words, in <file>.dsc</file>
files unlike the <file>debian/control</file>, <tt>all</tt> may
occur in combination with specific architectures.
The <tt>Architecture</tt> field in the Debian source control
file <file>.dsc</file> is generally constructed from
the <tt>Architecture</tt> fields in
the <file>debian/control</file> in the source package.
--
in the Standards-Version field, for example "2.3.0.0".
Since minor patch-level changes don't introduce new
policy, it was thought it would be better to relax
policy and only require the first 3 components to be
specified, in this example "2.3.0". All four
components may still be used if someone wishes to do so.
</footnote>
</p>
</sect1>
--
This is the main part of the version number. It is
usually the version number of the original ("upstream")
package from which the <file>.deb</file> file has been made,
if this is applicable. Usually this will be in the same
format as that specified by the upstream author(s);
however, it may need to be reformatted to fit into the
package management system's format and comparison
scheme.
</p>
<p>
--
</p>
<p>
First the initial part of each string consisting entirely of
non-digit characters is determined. These two parts (one of
which may be empty) are compared lexically. If a difference
is found it is returned. The lexical comparison is a
comparison of ASCII values modified so that all the letters
sort earlier than all the non-letters and so that a tilde
sorts before anything, even the end of a part. For example,
the following parts are in sorted order from earliest to
--
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>.
--
<p>
If data from several versions is being returned the entry
for the most recent version SHOULD be returned first, and
entries SHOULD be separated by the representation of a
blank line (the "title" line may also be followed by the
representation of a blank line).
</p>
</sect1>
<sect1 id="f-Binary">
--
<p>
This field appears in the control files of binary packages,
and in the <file>Packages</file> files. It gives an estimate
of the total amount of disk space required to install the
named package. Actual installed size may vary based on block
size, file system properties, or actions taken by package
maintainer scripts.
</p>
<p>
--
<p>
The URL of the web site for this package, preferably (when
applicable) the site from which the original source can be
obtained and any additional upstream documentation or
information may be found. The content of this field is a
simple URL without any surrounding characters such as
<tt><></tt>.
</p>
</sect1>
For ‘required’:
<var>upstream_version</var> MUST NOT contain a hyphen.
This format represents the case where a piece of
software was written specifically to be a Debian
package, where the Debian package source must always
be identical to the pristine source and therefore no
revision indication is required.
</p>
<p>
It is conventional to restart the
<var>debian_revision</var> at <tt>1</tt> each time the
--
<heading><tt>Installed-Size</tt></heading>
<p>
This field appears in the control files of binary packages,
and in the <file>Packages</file> files. It gives an estimate
of the total amount of disk space required to install the
named package. Actual installed size may vary based on block
size, file system properties, or actions taken by package
maintainer scripts.
</p>
For ‘optional’:
tilde) and is compared in the same way as the
<var>upstream_version</var> is.
</p>
<p>
It is optional; if it isn't present then the
<var>upstream_version</var> MUST NOT contain a hyphen.
This format represents the case where a piece of
software was written specifically to be a Debian
package, where the Debian package source must always
be identical to the pristine source and therefore no
--
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>.
I did my best, but I would be surprised to have been completely accurate on the
first attempt, so your critical comments are more than welcome.
Have a nice day,
--
Charles
Reply to: