View file File name : ch-scope.html Content : <!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> <title>1. About this manual — Debian Policy Manual v4.6.0.1</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/nature.css" /> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/doctools.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="2. The Debian Archive" href="ch-archive.html" /> <link rel="prev" title="Debian Policy Manual" href="index.html" /> </head><body> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="ch-archive.html" title="2. The Debian Archive" accesskey="N">next</a> |</li> <li class="right" > <a href="index.html" title="Debian Policy Manual" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> »</li> <li class="nav-item nav-item-this"><a href=""><span class="section-number">1. </span>About this manual</a></li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="about-this-manual"> <h1><span class="section-number">1. </span>About this manual<a class="headerlink" href="#about-this-manual" title="Permalink to this headline">¶</a></h1> <section id="scope"> <span id="s1-1"></span><h2><span class="section-number">1.1. </span>Scope<a class="headerlink" href="#scope" title="Permalink to this headline">¶</a></h2> <p>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.</p> <p>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. <a class="footnote-reference brackets" href="#id3" id="id1">1</a></p> <p>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.</p> <p>The footnotes present in this manual are merely informative, and are not part of Debian policy itself.</p> <p>The appendices to this manual are not necessarily normative, either. Please see <a class="reference internal" href="ap-pkg-scope.html"><span class="doc">Introduction and scope of these appendices</span></a> for more information.</p> <p>In the normative part of this manual, the following terms are used to describe the importance of each statement: <a class="footnote-reference brackets" href="#id4" id="id2">2</a></p> <ul class="simple"> <li><p>The terms <em>must</em> and <em>must not</em>, and the adjectives <em>required</em> and <em>prohibited</em>, 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 <em>critical</em>, <em>grave</em>, and <em>serious</em> bug severities (normally serious). They are collectively called <em>Policy requirements</em>.</p></li> <li><p>The terms <em>should</em> and <em>should not</em>, and the adjective <em>recommended</em>, 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 <em>important</em>, <em>normal</em>, and <em>minor</em>. They are collectively called <em>Policy recommendations</em>.</p></li> <li><p>The adjectives <em>encouraged</em> and <em>discouraged</em> 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 <em>wishlist</em>. These statements are collectively called <em>Policy advice</em>.</p></li> <li><p>The term <em>may</em> and the adjective <em>optional</em> 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.</p></li> </ul> <p>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.</p> <p>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.</p> <p>udebs (stripped-down binary packages used by the Debian Installer) do not comply with all of the requirements discussed here. See the <a class="reference external" href="https://d-i.debian.org/doc/internals/ch03.html">Debian Installer internals manual</a> for more information about them.</p> <dl class="footnote brackets"> <dt class="label" id="id3"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt> <dd><p>Informally, the criteria used for inclusion is that the material meet one of the following requirements:</p> <dl class="simple"> <dt>Standard interfaces</dt><dd><p>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.)</p> </dd> <dt>Chosen Convention</dt><dd><p>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.</p> </dd> </dl> <p>Please note that these are not mutually exclusive; selected conventions often become parts of standard interfaces.</p> </dd> <dt class="label" id="id4"><span class="brackets"><a class="fn-backref" href="#id2">2</a></span></dt> <dd><p>Compare RFC 2119. Note, however, that these words are used in a different way in this document.</p> </dd> </dl> </section> <section id="new-versions-of-this-document"> <span id="s1-2"></span><h2><span class="section-number">1.2. </span>New versions of this document<a class="headerlink" href="#new-versions-of-this-document" title="Permalink to this headline">¶</a></h2> <p>This manual is distributed via the Debian package <a class="reference external" href="https://packages.debian.org/debian-policy">debian-policy</a>.</p> <p>The current version of this document is also available from the Debian web mirrors at <a class="reference external" href="https://www.debian.org/doc/debian-policy/">https://www.debian.org/doc/debian-policy/</a>. Also available from the same directory are several other formats: <a class="reference external" href="https://www.debian.org/doc/debian-policy/policy.epub">policy.epub</a>, <a class="reference external" href="https://www.debian.org/doc/debian-policy/policy.txt">policy.txt</a> and <a class="reference external" href="https://www.debian.org/doc/debian-policy/policy.pdf">policy.pdf</a>. Included in both the same directory and in the debian-policy package is a standalone copy of <a class="reference internal" href="upgrading-checklist.html"><span class="doc">Upgrading checklist</span></a>, which indicates policy changes between versions of this document.</p> </section> <section id="authors-and-maintainers"> <span id="s-authors"></span><h2><span class="section-number">1.3. </span>Authors and Maintainers<a class="headerlink" href="#authors-and-maintainers" title="Permalink to this headline">¶</a></h2> <section id="early-history"> <h3><span class="section-number">1.3.1. </span>Early history<a class="headerlink" href="#early-history" title="Permalink to this headline">¶</a></h3> <p>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 <a class="reference external" href="mailto:debian-policy%40lists.debian.org">debian-policy mailing list</a></p> </section> <section id="current-process"> <h3><span class="section-number">1.3.2. </span>Current process<a class="headerlink" href="#current-process" title="Permalink to this headline">¶</a></h3> <p>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 <a class="reference internal" href="ap-process.html"><span class="doc">Debian Policy changes process</span></a>. The current Policy Editors are:</p> <ol class="arabic simple"> <li><p>Russ Allbery</p></li> <li><p>Sean Whitton</p></li> </ol> </section> <section id="improvements"> <h3><span class="section-number">1.3.3. </span>Improvements<a class="headerlink" href="#improvements" title="Permalink to this headline">¶</a></h3> <p>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, <a class="reference external" href="mailto:debian-policy%40lists.debian.org">debian-policy<span>@</span>lists<span>.</span>debian<span>.</span>org</a>, or submit a bug report against the <code class="docutils literal notranslate"><span class="pre">debian-policy</span></code> package.</p> <p>Please do not try to reach the individual authors or maintainers of the Policy Manual regarding changes to the Policy.</p> <p>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.</p> </section> </section> <section id="related-documents"> <span id="s-related"></span><h2><span class="section-number">1.4. </span>Related documents<a class="headerlink" href="#related-documents" title="Permalink to this headline">¶</a></h2> <p>There are several other documents other than this Policy Manual that are necessary to fully understand some Debian policies and procedures.</p> <p>The external “sub-policy” documents are referred to in:</p> <ul class="simple"> <li><p><a class="reference internal" href="ch-opersys.html#s-fhs"><span class="std std-ref">File System Structure</span></a></p></li> <li><p><a class="reference internal" href="ch-binary.html#s-virtual-pkg"><span class="std std-ref">Virtual packages</span></a></p></li> <li><p><a class="reference internal" href="ch-opersys.html#s-menus"><span class="std std-ref">Menus</span></a></p></li> <li><p><a class="reference internal" href="ch-customized-programs.html#s-perl"><span class="std std-ref">Perl programs and modules</span></a></p></li> <li><p><a class="reference internal" href="ch-binary.html#s-maintscriptprompt"><span class="std std-ref">Prompting in maintainer scripts</span></a></p></li> <li><p><a class="reference internal" href="ch-customized-programs.html#s-emacs"><span class="std std-ref">Emacs lisp programs</span></a></p></li> </ul> <p>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 <em>not</em> normative; rather, it includes things that don’t belong in the Policy, such as best practices for developers.</p> <p>The Developer’s Reference is available in the developers-reference package. It’s also available from the Debian web mirrors at <a class="reference external" href="https://www.debian.org/doc/developers-reference/">https://www.debian.org/doc/developers-reference/</a>.</p> <p>Finally, a <a class="reference internal" href="ch-docs.html#s-copyrightformat"><span class="std std-ref">specification for machine-readable copyright files</span></a> is maintained as part of the debian-policy package using the same procedure as the other policy documents. Use of this format is optional.</p> </section> <section id="definitions"> <span id="s-definitions"></span><h2><span class="section-number">1.5. </span>Definitions<a class="headerlink" href="#definitions" title="Permalink to this headline">¶</a></h2> <p>The following terms are used in this Policy Manual:</p> <dl class="simple"> <dt>ASCII</dt><dd><p>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 <a class="reference external" href="http://www.unicode.org/">Unicode</a> characters, with the eighth bit always zero.</p> </dd> <dt>UTF-8</dt><dd><p>The transformation format (sometimes called encoding) of <a class="reference external" href="http://www.unicode.org/">Unicode</a> defined by <a class="reference external" href="https://www.rfc-editor.org/rfc/rfc3629.txt">RFC 3629</a>. UTF-8 has the useful property of having ASCII as a subset, so any text encoded in ASCII is trivially also valid UTF-8.</p> </dd> </dl> </section> <section id="translations"> <h2><span class="section-number">1.6. </span>Translations<a class="headerlink" href="#translations" title="Permalink to this headline">¶</a></h2> <p>When translations of this document into languages other than English disagree with the English text, the English text takes precedence.</p> </section> </section> <div class="clearer"></div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table of Contents</a></h3> <ul> <li><a class="reference internal" href="#">1. About this manual</a><ul> <li><a class="reference internal" href="#scope">1.1. Scope</a></li> <li><a class="reference internal" href="#new-versions-of-this-document">1.2. New versions of this document</a></li> <li><a class="reference internal" href="#authors-and-maintainers">1.3. Authors and Maintainers</a><ul> <li><a class="reference internal" href="#early-history">1.3.1. Early history</a></li> <li><a class="reference internal" href="#current-process">1.3.2. Current process</a></li> <li><a class="reference internal" href="#improvements">1.3.3. Improvements</a></li> </ul> </li> <li><a class="reference internal" href="#related-documents">1.4. Related documents</a></li> <li><a class="reference internal" href="#definitions">1.5. Definitions</a></li> <li><a class="reference internal" href="#translations">1.6. Translations</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="index.html" title="previous chapter">Debian Policy Manual</a></p> <h4>Next topic</h4> <p class="topless"><a href="ch-archive.html" title="next chapter"><span class="section-number">2. </span>The Debian Archive</a></p> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/ch-scope.rst.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3 id="searchlabel">Quick search</h3> <div class="searchformwrapper"> <form class="search" action="search.html" method="get"> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> <input type="submit" value="Go" /> </form> </div> </div> <script>$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="ch-archive.html" title="2. The Debian Archive" >next</a> |</li> <li class="right" > <a href="index.html" title="Debian Policy Manual" >previous</a> |</li> <li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> »</li> <li class="nav-item nav-item-this"><a href=""><span class="section-number">1. </span>About this manual</a></li> </ul> </div> <div class="footer" role="contentinfo"> Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.2.0. </div> </body> </html>