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:
debian-devel@lists.debian.org
@;
will be picked up the the WNPP maintainer, and your intention will be published
in subsequent versions of the WNPP document.
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.
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.
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.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
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
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.
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.
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/
.
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.
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
.
aph@debian.org
schwarz@debian.org
ijackson@gnu.ai.mit.edu