policy/ch-scope.rst

   1 About this manual
   2 =================
   3
   4 .. _s1.1:
   5
   6 Scope
   7 -----
   8
   9 This manual describes the policy requirements for the Debian
  10 distribution. This includes the structure and contents of the Debian
  11 archive and several design issues of the operating system, as well as
  12 technical requirements that each package must satisfy to be included in
  13 the distribution.
  14
  15 This manual also describes Debian policy as it relates to creating
  16 Debian packages. It is not a tutorial on how to build packages, nor is
  17 it exhaustive where it comes to describing the behavior of the packaging
  18 system. Instead, this manual attempts to define the interface to the
  19 package management system that the developers have to be conversant
  20 with.  [#]_
  21
  22 The footnotes present in this manual are merely informative, and are not
  23 part of Debian policy itself.
  24
  25 The appendices to this manual are not necessarily normative, either.
  26 Please see :doc:`ap-pkg-scope` for more information.
  27
  28 In the normative part of this manual, the words *must*, *should* and
  29 *may*, and the adjectives *required*, *recommended* and *optional*, are
  30 used to distinguish the significance of the various guidelines in this
  31 policy document. Packages that do not conform to the guidelines denoted
  32 by *must* (or *required*) will generally not be considered acceptable
  33 for the Debian distribution. Non-conformance with guidelines denoted by
  34 *should* (or *recommended*) will generally be considered a bug, but will
  35 not necessarily render a package unsuitable for distribution. Guidelines
  36 denoted by *may* (or *optional*) are truly optional and adherence is
  37 left to the maintainer's discretion.
  38
  39 These classifications are roughly equivalent to the bug severities
  40 *serious* (for *must* or *required* directive violations), *minor*,
  41 *normal* or *important* (for *should* or *recommended* directive
  42 violations) and *wishlist* (for *optional* items).  [#]_
  43
  44 Much of the information presented in this manual will be useful even
  45 when building a package which is to be distributed in some other way or
  46 is intended for local use only.
  47
  48 udebs (stripped-down binary packages used by the Debian Installer) do
  49 not comply with all of the requirements discussed here. See the `Debian
  50 Installer internals
  51 manual <https://d-i.alioth.debian.org/doc/internals/ch03.html>`_ for
  52 more information about them.
  53
  54 .. _s1.2:
  55
  56 New versions of this document
  57 -----------------------------
  58
  59 This manual is distributed via the Debian package
  60 `debian-policy <https://packages.debian.org/debian-policy>`_.
  61
  62 The current version of this document is also available from the Debian
  63 web mirrors at https://www.debian.org/doc/debian-policy/. Also
  64 available from the same directory are several other formats:
  65 `policy.epub
  66 <https://www.debian.org/doc/debian-policy/policy.epub>`_,
  67 `policy.txt
  68 <https://www.debian.org/doc/debian-policy/policy.txt>`_ and
  69 `policy.pdf
  70 <https://www.debian.org/doc/debian-policy/policy.pdf>`_. Included
  71 in both the same directory and in the debian-policy package is a
  72 standalone copy of :doc:`upgrading-checklist`, which indicates policy
  73 changes between versions of this document.
  74
  75 .. _s-authors:
  76
  77 Authors and Maintainers
  78 -----------------------
  79
  80 Originally called "Debian GNU/Linux Policy Manual", this manual was
  81 initially written in 1996 by Ian Jackson. It was revised on November
  82 27th, 1996 by David A. Morris. Christian Schwarz added new sections on
  83 March 15th, 1997, and reworked/restructured it in April-July 1997.
  84 Christoph Lameter contributed the "Web Standard". Julian Gilbey largely
  85 restructured it in 2001.
  86
  87 Since September 1998, the responsibility for the contents of this
  88 document lies on the `debian-policy mailing
  89 list <mailto:debian-policy@lists.debian.org>`_. Proposals are discussed
  90 there and inserted into policy after a certain consensus is established.
  91 The current policy process is described in an appendix,
  92 :doc:`ap-process`. The actual editing is done by a group
  93 of maintainers that have no editorial powers. These are the current
  94 maintainers:
  95
  96 1. Russ Allbery
  97
  98 2. Bill Allombert
  99
 100 3. Andreas Barth
 101
 102 4. Sean Whitton
 103
 104 While the authors of this document have tried hard to avoid typos and
 105 other errors, these do still occur. If you discover an error in this
 106 manual or if you want to give any comments, suggestions, or criticisms
 107 please send an email to the Debian Policy Mailing List,
 108 debian-policy@lists.debian.org, or submit a bug report against the
 109 ``debian-policy`` package.
 110
 111 Please do not try to reach the individual authors or maintainers of the
 112 Policy Manual regarding changes to the Policy.
 113
 114 .. _s-related:
 115
 116 Related documents
 117 -----------------
 118
 119 There are several other documents other than this Policy Manual that are
 120 necessary to fully understand some Debian policies and procedures.
 121
 122 The external "sub-policy" documents are referred to in:
 123
 124 -  :ref:`s-fhs`
 125
 126 -  :ref:`s-virtual-pkg`
 127
 128 -  :ref:`s-menus`
 129
 130 -  :ref:`s-perl`
 131
 132 -  :ref:`s-maintscriptprompt`
 133
 134 -  :ref:`s-emacs`
 135
 136 In addition to those, which carry the weight of policy, there is the
 137 Debian Developer's Reference. This document describes procedures and
 138 resources for Debian developers, but it is *not* normative; rather, it
 139 includes things that don't belong in the Policy, such as best practices
 140 for developers.
 141
 142 The Developer's Reference is available in the developers-reference
 143 package. It's also available from the Debian web mirrors at
 144 https://www.debian.org/doc/developers-reference/.
 145
 146 Finally, a :ref:`specification for machine-readable copyright files
 147 <s-copyrightformat>` is maintained as part of the debian-policy
 148 package using the same procedure as the other policy documents. Use of
 149 this format is optional.
 150
 151 .. _s-definitions:
 152
 153 Definitions
 154 -----------
 155
 156 The following terms are used in this Policy Manual:
 157
 158 ASCII
 159     The character encoding specified by ANSI X3.4-1986 and its
 160     predecessor standards, referred to in MIME as US-ASCII, and
 161     corresponding to an encoding in eight bits per character of the
 162     first 128 `Unicode <http://www.unicode.org/>`_ characters, with the
 163     eighth bit always zero.
 164
 165 UTF-8
 166     The transformation format (sometimes called encoding) of
 167     `Unicode <http://www.unicode.org/>`_ defined by `RFC
 168     3629 <https://www.rfc-editor.org/rfc/rfc3629.txt>`__. UTF-8 has the
 169     useful property of having ASCII as a subset, so any text encoded in
 170     ASCII is trivially also valid UTF-8.
 171
 172 .. [#]
 173    Informally, the criteria used for inclusion is that the material meet
 174    one of the following requirements:
 175
 176    Standard interfaces
 177        The material presented represents an interface to the packaging
 178        system that is mandated for use, and is used by, a significant
 179        number of packages, and therefore should not be changed without
 180        peer review. Package maintainers can then rely on this interface
 181        not changing, and the package management software authors need to
 182        ensure compatibility with this interface definition. (Control
 183        file and changelog file formats are examples.)
 184
 185    Chosen Convention
 186        If there are a number of technically viable choices that can be
 187        made, but one needs to select one of these options for
 188        inter-operability. The version number format is one example.
 189
 190    Please note that these are not mutually exclusive; selected
 191    conventions often become parts of standard interfaces.
 192
 193 .. [#]
 194    Compare RFC 2119. Note, however, that these words are used in a
 195    different way in this document.