[back] [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 foobar'', substituting the name of the new package for foobar.

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. Only the Distribution field is discussed here, 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, subsubsection 6.2.2.1 for more information on when to upload to frozen.) 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. Also note that it never makes sense to combine the experimental distribution with anything else.

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. You can use either ssh 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, or 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 below). 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.


6.2.5 Uploads via chiark

If you have a slow network connection to master, there are alternatives. One is to upload files to Incoming via a cron-driven upload queue in Europe on chiark. For details connect to ftp.chiark.greenend.org.uk using anonymous FTP and read /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, subsection 6.2.4 applies here as well.

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


6.2.6 Uploads via erlangen

Another cron-driven 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, subsection 6.2.4 applies here as well.

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


6.2.7 Uploading to the non-us server

To upload a package to the non-us server you just have to transfer the files via anonymous ftp to ftp://non-us.debian.org/pub/debian-non-US/Incoming. Note, that the .changes file must have a valid PGP signature from one of the keys of the developers key-ring.


6.3 Announcing package uploads

When a package is uploaded an announcement should be posted to one of the ``debian-changes'' lists. The announcement should give the (source) package name and version number, and a very short summary of the changes, in the Subject field, and should contain the PGP-signed .changes file. Some additional explanatory text may be added before the start of the .changes file.

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 should 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 should 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.6.


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.


[back] [Copyright Notice] [Contents] [next]
Debian Developer's Reference
ver. 2.6.0, 11 February, 1999
Adam Di Carlo, current maintainer aph@debian.org
Christian Schwarz schwarz@debian.org
Ian Jackson ijackson@gnu.ai.mit.edu