ubuntu-policy.txt

This manual describes the policy requirements for the Ubuntu distribution. This includes the struc

     D.2.2.         `Size' and `MD5sum'
     D.2.3.         `Status'
     D.2.4.         `Config-Version'
     D.2.5.         `Conffiles'
     D.2.6.         Obsolete fields

     E.        Configuration file handling (from old Packaging Manual)
     E.1.      Automatic handling of configuration files by `dpkg'
     E.2.      Fully-featured maintainer script configuration handling

     F.        Alternative versions of an interface - `update-alternatives'
               (from old Packaging Manual)

     G.        Diversions - overriding a package's version of a file (from
               old Packaging Manual)


-------------------------------------------------------------------------------


1. About this manual
--------------------


1.1. Scope
----------

     This manual describes the policy requirements for the Ubuntu
     distribution.  This includes the structure and contents of the Ubuntu
     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 Ubuntu policy as it relates to creating
     Ubuntu 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 that the developers have to
     be conversant with.[1]

     The footnotes present in this manual are merely informative, and are
     not part of Ubuntu policy itself.

     The appendices to this manual are not necessarily normative, either.
     Please see Appendix A, `Introduction and scope of these appendices'
     for more information.

     In the normative part of this manual, the words _must_, _should_ and
     _may_, and the adjectives _required_, _recommended_ and _optional_,
     are used to distinguish the significance of the various guidelines in
     this policy document.  Packages that do not conform to the guidelines
     denoted by _must_ (or _required_) will generally not be considered
     acceptable for the Ubuntu distribution.  Non-conformance with
     guidelines denoted by _should_ (or _recommended_) will generally be
     considered a bug, but will not necessarily render a package unsuitable
     for distribution.  Guidelines denoted by _may_ (or _optional_) are
     truly optional and adherence is left to the maintainer's discretion.

     These classifications are roughly equivalent to the bug severities
     _serious_ (for _must_ or _required_ directive violations), _minor_,
     _normal_ or _important_ (for _should_ or _recommended_ directive
     violations) and _wishlist_ (for _optional_ items).  [2]

     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.

     The Ubuntu distribution differs from its parent Debian distribution in
     a number of significant ways.  In this document, these are marked with
     the tag _Ubuntu:_.

[1]  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
          interfaces not changing, and the package management software
          authors need to ensure compatibility with these interface
          definitions.  (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.

[2]  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 Ubuntu package `ubuntu-policy
     (http://packages.ubuntu.com/ubuntu-policy)' (packages.ubuntu.com
     /ubuntu-policy).

     The `ubuntu-policy' package also includes the file
     `upgrading-checklist.txt.gz' which indicates policy changes between
     versions of this document.


1.3. Authors and Maintainers
----------------------------

     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, the responsibility for the contents of the
     Debian version of this document lies on the debian-policy mailing list
     (mailto:[e-mail]).  Proposals are discussed
     there and inserted into policy after a certain consensus is
     established.  The actual editing is done by a group of maintainers
     that have no editorial powers.  These are the current maintainers:

     1.   Julian Gilbey

     2.   Branden Robinson

     3.   Josip Rodin

     4.   Manoj Srivastava

     The Ubuntu branch of this manual is maintained by the ubuntu-devel
     mailing list (mailto:[e-mail]).

     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 List,
     <[e-mail]>, 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.


1.4. 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:
        * Section 9.1.1, `File system Structure'
        * Section 3.6, `Virtual packages'
        * Section 9.6, `Menus'
        * Section 9.7, `Multimedia handlers'
        * Section 11.9, `Perl programs and modules'
        * Section 3.9.1, `Prompting in maintainer scripts'
        * Section 11.10, `Emacs lisp programs'

     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
     `/doc/developers-reference/
     (http://www.debian.org/doc/developers-reference/)'.


-------------------------------------------------------------------------------


2. The Ubuntu Archive
---------------------

     The Ubuntu system is maintained and distributed as a collection of
     _packages_.  Since there are so many of them (currently well over
     15000), they are split into _sections_ and given _priorities_ to
     simplify the handling of them.

     The effort of the Ubuntu project is to build a free operating system,
     but not every package we want to make accessible is _free_ in our
     sense (see the Ubuntu Licensing Policy, below), or may be
     imported/exported without restrictions.  Thus, the archive is split
     into the distribution areas or categories based on their licenses and
     other restrictions.  We also divide up packages based on whether they
     are supported or not.

     The aims of this are:
        * to allow us to make as much software available as we can
        * to allow us to encourage everyone to write free software, and
        * to allow us to make it easy for people to produce CD-ROMs of our
          system without violating any licenses, import/export
          restrictions, or any other laws.


2.1. The Ubuntu Licensing Policy
--------------------------------

     The Ubuntu Licensing Policy forms our definition of "free software".
     The following guidelines apply to the _main_ and _universe_ categories
     of the archive:

     Must include source code.
          The _main_ and _universe_ categories have a strict and
          non-negotiable requirement that application software included in
          them must come with full source code.

     Must allow modification and distribution of modified copies under the
     same license.
          Just having the source code does not convey the same freedom as
          having the right to change it.  Without the ability to modify
          software, the Ubuntu community cannot support software, fix bugs,
          translate it, or improve it.

     The following additional guidelines apply to the _main_, _restricted_
     and _universe_ categories of the archive:

     Must allow these rights to be passed on along with the software.
          You should be able to have exactly the same rights to the
          software as we do.

     Must not discriminate against persons, groups or against fields of
     endeavour.
          The license of software included in Ubuntu can not discriminate
          against anyone or any group of users and cannot restrict users
          from using the software for a particular field of endeavour - a
          business for example.  Thus we will not distribute software that
          is licensed "freely for non-commercial use".

     Must not be distributed under a license specific to Ubuntu.
          The rights attached to the software must not depend on the
          programme's being part of Ubuntu system.  So we will not
          distribute software for which Ubuntu has a "special" exemption or
          right, and we will not put our own software into Ubuntu and then
          refuse you the right to pass it on.

     The following additional guidelines apply to the entire archive:

     Must allow redistribution.
          Your right to sell or give away the software alone, or as part of
          an aggregate software distribution, is important because:
             * You, the user, must be able to pass on any software you have
               received from Ubuntu in either source code or compiled form.
             * While Ubuntu will not charge license fees for this
               distribution, you might well want to charge to print Ubuntu
               CD's, or create your own customized versions of Ubuntu which
               you sell, and should have the freedom to do so.

     Must not require royalty payments or any other fee for redistribution
     or modification.
          It's important that you can exercise your rights to this software
          without having to pay for the privilege, and that you can pass
          these rights on to other people on exactly the same basis.

     Must not contaminate other software licenses.
          The license must not place restrictions on other software that is
          distributed along with it.  For example, the license must not
          insist that all other programmes distributed on the same medium
          be free software.

     May require source modifications to be distributed as patches.
          In some cases, software authors are happy for us to distribute
          their software and modifications to their software, as long as
          the two are distributed separately, so that people always have a
          copy of their pristine code.  We are happy to respect this
          preference.  However, the license must explicitly permit
          distribution of software built from modified source code.

     The "GPL," "BSD," and "Artistic" licenses are examples of licenses
     that we consider _free_.

     Ubuntu contains licensed and copyrighted works that are not
     application software.  For example, the default Ubuntu installation
     includes documentation, images, sounds, video clips and firmware.  The
     Ubuntu community will make decisions on the inclusion of these works
     on a case-by-case basis, ensuring that these works do not restrict our
     ability to make Ubuntu available free of charge, and that Ubuntu
     remains re-distributable by you.


2.2. Categories
---------------