1. About this manual¶
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. 1
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 Introduction and scope of these appendices for more information.
In the normative part of this manual, the following terms are used to describe the importance of each statement: 2
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) do not comply with all of the requirements discussed here. See the Debian Installer internals manual 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.
1.2. New versions of this document¶
This manual is distributed via the Debian package 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, policy.txt and policy.pdf. Included in both the same directory and in the debian-policy package is a standalone copy of Upgrading checklist, which indicates policy changes between versions of this document.
The following terms are used in this Policy Manual:
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 characters, with the eighth bit always zero.
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.
The transformation format (sometimes called encoding) of Unicode defined by RFC 3629. UTF-8 has the useful property of having ASCII as a subset, so any text encoded in ASCII is trivially also valid UTF-8.
When translations of this document into languages other than English disagree with the English text, the English text takes precedence.