Debian policy manual - chapter 5
Source packaging, changelogs, etc.


5.1 Releases of packages by other than the usual Debian maintainer

Under certain circumstances it is necessary for someone other than the usual package maintainer to make a release of a package. For example, a porter for another architecture may have to make some small changes to the source package and does not wish to wait with uploading their release until the main maintainer has incorporated the patch, or a serious security problem may have come to light requiring immediate attention.

Maintainers other than the usual package maintainer should make as few changes to the package as possible, and they should always send a unified context diff (diff -u) detailing their changes to the bug tracking system properly flagged with the correct package so that the usual maintainer is kept aware of the situation.

When someone other than the usual maintainer releases a package they should add a new component to the debian-revision component of the version number - that is, the portion after the (last) hyphen. This extra component will start at 1. This is to avoid `stealing' one of the usual maintainer's version numbers, possibly disrupting their work. If there is no debian-revision component in the version number then one should be created, starting at 1.

If it is absolutely necessary for someone other than the usual maintainer to make a release based on a new upstream version then the person making the release should start with the debian-revision value 0.1. The usual maintainer of a package should start their debian-revision numbering at 1.


5.2 Standards conformance and Standards-Version

You should specify the most recent version of the packaging standards with which your package complies in the source package's Standards-Version field.

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

The value corresponds to a version of the Debian manuals, as can be found on the title page or page headers and footers (depending on the format). The value for this version of the manuals and packaging standards is 2.0.1.0.

The version number has four components - major and minor number and major and minor patchlevel. When the standards change in a way that requires every package to change the major number will be changed. Significant changes that will require work in many packages will be signaled by a change to the minor number. The major patchlevel will be changed for any change to the meaning of the standards, however small; the minor patchlevel will be changed when only cosmetic, typographical or other edits which do not change the meaning are made, or changes which do not affect the contents of packages.

You should regularly, and especially if your package has become out of date, install the most recent version of dpkg and read /usr/doc/dpkg/changelog-manuals to see which changes, if any, are relevant. If any are relevant you should look up the relevant section in the policy or programmers' manuals and update your package. When your package complies with the new standards you may update the Standards-Version source package field and release it.


5.3 Documentation and the changelog

Document your changes and updates to the source package properly in the debian/changelog file.

A copy of the file which will be installed in /usr/doc/package/copyright should be in debian/copyright.

In non-experimental packages you may only use a format for debian/changelog which is supported by the most recent released version of dpkg. If your format is not supported and there is general support for it you should contact the dpkg maintainer to have the parser script for your format included in the dpkg package.[8]


5.4 Changes to the upstream sources

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.

If changes to the source code are made that are generally applicable please try to get them included in the upstream version of the package by supplying the upstream authors with the changes in whatever form they prefer.

If you need to configure the package differently for Debian or for Linux, and the upstream source doesn't provide a way to configure it the way you need to, please 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.


5.5 Error trapping in makefiles

When make invokes a command in a makefile (including your package's upstream makefiles and the debian/rules) it does so using sh. This means that sh's usual bad error handling properties apply: if you include a miniature script as one of the commands in your makefile you'll find that if you don't do anything about it then errors are not detected and make will blithely continue after problems.

Every time you put more than one shell command (this includes using a loop) in a makefile command you must make sure that errors are trapped. For simple compound commands, such as changing directory and then running a program, using && rather than semicolon as a command separator is sufficient. For more complex commands including most loops and conditionals you must include a separate set -e command at the start of every makefile command that's actually one of these miniature shellscripts.


Debian policy manual - Copyright ©1996 Ian Jackson.
Contents; abstract; next; back.
version 2.0.1.0 (dpkg 1.3.13), 31 August 1996
Ian Jackson ijackson@gnu.ai.mit.edu