<enumlist>
<item>Russ Allbery</item>
<item>Bill Allombert</item>
- <item>Andrew McMillan</item>
- <item>Manoj Srivastava</item>
- <item>Colin Watson</item>
+ <item>Andreas Barth</item>
+ <item>Jonathan Nieder</item>
</enumlist>
</p>
<p>
The maintainer name and email address used in the changelog
- should be the details of the person uploading <em>this</em>
- version. They are <em>not</em> necessarily those of the
- usual package maintainer.<footnote>
- If the developer uploading the package is not one of the usual
- maintainers of the package (as listed in
+ should be the details of the person who prepared this release of
+ the package. They are <em>not</em> necessarily those of the
+ uploader or usual package maintainer.<footnote>
+ In the case of a sponsored upload, the uploader signs the
+ files, but the changelog maintainer name and address are those
+ of the person who prepared this release. If the preparer of
+ the release is not one of the usual maintainers of the package
+ (as listed in
the <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
or <qref id="f-Uploaders"><tt>Uploaders</tt></qref> control
fields of the package), the first line of the changelog is
any target that these targets depend on must also be
non-interactive.
</p>
+ <p>
+ For packages in the main archive, no required targets
+ may attempt network access.
+ </p>
<p>
The targets are as follows:
This is an optional, recommended configuration file for the
<tt>uscan</tt> utility which defines how to automatically scan
ftp or http sites for newly available updates of the
- package. This is used
- by <url id="http://dehs.alioth.debian.org/"> and other Debian QA
+ package. This is used Debian QA
tools to help with quality control and maintenance of the
distribution as a whole.
</p>
composed of US-ASCII characters excluding control characters,
space, and colon (i.e., characters in the ranges 33-57 and
59-126, inclusive). Field names must not begin with the comment
- character, <tt>#</tt>.
+ character, <tt>#</tt>, nor with the hyphen character, <tt>-</tt>.
</p>
<p>
the field name is <tt>Package</tt> and the field value
<tt>libc6</tt>.
</p>
-
+ <p> Empty field values are only permitted in source package control files
+ (<file>debian/control</file>). Such fields are ignored.
+ </p>
<p>
A paragraph must not contain more than one instance of a
particular field name.
file. These tools are responsible for removing the line
breaks from such fields when using fields from
<file>debian/control</file> to generate other control files.
+ They are also responsible for discarding empty fields.
</p>
<p>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
<item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
+ <item><qref id="f-Dgit"><tt>Dgit</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-Package-List"><tt>Package-List</tt></qref> (recommended)</item>
<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
+ is not an ordinary package file and must be installed by
hand by the distribution maintainers. If the section is
<tt>byhand</tt> the priority should be <tt>-</tt>.
</p>
this value is assumed for paragraphs lacking this field.
</p>
</sect1>
+
+ <sect1 id="f-Dgit">
+ <heading><tt>Dgit</tt></heading>
+
+ <p>
+ Folded field containing a single git commit hash, presented in
+ full, followed optionally by whitespace and other data to be
+ defined in future extensions.
+ </p>
+
+ <p>
+ Declares that the source package corresponds exactly to a
+ referenced commit in a Git repository available at the canonical
+ location called <em>dgit-repos</em>, used by <prgn>dgit</prgn>, a
+ bidirectional gateway between the Debian archive and Git. The
+ commit is reachable from at least one reference whose name matches
+ <tt>refs/dgit/*</tt>. See the manual page of <prgn>dgit</prgn> for
+ further details.
+ </p>
+ </sect1>
</sect>
<sect>
exceptions to the FHS apply:
<enumlist>
+ <item>
+ <p>
+ The FHS requirement that architecture-independent
+ application-specific static files be located in
+ <file>/usr/share</file> is relaxed to a suggestion.
+
+ In particular, a subdirectory of <file>/usr/lib</file> may
+ be used by a package (or a collection of packages) to hold a
+ mixture of architecture-independent and
+ architecture-dependent files. However, when a directory is
+ entirely composed of architecture-independent files, it
+ should be located in <file>/usr/share</file>.
+ </p>
+ </item>
<item>
<p>
The optional rules related to user specific
<footnote>
This is necessary in order to reserve the directories for
use in cross-installation of library packages from other
- architectures, as part of the planned deployment of
- <tt>multiarch</tt>.
+ architectures, as part of <tt>multiarch</tt>.
+ </footnote>
+ </p>
+ <p>
+ The requirement for C and C++ headers files to be
+ accessible through the search path
+ <file>/usr/include/</file> is amended, permitting files to
+ be accessible through the search path
+ <file>/usr/include/<var>triplet</var></file> where
+ <tt><var>triplet</var></tt> is as above. <footnote>
+ This is necessary for architecture-dependant headers
+ file to coexist in a <tt>multiarch</tt> setup.
</footnote>
</p>
<p>
stable release of Debian supports <file>/run</file>.
</p>
</item>
- <item>
+ <item>
+ <p>
+ The <file>/sys</file> directory in the root filesystem is
+ additionally allowed. <footnote>This directory is used as
+ mount point to mount virtual filesystems to get access to
+ kernel information.</footnote>
+ </p>
+ </item>
+ <item>
<p>
- The following directories in the root filesystem are
- additionally allowed: <file>/sys</file> and
- <file>/selinux</file>. <footnote>These directories
- are used as mount points to mount virtual filesystems
- to get access to kernel information.</footnote>
+ The <file>/var/www</file> directory is additionally allowed.
</p>
- </item>
+ </item>
+ <item>
+ <p>
+ The requirement for <file>/usr/local/lib<qual></file>
+ to exist if <file>/lib<qual></file> or
+ <file>/usr/lib<qual></file> exists (where
+ <file>lib<qual></file> is a variant of
+ <file>lib</file> such as <file>lib32</file> or
+ <file>lib64</file>) is removed.
+ </p>
+ </item>
<item>
<p>
On GNU/Hurd systems, the following additional
</item>
<tag>65535:</tag>
+ <item>
+ <p>
+ This value <em>must not</em> be used, because it was
+ the error return sentinel value when <tt>uid_t</tt>
+ was 16 bits.
+ </p>
+ </item>
+
+ <tag>65536-4294967293:</tag>
+ <item>
+ <p>
+ Dynamically allocated user accounts. By
+ default <prgn>adduser</prgn> will not allocate UIDs
+ and GIDs in this range, to ease compatibility with
+ legacy systems where <tt>uid_t</tt> is still 16
+ bits.
+ </p>
+ </item>
+
+ <tag>4294967294:</tag>
+ <item>
+ <p>
+ <tt>(uid_t)(-2) == (gid_t)(-2)</tt> <em>must not</em> be
+ used, because it is used as the anonymous, unauthenticated
+ user by some NFS implementations.
+ </p>
+ </item>
+
+ <tag>4294967295:</tag>
<item>
<p>
<tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
renamed. If a consensus cannot be reached, <em>both</em>
programs must be renamed.
</p>
-
+ <p>
+ Binary executables must not be statically linked with the GNU C
+ library, since this prevents the binary from benefiting from
+ fixes and improvements to the C library without being rebuilt
+ and complicates security updates. This requirement may be
+ relaxed for binary executables whose intended purpose is to
+ diagnose and fix the system in situations where the GNU C
+ library may not be usable (such as system recovery shells or
+ utilities like ldconfig) or for binary executables where the
+ security benefits of static linking outweigh the drawbacks.
+ </p>
<p>
By default, when a package is being built, any binaries
created should include debugging information, as well as
would point to <file>/srv/run</file> rather than the intended
target.
</footnote>
+ Symbolic links must not traverse above the root directory.
</p>
<p>
package is purged.
</item>
</list>
- Obsolete configuration files without local changes may be
- removed by the package during upgrade.
+ Obsolete configuration files without local changes should be
+ removed by the package during upgrade.<footnote>
+ The <prgn>dpkg-maintscript-helper</prgn> tool, available from the
+ <package>dpkg</package> package, can help for this task.</footnote>
</p>
<p>
Cgi-bin executable files are installed in the
directory
<example compact="compact">
-/usr/lib/cgi-bin/<var>cgi-bin-name</var>
+/usr/lib/cgi-bin
+ </example>
+ or a subdirectory of that directory, and the script
+ <example compact="compact">
+/usr/lib/cgi-bin/.../<var>cgi-bin-name</var>
</example>
- or a subdirectory of that directory, and should be
- referred to as
+ should be referred to as
<example compact="compact">
-http://localhost/cgi-bin/<var>cgi-bin-name</var>
+http://localhost/cgi-bin/.../<var>cgi-bin-name</var>
</example>
- (possibly with a subdirectory name
- before <var>cgi-bin-name</var>).
</item>
<item>
<package>doc-base</package> package. If access to the
web document root is unavoidable then use
<example compact="compact">
-/var/www
+/var/www/html
</example>
as the Document Root. This might be just a symbolic
link to the location where the system administrator
</p>
</sect>
- <sect>
+ <sect id="docs-additional">
<heading>Additional documentation</heading>
<p>
- Any additional documentation that comes with the package may
- be installed at the discretion of the package maintainer.
- Plain text documentation should be installed in the directory
- <file>/usr/share/doc/<var>package</var></file>, where
- <var>package</var> is the name of the package, and
- compressed with <tt>gzip -9</tt> unless it is small.
- </p>
+ Any additional documentation that comes with the package may be
+ installed at the discretion of the package maintainer. It is
+ often a good idea to include text information files
+ (<file>README</file>s, FAQs, and so forth) that come with the
+ source package in the binary package. However, you don't need
+ to install the instructions for building and installing the
+ package, of course!
+ </p>
+
+ <p>
+ Plain text documentation should be compressed with <tt>gzip
+ -9</tt> unless it is small.
+ </p>
+
+ <p>
+ If a package comes with large amounts of documentation that many
+ users of the package will not require, you should create a
+ separate binary package to contain it so that it does not take
+ up disk space on the machines of users who do not need or want
+ it installed. As a special case of this rule, shared library
+ documentation of any appreciable size should always be packaged
+ with the library development package (<ref id="sharedlibs-dev">)
+ or in a separate documentation package, since shared libraries
+ are frequently installed as dependencies of other packages by
+ users who have little interest in documentation of the library
+ itself. The documentation package for the
+ package <var>package</var> is conventionally
+ named <var>package</var>-doc
+ (or <var>package</var>-doc-<var>language-code</var> if there are
+ separate documentation packages for multiple languages).
+ </p>
<p>
- If a package comes with large amounts of documentation which
- many users of the package will not require you should create
- a separate binary package to contain it, so that it does not
- take up disk space on the machines of users who do not need
- or want it installed.</p>
+ Additional documentation included in the package should be
+ installed under <file>/usr/share/doc/<var>package</var></file>.
+ If the documentation is packaged separately,
+ as <var>package</var>-doc for example, it may be installed under
+ either that path or into the documentation directory for the
+ separate documentation package
+ (<file>/usr/share/doc/<var>package</var>-doc</file> in this
+ example). However, installing the documentation into the
+ documentation directory of the main package is preferred since
+ it is independent of the packaging method and will be easier for
+ users to find.
+ </p>
<p>
- It is often a good idea to put text information files
- (<file>README</file>s, changelogs, and so forth) that come with
- the source package in <file>/usr/share/doc/<var>package</var></file>
- in the binary package. However, you don't need to install
- the instructions for building and installing the package, of
- course!</p>
+ Any separate package providing documentation must still install
+ standard documentation files in its
+ own <file>/usr/share/doc</file> directory as specified in the
+ rest of this policy. See, for example, <ref id="copyrightfile">
+ and <ref id="changelogs">.
+ </p>
<p>
Packages must not require the existence of any files in
<file>/usr/share/doc/</file> in order to function
<footnote>
- The system administrator should be able to
- delete files in <file>/usr/share/doc/</file> without causing
- any programs to break.
- </footnote>.
- Any files that are referenced by programs but are also
- useful as stand alone documentation should be installed under
- <file>/usr/share/<var>package</var>/</file> with symbolic links from
- <file>/usr/share/doc/<var>package</var></file>.
+ The system administrator should be able to delete files
+ in <file>/usr/share/doc/</file> without causing any programs
+ to break.
+ </footnote>. Any files that are used or read by programs but
+ are also useful as stand alone documentation should be installed
+ elsewhere, such as
+ under <file>/usr/share/<var>package</var>/</file>, and then
+ included via symbolic links
+ in <file>/usr/share/doc/<var>package</var></file>.
</p>
<p>
</p>
</footnote>
</p>
-
- <p>
- Former Debian releases placed all additional documentation
- in <file>/usr/doc/<var>package</var></file>. This has been
- changed to <file>/usr/share/doc/<var>package</var></file>,
- and packages must not put documentation in the directory
- <file>/usr/doc/<var>package</var></file>. <footnote>
- At this phase of the transition, we no longer require a
- symbolic link in <file>/usr/doc/</file>. At a later point,
- policy shall change to make the symbolic links a bug.
- </footnote>
- </p>
</sect>
<sect>
via HTML.</p>
<p>
- If your package comes with extensive documentation in a
+ If the package comes with extensive documentation in a
markup format that can be converted to various other formats
you should if possible ship HTML versions in a binary
- package, in the directory
- <file>/usr/share/doc/<var>appropriate-package</var></file> or
- its subdirectories.<footnote>
- The rationale: The important thing here is that HTML
- docs should be available in <em>some</em> package, not
- necessarily in the main binary package.
+ package.<footnote>
+ Rationale: The important thing here is that HTML
+ documentation should be available from <em>some</em>
+ binary package.
</footnote>
+ The documentation must be installed as specified in
+ <ref id="docs-additional">.
</p>
<p>