X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=675097fb6405008e5e2c8951ca5884a061b034af;hp=8b59385eb5fa70944b117dccb42a124fa961c50e;hb=b191c0ce93fe448e0573be2ad4ed324f453b659e;hpb=d077cc7ca5d4d8fc3fc05051e7ac0ded11f42e29 diff --git a/developers-reference.sgml b/developers-reference.sgml index 8b59385..675097f 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -2,16 +2,15 @@ %versiondata; - + %commondata; - + + - + revision of the original developer's reference in cvs-en-rev --> + FIXME: "> @@ -22,7 +21,8 @@
It should be clear that this reference does not discuss the technical
-details of the Debian package nor how to generate Debian packages.
+details of Debian packages nor how to generate them.
Nor does this reference detail the standards to which Debian software
must comply. All of such information can be found in the
When you have found an advocate, have your GnuPG key signed and have
@@ -256,7 +259,8 @@ but are waiting for your new maintainer application to go through, you
might be able find a sponsor to upload your package for you. Sponsors
are people who are official Debian maintainers, and who are willing to
criticize and upload your packages for you. Those who are seeking a
-sponsor can request one at
If you wish to be a mentor and/or sponsor, more information is
available in .
@@ -333,7 +337,7 @@ security update, etc.) occurs while you're on vacation. Sometimes it's
nothing as critical as that, but it's still appropriate to let the others
know that you're unavailable.
-In order to inform the other developers, there's two things that you should do.
+In order to inform the other developers, there are two things that you should do.
First send a mail to &email-debian-private; with "[VAC] " prepended to the
subject of your message
A big part of your job as Debian maintainer will be to stay in contact
with the upstream developers. Debian users will sometimes report bugs
-to the Bug Tracking System that are not specific to Debian. You
-must forward these bug reports to the upstream developers so that
-they can be fixed in a future release. It's not your job to fix
-non-Debian specific bugs. However, if you are able to do so, you are
-encouraged to contribute to upstream development of the package by
-providing a fix for the bug. Debian users and developers will often
-submit patches to fix upstream bugs, and you should evaluate and
-forward these patches upstream.
+that are not specific to Debian to our bug tracking system. You
+have to forward these bug reports to the upstream developers so that
+they can be fixed in a future upstream release.
+
+While it's not your job to fix non-Debian specific bugs, you may freely
+do so if you're able. When you make such fixes, be sure to pass them on
+to the upstream maintainers as well. Debian users and developers will
+sometimes submit patches to fix upstream bugs — you should evaluate
+and forward these patches upstream.
If you need to modify the upstream sources in order to build a policy
compliant package, then you should propose a nice fix to the upstream
@@ -370,7 +375,7 @@ need, always try not to fork from the upstream sources.
Generally you should deal with bug reports on your packages as described in
. However, there's a special category of bugs that
-you need to take care of -- the so-called release-critical bugs (RC bugs).
+you need to take care of — the so-called release-critical bugs (RC bugs).
All bug reports that have severity critical, grave or
serious are considered to have an impact on whether the package can
be released in the next stable release of Debian.
@@ -417,10 +422,29 @@ resources that are available to help you in your maintainer work.
-The mailing list server is at &lists-host;.
+Much of the conversation between Debian developers (and users) is managed
+through a wide array of mailing lists we host at
+
+When replying to messages on the mailing list, please do not send a
+carbon copy (CC) to the original poster unless they explicitly
+request to be copied. Anyone who posts to a mailing list should read
+it to see the responses.
+
+Cross-posting (sending the same message to multiple lists) is discouraged.
+As ever on the net, please trim down the quoting of articles you're
+replying to. In general, please adhere to the usual conventions for
+posting messages.
-Online archives of mailing lists are available at
@@ -441,40 +465,8 @@ The core Debian mailing lists that developers should use are:
-There are
-other mailing lists available for a variety of special topics; see
-
-To subscribe to or unsubscribe from any of the Debian mailing lists, email
-debian-foo-REQUEST@&lists-host;, where
-debian-foo is the name of the list, with the word
-subscribe in the Subject to subscribe to the list or
-unsubscribe to unsubscribe.
-
-If you prefer to use a web page to subscribe to multiple mailing lists,
-there's one at
-You can download the current list of mailing lists and basic usage
-instructions from
-When replying to messages on the mailing list, please do not send a
-carbon copy (CC) to the original poster unless they explicitly
-request to be copied. Anyone who posts to a mailing list should read
-it to see the responses.
-
-Cross-posting (sending the same message to multiple lists) is discouraged.
-As ever on the net, please trim down the quoting of articles you're
-replying to. In general, please adhere to the usual conventions for
-posting messages.
-
-Please read the
@@ -493,6 +485,18 @@ for Debian related correspondence such as contacting upstream authors
about licenses, bugs, etc. or discussing the project with others where it
might be useful to have the discussion archived somewhere.
+
+Before requesting a mailing list that relates to the development of a
+package (or a small group of related packages), please consider if using
+an alias (via a .forward-aliasname file on master.debian.org, which
+translates into a reasonably nice you-aliasname@debian.org
+address) or a self-managed mailing list on
+If you decide that a regular mailing list on lists.debian.org is really what
+you want, go ahead and fill in a request, following
@@ -590,17 +594,22 @@ administration (such as packages to be removed from the archive,
suggestions for the web site, etc.),
generally you'll report a bug against a ``pseudo-package''. See for information on how to submit bugs.
+
+Some of the core servers are restricted, but the information from there
+is mirror to another server.
&bugs-host; is the canonical location for the Bug Tracking
-System (BTS). If you plan on doing some statistical analysis or
+System (BTS).
+
+It is restricted; a mirror is available on merkel.
+
+If you plan on doing some statistical analysis or
processing of Debian bugs, this would be the place to do it. Please
describe your plans on &email-debian-devel; before implementing
anything, however, to reduce unnecessary duplication of effort or
wasted processing time.
-
-All Debian developers have accounts on &bugs-host;.
@@ -608,6 +617,8 @@ The ftp-master.debian.org server holds the canonical copy of the Debian
archive (excluding the non-US packages). Generally, package uploads
go to this server; see .
+It is restricted; a mirror is available on merkel.
+
Problems with the Debian FTP archive generally need to be reported as
bugs against the
+On some machines, there are chroots to different distributions available.
+You can use them like
+
+
@@ -715,7 +740,7 @@ Those features are documented at
The &debian-formal; distribution consists of a lot of packages
(
Here is an example directory tree of a complete Debian archive:
@@ -740,13 +765,13 @@ In each of the areas, there is a directory for the source packages
(
-The
The main section of the Debian archive is what makes up the
official &debian-formal; distribution. The
@@ -808,7 +833,7 @@ The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola
Linux 2.2 kernel supports even more architectures, including ARM and
UltraSPARC. Since Linux supports these platforms, Debian decided that
it should, too. Therefore, Debian has ports underway; in fact, we
-also have ports underway to non-Linux kernel. Aside from
+also have ports underway to non-Linux kernels. Aside from
i386 (our name for Intel x86), there is m68k,
alpha, powerpc, sparc, hurd-i386,
arm, ia64, hppa, s390, mips,
@@ -822,7 +847,7 @@ ships for the i386, m68k, alpha, and
support of five new architectures: ia64, hppa,
s390, mips and mipsel.
-Information for developers or uses about the specific ports are
+Information for developers and users about the specific ports are
available at the
- is generated automatically by taking
+The
After a period of development, once the release manager deems fit, the
testing distribution is frozen, meaning that the policies
@@ -927,61 +953,14 @@ Note that development under unstable continues during the
freeze period, since the unstable distribution remains in
place in parallel with testing.
-
+Packages are usually installed into the `testing' distribution after they
+have undergone some degree of testing in unstable.
-The scripts that update the testing distribution are run each
-day after the installation of the updated packages. They generate the
-
-The inclusion of a package from unstable is conditional on
-the following:
-
-To find out whether a package is progressing into testing or not, see the
-testing script output on the
-The
-Sometimes, some packages never enter testing because the set of
-inter-relationship is too complicated and can not be sorted out
-by the scripts. In that case, the release manager must be
-contacted, and he will force the inclusion of the packages.
-
-In general, please refer to the
@@ -1011,7 +990,7 @@ into experimental.
Whenever there is a new upstream version of a package that introduces new
features but breaks a lot of old ones, it should either not be uploaded, or
be uploaded to experimental. A new, beta, version of some software
-which uses completely different configuration can go into
+which uses a completely different configuration can go into
experimental, at the maintainer's discretion. If you are working
on an incompatible or complex upgrade situation, you can also use
experimental as a staging area, so that testers can get early
@@ -1030,7 +1009,10 @@ New software which isn't likely to damage your system can go directly into
An alternative to experimental is to use your personal web space
on people.debian.org.
-
+
+Please consider to use the option -v to
@@ -1074,8 +1056,8 @@ symbolic links for stable, testing, and
The various download archives and the web site have several mirrors
available in order to relieve our canonical servers from heavy load.
-In fact, some of the canonical servers aren't public, and instead a
-first tier of mirrors balances the load. That way, users always access
+In fact, some of the canonical servers aren't public — a first tier
+of mirrors balances the load instead. That way, users always access
the mirrors and get used to using them, which allows Debian to better
spread its bandwidth requirements over several servers and networks,
and basically makes users avoid hammering on one primary location.
@@ -1097,15 +1079,16 @@ have accounts on these machines.
-The Incoming system is responsible of collecting updated packages and
+The Incoming system is responsible for collecting updated packages and
installing them in the Debian archive. It consists of a set of
directories and scripts that are installed both on &ftp-master-host;
and &non-us-host;.
Packages are uploaded by all the maintainers into a directory called
+Note: This description here is currently disabled, because
+ftp-master is restricted. Please see for
+the currently working way.
The
-The bug tracking system track bugs for each package. You can
-view the bugs of a given package at the URL
+The bug tracking system tracks bugs for each package.
+You can view the bugs of a given package at the URL
http://&bugs-host;/package-name.
-The Package Tracking System (PTS) is basically a tool to track by mail
-the activity of a source package. You just have to subscribe
-to a source package to start getting the mails related to it.
-You get the same mails as the maintainer. Each mail
-sent through the PTS is classified and associated to one of
-the keyword listed below. This will let you select the mails that
+The Package Tracking System (PTS) is an email-based tool to track
+the activity of a source package. This really means that you can
+get the same emails that the package maintainer gets, simply by
+subscribing to the package in the PTS.
+
+Each email sent through the PTS is classified under one of
+the keywords listed below. This will let you select the mails that
you want to receive.
By default you will get:
@@ -1236,46 +1224,48 @@ All the bug reports and following discussions.
-You can also decide to receive some more information:
+You can also decide to receive additional information:
Once you are subscribed to a package, you will get the mails sent to
-srcpackage@packages.qa.debian.org. Those mails
+sourcepackage@packages.qa.debian.org. Those mails
have special headers appended to let you filter them in a special
-mailbox with
@@ -1372,64 +1361,64 @@ X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org
If you use a publicly accessible CVS repository for maintaining
your Debian package you may want to forward the commit notification
-to the PTS so that the subscribers (possible co-maintainers) can
+to the PTS so that the subscribers (and possible co-maintainers) can
closely follow the package's evolution.
-It's very easy to setup. Once your CVS repository generates commit
-notifications, you just have to make sure it sends a copy of those mails
-to srcpackage_cvs@&pts-host;. Only people who
-accepts the cvs keyword will receive the notifications.
+Once you set up the CVS repository to generate commit notifications,
+you just have to make sure it sends a copy of those mails
+to sourcepackage_cvs@&pts-host;. Only the people
+who accept the cvs keyword will receive these notifications.
-The PTS has been extended with a web interface that puts together
-many information about each source package. It features many useful
+The PTS has a web interface at
You can jump directly to the web page concerning a specific source package
-with an url like http://&pts-host;/srcpackage. Otherwise
-you can go through the
This web interface has been designed like a portal for the development of
-packages: you can add custom content on the pages of your packages. You can
-add "static information" (news item that are meant to stay available
+packages: you can add custom content on your packages' pages. You can
+add "static information" (news items that are meant to stay available
indefinitely) and news items in the "latest news" section.
-Static news can be used to indicate:
+Static news items can be used to indicate:
-Both kind of news are generated in a similar manner: you just have to send a mail
-either to
-Some examples of valid mails used to generate news item in the PTS are following. The first one
-adds a link to the cvsweb interface of debian-cd in the "Static information" section.
+Here are a few examples of valid mails used to generate news items in
+the PTS. The first one adds a link to the cvsweb interface of debian-cd
+in the "Static information" section:
+The second one is an announcement sent to a mailing list which is also sent
to the PTS so that it is published on the PTS web page of the package. Note the
-use of the BCC field to avoid answers sent to the PTS by mistake ...
+use of the BCC field to avoid answers sent to the PTS by mistake.
-Think twice before adding a news to the PTS because you won't be able to
-remove it later and you wan't be able to edit it either. The only thing that you
-can do is send a second news that will deprecate the information contained in
-the first news.
+Think twice before adding a news item to the PTS because you won't be able
+to remove it later and you wan't be able to edit it either. The only thing
+that you can do is send a second news item that will deprecate the
+information contained in the previous one.
@@ -1474,6 +1464,21 @@ It is a good idea to look up your own data regularly so that
you don't forget any open bug, and so that you don't forget which
packages are under your responsibility.
+
+Alioth is a fairly new Debian service, based on a slightly modified version
+of the GForge software (which evolved from SourceForge). This software
+offers developers access to easy-to-use tools such as bug trackers, patch
+manager, project/task managers, file hosting services, mailing lists, CVS
+repositories etc. All these tools are managed via a web interface.
+
+It is intended to provide facilities to free software projects backed or led
+by Debian, facilitate contributions from external developers to projects
+started by Debian, and help projects whose goals are the promotion of Debian
+or its derivatives.
+
+For more information please visit
@@ -1555,7 +1560,7 @@ Changelog entries can be used to automatically close Debian bugs when
the package is installed into the archive. See .
-It is conventional that the changelog entry notating of a package that
+It is conventional that the changelog entry of a package that
contains a new upstream version of the software looks like this:
-It is technically possible to upload a package into several distributions
-at the same time but it usually doesn't make sense to use that feature
-because the dependencies of the package may vary with the distribution.
-In particular, it never makes sense to combine the experimental
-distribution with anything else (see ).
+It is not possible to upload a package into several distributions
+at the same time.
-It is discouraged to change anything else in the package that isn't
-important, because even trivial fixes can cause bugs later on.
+Changing anything else in the package that isn't important is discouraged,
+because even trivial fixes can cause bugs later on.
Packages uploaded to stable need to be compiled on systems running
stable, so that their dependencies are limited to the libraries
@@ -1703,50 +1705,32 @@ 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.
+
+It's best practice to speak with the stable release manager before
+uploading to stable/stable-proposed-updates, so that the
+uploaded package fits the needs of the next point release.
-The testing distribution is fed with packages from unstable according to the rules
-explained in . However, the release manager may stop the testing
-scripts when he wants to freeze the distribution. In that case, you may want to
-upload to testing-proposed-updates to provide fixed packages during the freeze.
-
-Keep in mind that packages uploaded there are not automatically processed, they
-have to go through the hands of the release manager. So you'd better have a good
-reason to upload there. In order to know what a good reason is in the
-release manager's eyes, you should read the instructions that he regularly
-gives on &email-debian-devel-announce;.
-
-You should not upload to testing-proposed-updates when you can update your
-packages through unstable. If you can't (for example because you have a
-newer development version in unstable), you may use it but it is recommended to ask
-the authorization of the release manager before.
+Please see the information in the
-To upload a package, you need a personal account on
-
-If you want to use feature described in ,
-you'll have to upload to ftp-master. It is the only upload
-point that supported delayed incoming.
+To upload a package, you should upload the files (including the signed
+changes and dsc-file) with anonymous ftp to
+
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 transferring
-the changes file last, you can simply copy your files to a temporary
-directory on ftp-master and then move them to
-&us-upload-dir;.
-
+all files have been uploaded.
+
Note: Do not upload to ftp-master cryptographic
packages which belong to contrib or non-free. Uploads of
such software should go to non-us (see ftp-master; depending on the case they may still be uploaded to
You may also find the Debian packages or
useful
-when uploading packages. These handy programs help automate the
+when uploading packages. These handy programs help automate the
process of uploading packages into Debian.
-After uploading your package, you can check how the archive
-maintenance software will process it by running
-Note that
-As discussed above, export controlled software should not be uploaded
-to ftp-master. Instead, upload the package to
-
-You can check your upload the same way it's done on ftp-master,
-with:
-
Note that U.S. residents or citizens are subject to restrictions on
export of cryptographic software. As of this writing, U.S. citizens
@@ -1816,64 +1791,50 @@ advice. Again, it is strongly recommended that U.S. citizens and
residents consult a lawyer before doing uploads to non-US.
-
-If you have a slow network connection to ftp-master, there are
-alternatives. One is to upload files to
-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 applies here as well.
-
-The program
-Another upload queue is available in Germany: just upload the files
-via anonymous FTP to
-The upload must be a complete Debian upload, as you would put it into
-ftp-master's
-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.
+With a fairly recent dput, this section
+
-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
+Note:
+Since this upload queue goes to ftp-master, the
prescription found in applies here as well.
-
-The program
+Do NOT upload a package to the security upload queue (oldstable-security,
+stable-security, etc.) without prior authorization from the security
+team. If the package does not exactly meet the team's requirements, it
+will cause many problems and delays in dealing with the unwanted upload.
+For details, please see section .
-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
-An upload queue is available in Japan: just upload the files via
-anonymous FTP to
+The queues on master.debian.org, samosa.debian.org, master.debian.or.jp
+and ftp.chiark.greenend.org.uk are down permanently and will not be
+resurrected. The queue in Japan will be replaced with a new queue on
+hp.debian.or.jp some day.
+
+For the time being, the anonymous ftp queue on auric.debian.org (the
+former ftp-master) works, but it is deprecated and will be removed at
+some point in the future.
The
-Note also that the term "section" is used for the separation of packages
-according to their licensing, e.g. main, contrib and
-non-free. This is described in another section, .
+Note that the Section field describes both the section as
+well as the subsection, which are described in . If the section is "main", it should be
+omitted. The list of allowable subsections can be found in
The bug tracking system's features interesting to developers are described
in the
Operations such as reassigning bugs to other packages, merging separate
bug reports about the same issue, or reopening bugs when they are
@@ -1979,9 +1942,8 @@ maintainer address.
When responding to bugs, make sure that any discussion you have about
-bugs are sent both to
-the original submitter of the bug, and the bug itself (e.g.,
-
-If the bug submitter disagree with your decision to close the bug,
+If the bug submitter disagrees with your decision to close the bug,
they may reopen it until you find an agreement on how to handle it.
If you don't find any, you may want to tag the bug wontfix
to let people know that the bug exists but that it won't be corrected.
@@ -2043,10 +2005,10 @@ the BTS if you wish to keep it reported against your package). Before
doing so, please read the
Sometimes you also have to adjust the severity of the bug so that it
matches our definition of the severity. That's because people tend to
@@ -2054,8 +2016,8 @@ inflate the severity of bugs to make sure their bugs are fixed quickly.
Some bugs may even be dropped to wishlist severity when the requested
change is just cosmetic.
For general information on how to write your changelog entries, see
@@ -2153,8 +2115,10 @@ security advisories, and maintaining security.debian.org.
When you become aware of a security-related bug in a Debian package,
whether or not you are the maintainer, collect pertinent information
about the problem, and promptly contact the security team at
-&email-security-team; as soon as possible. Useful information
-includes, for example:
+&email-security-team; as soon as possible. DO NOT UPLOAD any
+packages for stable; the security team will do that.
+
+Useful information includes, for example:
There are two reasons for releasing information even though secrecy is
-requested: the problem has been known for a while, or that the problem
+requested: the problem has been known for a while, or the problem
or exploit has become public.
+Do NOT include any changes in your package which are
+not directly related to fixing the vulnerability. These will only
+need to be reverted, and this wastes time. If there are other bugs in
+your package that you would like to fix, make an upload to
+proposed-updates in the usual way, after the security advisory is
+issued. The security update mechanism is not a means for introducing
+changes to your package which would otherwise be rejected from the
+stable release, so please do not attempt to do this.
+
Review and test your changes as much as possible. Check the
differences from the previous version repeatedly
(
-When packaging the fix, keep the following points in mind:
+Be sure to verify the following items:
-DO NOT upload a package to the security upload queue
+Do NOT upload a package to the security upload queue
(oldstable-security, stable-security, etc.) without
prior authorization from the security team. If the package does not
exactly meet the team's requirements, it will cause many problems and
delays in dealing with the unwanted upload.
-DO NOT upload your fix to proposed-updates without
+Do NOT upload your fix to proposed-updates without
coordinating with the security team. Packages from
security.debian.org will be copied into the proposed-updates directory
automatically. If a package with the same or a higher version number
@@ -2438,9 +2421,9 @@ avoid unwanted removals and to keep a trace of why a package has been
removed. For example, you can provide the name of the package that
supersedes the one to be removed.
-Usually you only ask the removal of a package maintained by yourself.
+Usually you only ask for the removal of a package maintained by yourself.
If you want to remove another package, you have to get the approval
-of its last maintainer.
+of its maintainer.
If in doubt concerning whether a package is disposable, email
&email-debian-devel; asking for opinions. Also of interest is the
@@ -2448,6 +2431,7 @@ If in doubt concerning whether a package is disposable, email
package. When invoked as apt-cache showpkg
package, the program will show details for
package, including reverse depends.
+Removal of orphaned packages is discussed on &email-debian-qa;.
Once the package has been removed, the package's bugs should be handled.
They should either be reassigned to another package in the case where
@@ -2460,7 +2444,7 @@ software is simply no more part of Debian.
In the past, it was possible to remove packages from
-Sometimes you made a mistake naming the package and you need to rename
-it. In this case, you need to follow a two-step process. First, set
+When you make a mistake naming your package, you should follow a two-step
+process to rename it. First, set
your
-If the package is especially crucial to Debian, you should instead submit
+If you just intend to give the package away, but you can keep maintainership
+for the moment, then you should instead submit
a bug against
-Read instructions on the
@@ -2554,7 +2538,7 @@ portability. Therefore, even if you are not a porter, you should read
most of this chapter.
Porting is the act of building Debian packages for architectures that
-is different from the original architecture of the package
+are different from the original architecture of the package
maintainer's binary package. It is a unique and essential activity.
In fact, porters do most of the actual compiling of Debian packages.
For instance, for a single i386 binary package, there must be
@@ -2571,7 +2555,7 @@ the case. This section contains a checklist of ``gotchas'' often
committed by Debian maintainers — common problems which often stymie
porters, and make their jobs unnecessarily difficult.
-The first and most important watchword is to respond quickly to bug or
+The first and most important thing is to respond quickly to bug or
issues raised by porters. Please treat porters with courtesy, as if
they were in fact co-maintainers of your package (which in a way, they
are). Please be tolerant of succinct or even unclear bug reports,
@@ -2620,7 +2604,7 @@ They should be removed by the `clean' target of
Make sure you don't rely on locally installed or hacked configurations
or programs. For instance, you should never be calling programs in
-
-
-
-
-Usual news item may be used to announce that:
+Usual news items may be used to announce that:
-
In the first two cases, the information is public and it is important
@@ -2225,7 +2189,7 @@ itself is public, and can (and will) be examined by the general public.
-