About this manual
=================
.. _s1.1:
Scope
-----
This manual describes the policy requirements for the Debian
distribution. This includes the structure and contents of the Debian
archive and several design issues of the operating system, as well as
technical requirements that each package must satisfy to be included in
the distribution.
This manual also describes Debian policy as it relates to creating
Debian packages. It is not a tutorial on how to build packages, nor is
it exhaustive where it comes to describing the behavior of the
packaging system. Instead, this manual attempts to define the
interface to the package management system with which the developers
must be conversant. [#]_
This manual cannot and does not prohibit every possible bug or
undesirable behaviour. The fact that something is not prohibited by
Debian policy does not mean that it is not a bug, let alone that it is
desirable. Questions not covered by policy should be evaluated on
their merits.
The footnotes present in this manual are merely informative, and are not
part of Debian policy itself.
The appendices to this manual are not necessarily normative, either.
Please see :doc:`ap-pkg-scope` for more information.
In the normative part of this manual, the following terms are used to
describe the importance of each statement: [#]_
* The terms *must* and *must not*, and the adjectives *required* and
*prohibited*, denote strong requirements. Packages that do not conform
to these requirements will generally not be considered acceptable for
the Debian distribution. These statements correspond to the *critical*,
*grave*, and *serious* bug severities (normally serious). They are
collectively called *Policy requirements*.
* The terms *should* and *should not*, and the adjective *recommended*,
denote best practices. Non-conformance with these guidelines will
generally be considered a bug, but will not necessarily render a package
unsuitable for distribution. These statements correspond to bug
severities of *important*, *normal*, and *minor*. They are collectively
called *Policy recommendations*.
* The adjectives *encouraged* and *discouraged* denote places where Policy
offers advice to maintainers, but maintainers are free to follow or not
follow that advice. Non-conformance with this advice is normally not
considered a bug; if a bug seems worthwhile, normally it would have a
severity of *wishlist*. These statements are collectively called *Policy
advice*.
* The term *may* and the adjective *optional* are used to clarify cases
where it may otherwise appear that Policy is specifying a requirement or
recommendation. In those cases, these words describe decisions that are
truly optional and at the maintainer's discretion.
The Release Team can, at their discretion, downgrade a Policy requirement
to a Policy recommendation for a given release of the Debian distribution.
This may be done for only a specific package or for the archive as a
whole. This provision is intended to provide flexibility to balance the
quality standards of the distribution against the release schedule and the
importance of making a stable release.
Much of the information presented in this manual will be useful even
when building a package which is to be distributed in some other way or
is intended for local use only.
udebs (stripped-down binary packages used by the Debian Installer) and
source packages that produce only udebs do not comply with all of the
requirements discussed here. See the `Debian Installer internals manual
<https://d-i.debian.org/doc/internals/ch03.html>`_ for more information
about them.
.. [#]
Informally, the criteria used for inclusion is that the material meet
one of the following requirements:
Standard interfaces
The material presented represents an interface to the packaging
system that is mandated for use, and is used by, a significant
number of packages, and therefore should not be changed without
peer review. Package maintainers can then rely on this interface
not changing, and the package management software authors need to
ensure compatibility with this interface definition. (Control
file and changelog file formats are examples.)
Chosen Convention
If there are a number of technically viable choices that can be
made, but one needs to select one of these options for
inter-operability. The version number format is one example.
Please note that these are not mutually exclusive; selected
conventions often become parts of standard interfaces.
.. [#]
Compare RFC 2119. Note, however, that these words are used in a
different way in this document.
.. _s1.2:
New versions of this document
-----------------------------
This manual is distributed via the Debian package
`debian-policy <https://packages.debian.org/debian-policy>`_.
The current version of this document is also available from the Debian
web mirrors at https://www.debian.org/doc/debian-policy/. Also
available from the same directory are several other formats:
`policy.epub
<https://www.debian.org/doc/debian-policy/policy.epub>`_,
`policy.txt
<https://www.debian.org/doc/debian-policy/policy.txt>`_ and
`policy.pdf
<https://www.debian.org/doc/debian-policy/policy.pdf>`_. Included
in both the same directory and in the debian-policy package is a
standalone copy of :doc:`upgrading-checklist`, which indicates policy
changes between versions of this document.
.. _s-authors:
Authors and Maintainers
-----------------------
Early history
~~~~~~~~~~~~~
Originally called "Debian GNU/Linux Policy Manual", this manual was
initially written in 1996 by Ian Jackson. It was revised on November
27th, 1996 by David A. Morris. Christian Schwarz added new sections on
March 15th, 1997, and reworked/restructured it in April-July 1997.
Christoph Lameter contributed the "Web Standard". Julian Gilbey
largely restructured it in 2001. Since September 1998, changes to the
contents of this document have been co-ordinated by means of the
`debian-policy mailing list <mailto:debian-policy@lists.debian.org>`_
Current process
~~~~~~~~~~~~~~~
The Policy Editors are DPL delegates with responsibility for the
contents of this document (see the Debian Constitution for the meaning
of "DPL delegate"). However, the Policy Editors further delegate
their editorial power to a process of establishing project member
consensus on the debian-policy mailing list, as described in
:doc:`ap-process`. The current Policy Editors are:
1. Russ Allbery
2. Sean Whitton
Improvements
~~~~~~~~~~~~
While the authors of this document have tried hard to avoid typos and
other errors, these do still occur. If you discover an error in this
manual or if you want to give any comments, suggestions, or criticisms
please send an email to the Debian Policy Mailing List,
debian-policy@lists.debian.org, or submit a bug report against the
``debian-policy`` package.
Please do not try to reach the individual authors or maintainers of the
Policy Manual regarding changes to the Policy.
New techniques and functionality are generally implemented in the
Debian archive (long) before they are detailed in this document. This
is not considered to be a problem: there is a consensus in the Debian
Project that the task of keeping this document up-to-date should never
block making improvements to Debian. Nevertheless, it is better to
submit patches to this document sooner rather than later. This
reduces the amount of work that is needed on the part of others to get
themselves up-to-speed on new best practices.
.. _s-related:
Related documents
-----------------
There are several other documents other than this Policy Manual that are
necessary to fully understand some Debian policies and procedures.
The external "sub-policy" documents are referred to in:
- :ref:`s-fhs`
- :ref:`s-virtual-pkg`
- :ref:`s-menus`
- :ref:`s-perl`
- :ref:`s-maintscriptprompt`
- :ref:`s-emacs`
In addition to those, which carry the weight of policy, there is the
Debian Developer's Reference. This document describes procedures and
resources for Debian developers, but it is *not* normative; rather, it
includes things that don't belong in the Policy, such as best practices
for developers.
The Developer's Reference is available in the developers-reference
package. It's also available from the Debian web mirrors at
https://www.debian.org/doc/developers-reference/.
Finally, a :ref:`specification for machine-readable copyright files
<s-copyrightformat>` is maintained as part of the debian-policy
package using the same procedure as the other policy documents. Use of
this format is optional.
.. _s-definitions:
Definitions
-----------
The following terms are used in this Policy Manual:
ASCII
The character encoding specified by ANSI X3.4-1986 and its
predecessor standards, referred to in MIME as US-ASCII, and
corresponding to an encoding in eight bits per character of the
first 128 `Unicode <http://www.unicode.org/>`_ characters, with the
eighth bit always zero.
upstream
The source of software that is being packaged, or the portion of a
software package that originates from outside of Debian. For example,
suppose Alice writes and releases a free software package, and then
Bob creates a Debian package of that software package. Alice is the
*upstream maintainer* (sometimes abbreviated as *upstream*) of the
package, Alice's releases are the *upstream releases*, and the version
number she puts on a release is the *upstream version*. Bob may make
Debian-specific modifications to the package, and then later send
those modifications *upstream* to be incorporated in Alice's releases.
The packager and upstream developer may be the same person. For
example, Alice may choose to package her own software for Debian.
However, this manual still distinguishes between the role of upstream
and the role of Debian packager, even when the same person is filling
both of those roles, since they have some implications for the details
of packaging.
UTF-8
The transformation format (sometimes called encoding) of
`Unicode <http://www.unicode.org/>`_ defined by `RFC
3629 <https://www.rfc-editor.org/rfc/rfc3629.txt>`__. UTF-8 has the
useful property of having ASCII as a subset, so any text encoded in
ASCII is trivially also valid UTF-8.
Translations
------------
When translations of this document into languages other than English
disagree with the English text, the English text takes precedence.