[ previous ] [ Copyright Notice ] [ Contents ] [ next ]

Debian Developer's Reference
Chapter 6 Package uploads


6.1 Announcing 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 ensures that no one is already working on packaging that software, and that effort is not duplicated. Assuming no one else is already working on your prospective package, you must then send a short email to debian-devel@lists.debian.org describing your plan to create a new package. You should set the subject of the email to ``intent to package foo'', substituting the name of the new package for foo.

There are a number of reasons why we ask maintainers to follow these steps:


6.2 Uploading a package


6.2.1 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:

All of these fields are mandatory for a Debian upload. See the list of control fields in the Debian Packaging 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. Only the Distribution field is discussed in this section, since it relates to the archive maintenance policies.


6.2.2 Picking a distribution

Notably, the Distribution field, which originates from the debian/changelog file, indicates which distribution the package is intended for. There are four possible values for this field: `stable', `unstable', `frozen', or `experimental'; these values can also be combined. For instance, if you have a crucial security fix release of a package, and the package has not diverged between the stable and unstable distributions, then you might put `stable unstable' in the changelog's Distribution field. Or, if Debian has been frozen, and you want to get a bug-fix release into frozen, you would set the distribution to `frozen unstable'. (See Uploading to frozen, Section 6.2.2.1 for more information on when to upload to frozen.) Note that it never makes sense to combine the experimental distribution with anything else. Also note that setting the distribution 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. The Release Team (which can be reached at debian-release@lists.debian.org) will decide if your package can be included in stable, therefore if your changelog entry is not clear enough, you may want to explain them why you uploaded your package to stable by sending them a short explication.

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; subsequent times the very same tar file should be used to build the new diffs and .dsc files, and it need not then be 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 then 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 then the new version of the original source should be uploaded, possibly by using the -sa flag.


6.2.2.1 Uploading to frozen

The Debian freeze is a crucial time for Debian. It is our chance to synchronize and stabilize our distribution as a whole. Therefore, care must be taken when uploading to frozen.

It is tempting to always try to get the newest release of software into the release. However, it's much more important that the system as a whole is stable and works as expected.

The watchword for uploading to frozen is no new code. This is a difficult thing to quantify, so here are some guidelines:

Remember, there is statistically a 15% chance that every bug fix will introduce a new bug. The introduction and discovery of new bugs either delays release or weakens the final product. There is little correlation between the severity of the original bug and the severity of the introduced bug.


6.2.3 Checking the package prior to upload

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


6.2.4 Uploading to master

To upload a package, you need a personal account on master.debian.org. All maintainers should already have this account, see The master server, Section 4.2.1. You can use either scp or ftp to transfer the files. In either case, the files need to be placed into /home/Debian/ftp/private/project/Incoming/. (You cannot upload to Incoming on master using anonymous FTP -- you must use your user-name and password.)

Note: Do not upload packages containing software that is export-controlled by the United States government to master, nor to the overseas upload queues on chiark or erlangen. This prohibition covers almost all cryptographic software, and even sometimes software that contains ``hooks'' to cryptographic software, such as electronic mail readers that support PGP encryption and authentication. Uploads of such software should go to non-us (see Uploading to pandora (non-us), Section 6.2.5). If you are not sure whether U.S. export controls apply to your package, post a message to debian-devel@lists.debian.org and ask.

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

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

     ~maor/dinstall/dinstall -n foo.changes


6.2.5 Uploading to pandora (non-us)

As discussed above, export controlled software should not be uploaded to master. Instead, use non-anonymous FTP or scp to copy the package to pandora.debian.org, placing the files in /org/non-us.debian.org/incoming/. By default, you can use your same account which works on master.

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

Just as for an upload to master, you can check your upload with :

     /org/non-us.debian.org/scripts/dinstall/dinstall -n foo.changes


6.2.6 Uploads via chiark

If you have a slow network connection to 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 master, the prescription found in Uploading to master, Section 6.2.4 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.2.7 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 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 master via the 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 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 some mail reply from the queue daemon what happened to your upload. Hopefully it should have been moved to 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 master, the prescription found in Uploading to master, Section 6.2.4 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.2.8 Other Upload Queues

Another upload queue is available which is based in the US, and is a good backup when there are problems reaching 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.3 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 dinstall when it runs (usually once a day), you just need to use a recent dpkg-dev (>= 1.4.1.2). Before that, dupload was used to send those announcements, please make sure that you configured your dupload to no more send those announcements (check its documentation and look for dinstall_runs). The mail generated by dinstall will contain the PGP/GPG signed .changes files that you uploaded with your package.

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', `experimental', or `frozen' (when present), the announcement will be posted to debian-devel-changes@lists.debian.org instead.

On occasion, it is necessary to upload a package to both the stable and unstable distributions; this is done by putting both distributions in the Distribution: line. In such a case the upload announcement will go to both of the above mailing lists.

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


6.4 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 an archive maintenance tool called dinstall. 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 week to occur (please be patient).

In any case, you will receive notification indicating that the package has been uploaded via email. Please examine this notification carefully. You may notice that the package didn't go into the section you thought you set it to go into. Read on for why.


6.4.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. Sometimes the override file needs correcting. Simply changing the package's control file is not going to work. Instead, you should email override-change@debian.org or submit a bug against ftp.debian.org.

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


[ previous ] [ Copyright Notice ] [ Contents ] [ next ]
Debian Developer's Reference
ver. 2.7.2, 16 April, 2000
Adam Di Carlo, current maintainer aph@debian.org
Christian Schwarz schwarz@debian.org
Ian Jackson ijackson@gnu.ai.mit.edu