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:
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.
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.
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.
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).
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 11.2.
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.
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.
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.
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.
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.
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.
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
.