ubuntu-policy.txt

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

     `preinst' script, and before the package is unpacked or any of its
     dependencies or pre-dependencies are satisfied.  Therefore it must
     work using only the tools present in _essential_ packages.[3]

     Packages which use the Debian Configuration management specification
     must allow for translation of their messages by using a gettext-based
     system such as the one provided by the `po-debconf' package.

     Packages should try to minimize the amount of prompting they need to
     do, and they should ensure that the user will only ever be asked each
     question once.  This means that packages should try to use appropriate
     shared configuration files (such as `/etc/papersize' and
     `/etc/news/server'), and shared `debconf' variables rather than each
     prompting for their own list of required pieces of information.

     It also means that an upgrade should not ask the same questions again,
     unless the user has used `dpkg --purge' to remove the package's
     configuration.  The answers to configuration questions should be
     stored in an appropriate place in `/etc' so that the user can modify
     them, and how this has been done should be documented.

     If a package has a vitally important piece of information to pass to
     the user (such as "don't run me as I am, you must edit the following
     configuration files first or you risk your system emitting
     badly-formatted messages"), it should display this in the `config' or
     `postinst' script and prompt the user to hit return to acknowledge the
     message.  Copyright messages do not count as vitally important (they
     belong in `/usr/share/doc/<package>/copyright'); neither do
     instructions on how to use a program (these should be in on-line
     documentation, where all the users can see them).

     Any necessary prompting should almost always be confined to the
     `config' or `postinst' script.  If it is done in the `postinst', it
     should be protected with a conditional so that unnecessary prompting
     doesn't happen if a package's installation fails and the `postinst' is
     called with `abort-upgrade', `abort-remove' or `abort-deconfigure'.

[1]  From the Jargon file: by hand 2.  By extension, writing code which
     does something in an explicit or low-level way for which a presupplied
     library (_debconf, in this instance_) routine ought to have been
     available.

[2]  The control.tar.gz inside the .deb.  See deb(5).

[3]  `Debconf' or another tool that implements the Debian Configuration
     management specification will also be installed, and any versioned
     dependencies on it will be satisfied before preconfiguration begins.


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


4. Source packages
------------------


4.1. Standards conformance
--------------------------

     Source packages should specify the most recent version number of this
     policy document with which your package complied when it was last
     updated.

     This information may be used to file bug reports automatically if your
     package becomes too much out of date.

     The version is specified in the `Standards-Version' control field.
     The format of the `Standards-Version' field is described in Section
     5.6.11, ``Standards-Version''.

     You should regularly, and especially if your package has become out of
     date, check for the newest Policy Manual available and update your
     package, if necessary.  When your package complies with the new
     standards you should update the `Standards-Version' source package
     field and release it.[1]

[1]  See the file `upgrading-checklist' for information about policy which
     has changed between different versions of this document.


4.2. Package relationships
--------------------------

     Source packages should specify which binary packages they require to
     be installed or not to be installed in order to build correctly.  For
     example, if building a package requires a certain compiler, then the
     compiler should be specified as a build-time dependency.

     It is not necessary to explicitly specify build-time relationships on
     a minimal set of packages that are always needed to compile, link and
     put in an Ubuntu package a standard "Hello World!"  program written in
     C or C++.  The required packages are called _build-essential_, and an
     informational list can be found in
     `/usr/share/doc/build-essential/list' (which is contained in the
     `build-essential' package).[1]

     When specifying the set of build-time dependencies, one should list
     only those packages explicitly required by the build.  It is not
     necessary to list packages which are required merely because some
     other package in the list of build-time dependencies depends on
     them.[2]

     If build-time dependencies are specified, it must be possible to build
     the package and produce working binaries on a system with only
     essential and build-essential packages installed and also those
     required to satisfy the build-time relationships (including any
     implied relationships).  In particular, this means that version
     clauses should be used rigorously in build-time relationships so that
     one cannot produce bad or inconsistently configured packages when the
     relationships are properly satisfied.

     Chapter 7, `Declaring relationships between packages' explains the
     technical details.

[1]  Rationale:
        * This allows maintaining the list separately from the policy
          documents (the list does not need the kind of control that the
          policy documents do).
        * Having a separate package allows one to install the
          build-essential packages on a machine, as well as allowing other
          packages such as tasks to require installation of the
          build-essential packages using the depends relation.
        * The separate package allows bug reports against the list to be
          categorized separately from the policy management process in the
          BTS.

[2]  The reason for this is that dependencies change, and you should list
     all those packages, and _only_ those packages that _you_ need
     directly.  What others need is their business.  For example, if you
     only link against `libimlib', you will need to build-depend on
     `libimlib2-dev' but not against any `libjpeg*' packages, even though
     `libimlib2-dev' currently depends on them: installation of
     `libimlib2-dev' will automatically ensure that all of its run-time
     dependencies are satisfied.


4.3. Changes to the upstream sources
------------------------------------

     If changes to the source code are made that are not specific to the
     needs of the Ubuntu system, they should be sent to the upstream
     authors in whatever form they prefer so as to be included in the
     upstream version of the package.

     If you need to configure the package differently for Ubuntu or for
     Linux, and the upstream source doesn't provide a way to do so, you
     should add such configuration facilities (for example, a new
     `autoconf' test or `#define') and send the patch to the upstream
     authors, with the default set to the way they originally had it.  You
     can then easily override the default in your `debian/rules' or
     wherever is appropriate.

     You should make sure that the `configure' utility detects the correct
     architecture specification string (refer to Section 11.1,
     `Architecture specification strings' for details).

     If you need to edit a `Makefile' where GNU-style `configure' scripts
     are used, you should edit the `.in' files rather than editing the
     `Makefile' directly.  This allows the user to reconfigure the package
     if necessary.  You should _not_ configure the package and edit the
     generated `Makefile'!  This makes it impossible for someone else to
     later reconfigure the package without losing the changes you made.


4.4. Ubuntu changelog: `debian/changelog'
-----------------------------------------

     Changes in the Ubuntu version of the package should be briefly
     explained in the Ubuntu changelog file `debian/changelog'.[1] This
     includes modifications made in the Ubuntu package compared to the
     upstream one or the Debian package as well as other changes and
     updates to the package.  [2]

     The format of the `debian/changelog' allows the package building tools
     to discover which version of the package is being built and find out
     other release-specific information.

     That format is a series of entries like this:
          <package> (<version>) <distribution(s)>; urgency=<urgency>
          	    <[optional blank line(s), stripped]>
            * <change details>
              <more change details>
          	    <[blank line(s), included in output of dpkg-parsechangelog]>
            * <even more change details>
          	    <[optional blank line(s), stripped]>
           -- <maintainer name> <<email address>><[two spaces]>  <date>

     <package> and <version> are the source package name and version
     number.

     <distribution(s)> lists the distributions where this version should be
     installed when it is uploaded - it is copied to the `Distribution'
     field in the `.changes' file.  See Section 5.6.14, ``Distribution''.

     <urgency> is the value for the `Urgency' field in the `.changes' file
     for the upload (see Section 5.6.17, ``Urgency'').  It is not possible
     to specify an urgency containing commas; commas are used to separate
     `<keyword>=<value>' settings in the `dpkg' changelog format (though
     there is currently only one useful <keyword>, `urgency').

     The change details may in fact be any series of lines starting with at
     least two spaces, but conventionally each change starts with an
     asterisk and a separating space and continuation lines are indented so
     as to bring them in line with the start of the text above.  Blank
     lines may be used here to separate groups of changes, if desired.

     If this upload resolves bugs recorded in the Debian Bug Tracking
     System (BTS), they may be automatically closed on the inclusion of
     this package into the Debian archive by including the string: `closes:
     Bug#<nnnnn>' in the change details.[3] This information is conveyed
     via the `Closes' field in the `.changes' file (see Section 5.6.22,
     ``Closes'').

     Ubuntu: If this upload resolves bugs recorded in Launchpad, they may
     be automatically closed on the inclusion of this package into the
     Ubuntu archive by including the string: `LP: #<nnnnn>' in the change
     details.[4] This information is conveyed via the
     `Launchpad-Bugs-Fixed' field in the `.changes' file (see Section
     5.6.23, ``Launchpad-Bugs-Fixed'').

     The maintainer name and email address used in the changelog should be
     the details of the person uploading _this_ version.  They are _not_
     necessarily those of the usual package maintainer.  The information
     here will be copied to the `Changed-By' field in the `.changes' file
     (see Section 5.6.4, ``Changed-By''), and then later used to send an
     acknowledgement when the upload has been installed.

     The <date> should be in RFC822 format[5]; it should include the time
     zone specified numerically, with the time zone name or abbreviation
     optionally present as a comment in parentheses.

     The first "title" line with the package name should start at the left
     hand margin; the "trailer" line with the maintainer and date details
     should be preceded by exactly one space.  The maintainer details and
     the date must be separated by exactly two spaces.

     For more information on placement of the changelog files within binary
     packages, please see Section 12.7, `Changelog files'.

[1]  Mistakes in changelogs are usually best rectified by making a new
     changelog entry rather than "rewriting history" by editing old
     changelog entries.

[2]  Although there is nothing stopping an author who is also the Ubuntu
     maintainer from using this changelog for all their changes, it will
     have to be renamed if the Ubuntu and upstream maintainers become
     different people.  In such a case, however, it might be better to
     maintain the package as a non-native package.

[3]  To be precise, the string should match the following Perl regular
     expression:

          /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i

     Then all of the bug numbers listed will be closed by the archive
     maintenance script (`katie') using the <version> of the changelog
     entry.

[4]  To be precise, the string should match the following Perl regular
     expression:

          /lp:\s+\#\d+(?:,\s*\#\d+)*/i

     Then all of the bug numbers listed will be closed by the archive
     maintenance software using the <version> of the changelog entry.

[5]  This is generated by `date -R'.

4.4.1. Alternative changelog formats
------------------------------------

     In non-experimental packages you must use a format for
     `debian/changelog' which is supported by the most recent released
     version of `dpkg'.

     It is possible to use a format different from the standard one by
     providing a changelog parser for the format you wish to use.  The
     parser must have an API compatible with that expected by
     `dpkg-genchanges' and `dpkg-gencontrol', and it must not interact with
     the user at all.  [1]

[1]  If there is general interest in the new format, you should contact the
     `dpkg' maintainer to have the parser script for it included in the
     `dpkg' package.  (You will need to agree tha