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.gb14...@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 -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
