Whole document tree

Debian Developer's Reference
Chapter 6 - Package uploads

6.1 New packages

If you want to create a new package for the Debian distribution, you should first check the Work-Needing and Prospective Packages (WNPP) list. Checking the WNPP list ensures that no one is already working on packaging that software, and that effort is not duplicated. Read the WNPP web pages for more information.

Assuming no one else is already working on your prospective package, you must then submit a bug report (Submitting Bugs, Section 10.2) against the pseudo package wnpp describing your plan to create a new package, including, but not limiting yourself to, a description of the package, the license of the prospective package and the current URL where it can be downloaded from.

You should set the subject of the bug to ``ITP: foo -- short description'', substituting the name of the new package for foo. The severity of the bug report must be set to wishlist. If you feel it's necessary, send a copy to debian-devel@lists.debian.org by putting the address in the X-Debbugs-CC: header of the message (no, don't use CC:, because that way the message's subject won't indicate the bug number).

Please include a Closes: bug#nnnnn entry on the changelog of the new package in order for the bug report to be automatically closed once the new package is installed on the archive (When bugs are closed by new uploads, Section 10.4).

There are a number of reasons why we ask maintainers to announce their intentions:

• It helps the (potentially new) maintainer to tap into the experience of people on the list, and lets them know if anyone else is working on it already.
• It lets other people thinking about working on the package know that there already is a volunteer, so efforts may be shared.
• It lets the rest of the maintainers know more about the package than the one line description and the usual changelog entry ``Initial release'' that gets posted to debian-devel-changes.
• It is helpful to the people who live off unstable (and form our first line of testers). We should encourage these people.
• The announcements give maintainers and other interested parties a better feel of what is going on, and what is new, in the project.

6.2 Adding an entry to debian/changelog

Changes that you make to the package need to be recorded in the debian/changelog. These changes should provide a concise description of what was changed, why (if it's in doubt), and note if any bugs were closed. They also record when the packages was completed. This file will be installed in /usr/share/doc/package/changelog.Debian.gz, or /usr/share/doc/package/changelog.gz for native packages.

The debian/changelog file conform to a certain structure, with a number of different fields. One field of note, the distribution, is described in Picking a distribution, Section 6.4.2. More information about the structure structure of this file can be found in the Debian Policy section titled "debian/changelog".

Changelog entries can be used to automatically close Debian bugs when the package is installed into the archive. See When bugs are closed by new uploads, Section 10.4.

It is conventional that the changelog entry notating that the package contains a new upstream version of the software looks like this:

       * new upstream version

There are tools to help you create entries and finalize the changelog for release — see devscripts, Section 12.13 and dpkg-dev-el, Section 12.14.

6.3 Checking the package prior to upload

Before you upload your package, you should do basic testing on it. At a minimum, you should try the following activities (you'll need to have an older version of the same Debian package around):

• Install the package and make sure the software works, or upgrade the package from an older version to your new version if a Debian package for it already exists.

• Run lintian over the package. You can run lintian as follows: lintian -v package-version.changes. This will check the source package as well as the binary package. If you don't understand the output that lintian generates, try adding the -i switch, which will cause lintian to output a very verbose description of the problem.

  Normally, a package should not be uploaded if it causes lintian to emit errors (they will start with E).

  For more information on lintian, see lintian, Section 12.2.

• Downgrade the package to the previous version (if one exists) — this tests the postrm and prerm scripts.

• Remove the package, then reinstall it.

6.4 Generating the changes file

When a package is uploaded to the Debian FTP archive, it must be accompanied by a .changes file, which gives directions to the archive maintainers for its handling. This is usually generated by dpkg-genchanges during the normal package build process.

The changes file is a control file with the following fields:

• Format
• Date
• Source
• Binary
• Architecture
• Version
• Distribution
• Urgency
• Maintainer
• Description
• Changes
• Files

All of these fields are mandatory for a Debian upload. See the list of control fields in the Debian Policy Manual for the contents of these fields. You can close bugs automatically using the Description field, see When bugs are closed by new uploads, Section 10.4.

6.4.1 The original source tarball

The first time a version is uploaded which corresponds to a particular upstream version, the original source tar file should be uploaded and included in the .changes file. Subsequently, this very same tar file should be used to build the new diffs and .dsc files, and will not need to be re-uploaded.

By default, dpkg-genchanges and dpkg-buildpackage will include the original source tar file if and only if the Debian revision part of the source version number is 0 or 1, indicating a new upstream version. This behaviour may be modified by using -sa to always include it or -sd to always leave it out.

If no original source is included in the upload, the original source tar-file used by dpkg-source when constructing the .dsc file and diff to be uploaded must be byte-for-byte identical with the one already in the archive. If there is some reason why this is not the case, the new version of the original source should be uploaded, possibly by using the -sa flag.

6.4.2 Picking a distribution

The Distribution field, which originates from the first line of the debian/changelog file, indicates which distribution the package is intended for.

There are three possible values for this field: `stable', `unstable', and `experimental'. Normally, packages are uploaded into unstable.

You should avoid combining `stable' with others because of potential problems with library dependencies (for your package and for the package built by the build daemons for other architecture). See Uploading to stable, Section 6.4.2.1 for more information on when and how to upload to stable.

It never makes sense to combine the experimental distribution with anything else.

6.4.2.1 Uploading to stable

Uploading to stable means that the package will be placed into the proposed-updates directory of the Debian archive for further testing before it is actually included in stable.

Extra care should be taken when uploading to stable. Basically, a package should only be uploaded to stable if one of the following happens:

• a security problem (e.g. a Debian security advisory)

• a truely critical functionality problem

• the package becomes uninstallable

• a released architecture lacks the package

It is discouraged to change anything else in the package that isn't important, because even trivial fixes can cause bugs later on. Uploading new upstream versions to fix security problems is deprecated; applying the specific patch from the new upstream version to the old one ("backporting" the patch) is the right thing to do in most cases.

Packages uploaded to stable need to be compiled on systems running stable, so that their dependencies are limited to the libraries (and other packages) available in stable; for example, a package uploaded to stable that depends on a library package that only exists in unstable will be rejected. Making changes to dependencies of other packages (by messing with Provides or shlibs files), possibly making those other packages uninstallable, is strongly discouraged.

The Release Team (which can be reached at debian-release@lists.debian.org) will regularly evaluate the uploads in proposed-updates and decide if your package can be included in stable. Please be clear (and verbose, if necessary) in your changelog entries for uploads to stable, because otherwise the package won't be considered for inclusion.

6.5 Uploading a package

6.5.1 Uploading to ftp-master

To upload a package, you need a personal account on ftp-master.debian.org, which you should have as an official maintainer. If you use scp or rsync to transfer the files, place them into /org/ftp.debian.org/incoming/; if you use anonymous FTP to upload, place them into /pub/UploadQueue/. Please note that you should transfer the changes file last. Otherwise, your upload may be rejected because the archive maintenance software will parse the changes file and see that not all files have been uploaded. If you don't want to bother with transfering the changes file last, you can simply copy your files to a temporary directory on ftp-master and then move them to /org/ftp.debian.org/incoming/.

Note: Do not upload to ftp-master packages containing software that is patent-restricted by the United States government, any cryptographic packages which belong in contrib or non-free. If you can't upload it to ftp-master, then neither can you upload it to the overseas upload queues on chiark or erlangen. Uploads of such software should go to non-us (see Uploading to non-US (pandora), Section 6.5.2). If you are not sure whether U.S. patent controls or cryptographic controls apply to your package, post a message to debian-devel@lists.debian.org and ask.

You may also find the Debian packages dupload or dput useful when uploading packages. These handy program are distributed with defaults for uploading via ftp to ftp-master, chiark, and erlangen. It can also be configured to use ssh or rsync. See dupload(1), dupload(5) and dput(1) for more information.

After uploading your package, you can check how the archive maintenance software will process it by running dinstall on your changes file:

     dinstall -n foo.changes

6.5.2 Uploading to non-US (pandora)

As discussed above, export controlled software should not be uploaded to ftp-master. Instead, upload the package to non-us.debian.org, placing the files in /org/non-us.debian.org/incoming/ (both dupload, Section 12.9 and dput, Section 12.10 can be used also, with the right invokation). By default, you can use the same account/password that works on ftp-master. If you use anonymous FTP to upload, place the files into /pub/UploadQueue/.

You can check your upload the same way it's done on ftp-master, with:

     dinstall -n foo.changes

Note that U.S. residents or citizens are subject to restrictions on export of cryptographic software. As of this writing, U.S. citizens are allowed to export some cryptographic software, subject to notification rules by the U.S. Department of Commerce. However, this restriction has been waived for software which is already available outside the U.S. Therefore, any cryptographic software which belongs in the main section of the Debian archive and does not depend on any package outside of main (e.g., does not depend on anything in non-US/main) can be uploaded to ftp-master or its queues, described above.

Debian policy does not prevent upload to non-US by U.S. residents or citizens, but care should be taken in doing so. It is recommended that developers take all necessary steps to ensure that they are not breaking current US law by doing an upload to non-US, including consulting a lawyer.

For packages in non-US/main, non-US/contrib, developers should at least follow the procedure outlined by the US Government. Maintainers of non-US/non-free packages should further consult the rules on notification of export of non-free software.

This section is for information only and does not constitute legal advice. Again, it is strongly recommended that U.S. citizens and residents consult a lawyer before doing uploads to non-US.

6.5.3 Uploads via chiark

If you have a slow network connection to ftp-master, there are alternatives. One is to upload files to Incoming via a upload queue in Europe on chiark. For details connect to ftp://ftp.chiark.greenend.org.uk/pub/debian/private/project/README.how-to-upload.

Note: Do not upload packages containing software that is export-controlled by the United States government to the queue on chiark. Since this upload queue goes to ftp-master, the prescription found in Uploading to ftp-master, Section 6.5.1 applies here as well.

The program dupload comes with support for uploading to chiark; please refer to the documentation that comes with the program for details.

6.5.4 Uploads via erlangen

Another upload queue is available in Germany: just upload the files via anonymous FTP to ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue/.

The upload must be a complete Debian upload, as you would put it into ftp-master's Incoming, i.e., a .changes files along with the other files mentioned in the .changes. The queue daemon also checks that the .changes is correctly PGP-signed by a Debian developer, so that no bogus files can find their way to ftp-master via this queue. Please also make sure that the Maintainer field in the .changes contains your e-mail address. The address found there is used for all replies, just as on ftp-master.

There's no need to move your files into a second directory after the upload, as on chiark. And, in any case, you should get a mail reply from the queue daemon explaining what happened to your upload. Hopefully it should have been moved to ftp-master, but in case of errors you're notified, too.

Note: Do not upload packages containing software that is export-controlled by the United States government to the queue on erlangen. Since this upload queue goes to ftp-master, the prescription found in Uploading to ftp-master, Section 6.5.1 applies here as well.

The program dupload comes with support for uploading to erlangen; please refer to the documentation that comes with the program for details.

6.5.5 Other Upload Queues

Another upload queue is available which is based in the US, and is a good backup when there are problems reaching ftp-master. You can upload files, just as in erlangen, to ftp://samosa.debian.org/pub/UploadQueue/.

An upload queue is available in Japan: just upload the files via anonymous FTP to ftp://master.debian.or.jp/pub/Incoming/upload/.

6.6 Announcing package uploads

When a package is uploaded, an announcement should be posted to one of the ``debian-changes'' lists. This is now done automatically by the archive maintenance software when it runs (usually once a day). You just need to use a recent dpkg-dev (>= 1.4.1.2). The mail generated by the archive maintenance software will contain the PGP/GPG signed .changes files that you uploaded with your package. Previously, dupload used to send those announcements, so please make sure that you configured your dupload not to send those announcements (check its documentation and look for ``dinstall_runs'').

If a package is released with the Distribution: set to `stable', the announcement is sent to debian-changes@lists.debian.org. If a package is released with Distribution: set to `unstable', or `experimental', the announcement will be posted to debian-devel-changes@lists.debian.org instead.

The dupload program is clever enough to determine where the announcement should go, and will automatically mail the announcement to the right list. See dupload, Section 12.9.

6.7 Notification that a new package has been installed

The Debian archive maintainers are responsible for handling package uploads. For the most part, uploads are automatically handled on a daily basis by the archive maintenance tools, katie. Specifically, updates to existing packages to the `unstable' distribution are handled automatically. In other cases, notably new packages, placing the uploaded package into the distribution is handled manually. When uploads are handled manually, the change to the archive may take up to a month to occur. Please be patient.

In any case, you will receive email notification indicating that the package has added to the archive, which also indicates which bugs will be closed by the upload. Please examine this notification carefully, checking if any bugs you meant to close didn't get triggered.

The installation notification also includes information on what section the package was inserted into. If there is a disparity, you will receive a separate email notifying you of that. Read on below.

6.7.1 The override file

The debian/control file's Section and Priority fields do not actually specify where the file will be placed in the archive, nor its priority. In order to retain the overall integrity of the archive, it is the archive maintainers who have control over these fields. The values in the debian/control file are actually just hints.

The archive maintainers keep track of the canonical sections and priorities for packages in the override file. If there is a disparity between the override file and the package's fields as indicated in debian/control, then you will receive an email noting the divergence when the package is installed into the archive. You can either correct your debian/control file for your next upload, or else you may wish to make a change in the override file.

To alter the actual section that a package is put in, you need to first make sure that the debian/control in your package is accurate. Next, send an email override-change@debian.org or submit a bug against ftp.debian.org requesting that the section or priority for your package be changed from the old section or priority to the new one. Be sure to explain your reasoning.

For more information about override files, see dpkg-scanpackages(8), /usr/share/doc/debian/bug-log-mailserver.txt, and /usr/share/doc/debian/bug-maint-info.txt.

Debian Developer's Reference