ubuntu-policy.txt

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

     However, in some cases where the upstream version number is based on a
     date (e.g., a development "snapshot" release) the package management
     system cannot handle these version numbers without epochs.  For
     example, dpkg will consider "96May01" to be greater than "96Dec24".

     To prevent having to use epochs for every new upstream version, the
     date based portion of the version number should be changed to the
     following format in such cases: "19960501", "19961224".  It is up to
     the maintainer whether they want to bother the upstream maintainer to
     change the version numbers upstream, too.

     Note that other version formats based on dates which are parsed
     correctly by the package management system should _not_ be changed.

     Native Debian or Ubuntu packages (i.e., packages which have been
     written especially for Debian or Ubuntu) whose version numbers include
     dates should always use the "YYYYMMDD" format.


3.3. The maintainer of a package
--------------------------------

     Every package must have a Debian maintainer (the maintainer may be one
     person or a group of people reachable from a common email address,
     such as a mailing list).  The maintainer is responsible for ensuring
     that the package is placed in the appropriate distributions.

     The maintainer must be specified in the `Maintainer' control field
     with their correct name and a working email address.  If one person
     maintains several packages, they should try to avoid having different
     forms of their name and email address in the `Maintainer' fields of
     those packages.

     The format of the `Maintainer' control field is described in Section
     5.6.2, ``Maintainer''.

     If the maintainer of a package quits from the Debian project, "Debian
     QA Group" <[e-mail]> takes over the maintainer-ship of
     the package until someone else volunteers for that task.  These
     packages are called _orphaned packages_.[1]

     Ubuntu: Packages that are modified in Ubuntu should have an
     Ubuntu-specific `Maintainer' field.[2] All Ubuntu binary packages, and
     Ubuntu source packages that are modified relative to Debian (that is,
     its version number contains the string "ubuntu"), should have their
     `Maintainer' field adjusted as follows:
        * If the `Maintainer' field contains an `ubuntu.com' email address,
          or one associated with an Ubuntu developer, then no modifications
          should be made.
        * If the package is in `main' or `restricted', the `Maintainer'
          field should be set to Ubuntu Core Developers
          <[e-mail]>.
        * If the package is in `universe' or `multiverse', the `Maintainer'
          field should be set to Ubuntu MOTU Developers
          <[e-mail]>.
     If the `Maintainer' field is modified, then the old value must be
     saved in a field named `XSBC-Original-Maintainer'.  Because it is
     mandated and very common, it is not necessary or appropriate to
     document this change in `debian/changelog', unless it is the only
     change involved in the upload.

[1]  The detailed procedure for doing this gracefully can be found in the
     Debian Developer's Reference, see Section 1.4, `Related documents'.

[2]  This is in response to a poll of Debian maintainers, documented in the
     DebianMaintainerField specification
     (http://wiki.ubuntu.com/DebianMaintainerField).


3.4. The description of a package
---------------------------------

     Every Ubuntu package must have an extended description stored in the
     appropriate field of the control record.  The technical information
     about the format of the `Description' field is in Section 5.6.13,
     ``Description''.

     The description should describe the package (the program) to a user
     (system administrator) who has never met it before so that they have
     enough information to decide whether they want to install it.  This
     description should not just be copied verbatim from the program's
     documentation.

     Put important information first, both in the synopsis and extended
     description.  Sometimes only the first part of the synopsis or of the
     description will be displayed.  You can assume that there will usually
     be a way to see the whole extended description.

     The description should also give information about the significant
     dependencies and conflicts between this package and others, so that
     the user knows why these dependencies and conflicts have been
     declared.

     Instructions for configuring or using the package should not be
     included (that is what installation scripts, manual pages, info files,
     etc., are for).  Copyright statements and other administrivia should
     not be included either (that is what the copyright file is for).

3.4.1. The single line synopsis
-------------------------------

     The single line synopsis should be kept brief - certainly under 80
     characters.

     Do not include the package name in the synopsis line.  The display
     software knows how to display this already, and you do not need to
     state it.  Remember that in many situations the user may only see the
     synopsis line - make it as informative as you can.

3.4.2. The extended description
-------------------------------

     Do not try to continue the single line synopsis into the extended
     description.  This will not work correctly when the full description
     is displayed, and makes no sense where only the summary (the single
     line synopsis) is available.

     The extended description should describe what the package does and how
     it relates to the rest of the system (in terms of, for example, which
     subsystem it is which part of).

     The description field needs to make sense to anyone, even people who
     have no idea about any of the things the package deals with.[1]

[1]  The blurb that comes with a program in its announcements and/or
     `README' files is rarely suitable for use in a description.  It is
     usually aimed at people who are already in the community where the
     package is used.


3.5. Dependencies
-----------------

     Every package must specify the dependency information about other
     packages that are required for the first to work correctly.

     For example, a dependency entry must be provided for any shared
     libraries required by a dynamically-linked executable binary in a
     package.

     Packages are not required to declare any dependencies they have on
     other packages which are marked `Essential' (see below), and should
     not do so unless they depend on a particular version of that
     package.[1]

     Sometimes, a package requires another package to be installed _and_
     configured before it can be installed.  In this case, you must specify
     a `Pre-Depends' entry for the package.

     You should not specify a `Pre-Depends' entry for a package before this
     has been discussed on the `ubuntu-devel' mailing list and a consensus
     about doing that has been reached.

     The format of the package interrelationship control fields is
     described in Chapter 7, `Declaring relationships between packages'.

[1]  Essential is defined as the minimal set of functionality that must be
     available and usable on the system even when packages are in an
     unconfigured (but unpacked) state.  This is needed to avoid
     unresolvable dependency loops on upgrade.  If packages add unnecessary
     dependencies on packages in this set, the chances that there _will_ be
     an unresolvable dependency loop caused by forcing these Essential
     packages to be configured first before they need to be is greatly
     increased.  It also increases the chances that frontends will be
     unable to _calculate_ an upgrade path, even if one exists.

     Also, it's pretty unlikely that functionality from Essential shall
     ever be removed (which is one reason why care must be taken before
     adding to the Essential packages set), but _packages_ have been
     removed from the Essential set when the functionality moved to a
     different package.  So depending on these packages _just in case_ they
     stop being essential does way more harm than good.


3.6. Virtual packages
---------------------

     Sometimes, there are several packages which offer more-or-less the
     same functionality.  In this case, it's useful to define a _virtual
     package_ whose name describes that common functionality.  (The virtual
     packages only exist logically, not physically; that's why they are
     called _virtual_.) The packages with this particular function will
     then _provide_ the virtual package.  Thus, any other package requiring
     that function can simply depend on the virtual package without having
     to specify all possible packages individually.

     All packages should use virtual package names where appropriate, and
     arrange to create new ones if necessary.  They should not use virtual
     package names (except privately, amongst a cooperating group of
     packages) unless they have been agreed upon and appear in the list of
     virtual package names.  (See also Section 7.5, `Virtual packages -
     `Provides'')

     The latest version of the authoritative list of virtual package names
     can be found in the `debian-policy' package.  It is also available
     from the Debian web mirrors at
     `/doc/packaging-manuals/virtual-package-names-list.txt
     (http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt)'.

     The procedure for updating the list is described in the preface to the
     list.


3.7. Base system
----------------

     The `base system' is a minimum subset of the Ubuntu system that is
     installed before everything else on a new system.  Only very few
     packages are allowed to form part of the base system, in order to keep
     the required disk usage very small.

     The base system consists of all those packages with priority
     `required' or `important'.  Many of them will be tagged `essential'
     (see below).


3.8. Essential packages
-----------------------

     Some packages are tagged `essential' for a system using the
     `Essential' control file field.  The format of the `Essential' control
     field is described in Section 5.6.9, ``Essential''.

     Since these packages cannot be easily removed (one has to specify an
     extra _force option_ to `dpkg' to do so), this flag must not be used
     unless absolutely necessary.  A shared library package must not be
     tagged `essential'; dependencies will prevent its premature removal,
     and we need to be able to remove it when it has been superseded.

     Since dpkg will not prevent upgrading of other packages while an
     `essential' package is in an unconfigured state, all `essential'
     packages must supply all of their core functionality even when
     unconfigured.  If the package cannot satisfy this requirement it must
     not be tagged as essential, and any packages depending on this package
     must instead have explicit dependency fields as appropriate.

     You must not tag any packages `essential' before this has been
     discussed on the `ubuntu-devel' mailing list and a consensus about
     doing that has been reached.


3.9. Maintainer Scripts
-----------------------

     The package installation scripts should avoid producing output which
     is unnecessary for the user to see and should rely on `dpkg' to stave
     off boredom on the part of a user installing many packages.  This
     means, amongst other things, using the `--quiet' option on
     `install-info'.

     Errors which occur during the execution of an installation script must
     be checked and the installation must not continue after an error.

     Note that in general Section 10.4, `Scripts' applies to package
     maintainer scripts, too.

     You should not use `dpkg-divert' on a file belonging to another
     package without consulting the maintainer of that package first.

     All packages which supply an instance of a common command name (or, in
     general, filename) should generally use `update-alternatives', so that
     they may be installed together.  If `update-alternatives' is not used,
     then each package must use `Conflicts' to ensure that other packages
     are de-installed.  (In this case, it may be appropriate to specify a
     conflict against earlier versions of something that previously did not
     use `update-alternatives'; this is an exception to the usual rule that
     versioned conflicts should be avoided.)

3.9.1. Prompting in maintainer scripts
--------------------------------------

     Package maintainer scripts may prompt the user if necessary.
     Prompting should be done by communicating through a program, such as
     `debconf', which conforms to the Debian Configuration management
     specification, version 2 or higher.  Prompting the user by other
     means, such as by hand[1], is now deprecated.

     The Debian Configuration management specification is included in the
     `debconf_specification' files in the `debian-policy' package.  It is
     also available from the Debian web mirrors at
     `/doc/packaging-manuals/debconf_specification.html
     (http://www.debian.org/doc/packaging-manuals/debconf_specification.html)'.

     Packages which use the Debian Configuration management specification
     may contain an additional `config' script and a `templates' file in
     their control archive[2].  The `config' script might be run before the