X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=developers-reference.sgml;h=72e4c3a1aa8083097e3289d4569e275ffcb79563;hb=25d4d612ad700f4daa88037123e2a783d5913c3f;hp=a70f475adff0942cd7df80b0bfd0e3a8263292d9;hpb=b9ad716105a5129cd710814f0af93ea3767c7fde;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index a70f475..72e4c3a 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -5,7 +5,7 @@ %commondata; - + @@ -49,7 +49,7 @@ merchantability or fitness for a particular purpose. See the GNU General Public License for more details.
A copy of the GNU General Public License is available as &file-GPL; in
-the Debian GNU/Linux distribution or on the World Wide Web at
+When you know how you want to contribute to &debian-formal;, you
+should get in contact with existing Debian maintainers who are working
+on similar tasks. That way, you can learn from experienced developers.
+For example, if you are interested in packaging existing software for
+Debian you should try to get a sponsor. A sponsor will work together
+with you on your package and upload it to the Debian archive once he
+is happy with the packaging work you have done. You can find a sponsor
+by mailing the &email-debian-mentors; mailing list, describing your
+package and yourself and asking for a sponsor (see
+for more information on sponsoring). On the other hand, if you are
+interested in porting Debian to alternative architectures or kernels
+you can subscribe to port specific mailing lists and ask there how to
+get started. Finally, if you are interested in documentation or
+Quality Assurance (QA) work you can join maintainers already working on
+these tasks and submit patches and improvements.
+
-Before you decide to register with the Debian Project, you will need
-to read the
The process of registering as a developer is a process of verifying
-your identity and intentions. As the number of people working on
-Debian GNU/Linux has grown to over &number-of-maintainers; people and
-our systems are used in several very important places we have to be
-careful about being compromised. Therefore, we need to verify new
-maintainers before we can give them accounts on our servers and
-letting them upload packages.
-
-Registration requires that the following information be sent in
-appropriate steps described at
+Before you actually register you should have shown that you can do
+competent work and will be a good contributor. You can show this by
+submitting patches through the Bug Tracking System or having a package
+sponsored by an existing maintainer for a while. Also, we expect that
+contributors are interested in the whole project and not just in
+maintaining their own packages. If you can help other maintainers by
+providing further information on a bug or even a patch, then do so!
+
+Registration requires that you are familiar with Debian's philosophy
+and technical documentation. Furthermore, you need a GPG key which
+has been signed by an existing Debian maintainer. If your GPG key
+is not signed yet, you should try to meet a Debian maintainer in
+person to get your key signed. There's a
If you do not have an OpenPGP key yet, generate one. Every developer
needs a OpenPGP key in order to sign and verify package uploads. You
@@ -200,13 +198,6 @@ much less secure. Your key must be signed with at least your own user
ID; this prevents user ID tampering.
-Also remember that one of the names on your key must match the email
-address you list as the official maintainer for your packages. For
-instance, I set the maintainer of the
-
If your public key isn't on public key servers such as &pgp-keyserv;,
please read the documentation available locally in &file-keyservs;.
That document contains instructions on how to put your key on the
@@ -222,33 +213,33 @@ Some countries restrict the use of cryptographic software by their
citizens. This need not impede one's activities as a Debian package
maintainer however, as it may be perfectly legal to use cryptographic
products for authentication, rather than encryption purposes (as is
-the case in France). The Debian Project does not require the use of
+the case in France). &debian-formal; does not require the use of
cryptography qua cryptography in any manner. If you live in a
country where use of cryptography even for authentication is forbidden
then please contact us so we can make special arrangements.
-Once you have all your information ready, and your public key is
-available on public key servers, send a message to
-&email-new-maintainer; to register as an offical Debian developer so
-that you will be able to upload your packages. This message must
-contain your name and your valid e-mail address. All the information
-discussed above is required after your Application Manager is
-assigned. Application Manager is your agent in the registration
-process, and you can always ask him about the status of your
-application. You can check the
+When you have found an advocate, have your GPG key signed and have
+already contributed to Debian for a while, you're ready to apply.
+You can simply register on our
For more details, please consult
-Once this information is received and processed, you should be
-contacted with information about your new Debian maintainer account.
-If you don't hear anything within a month, please send a followup
-message asking if your original application was received. Do
-not re-send your original application, that will just confuse
-the New Maintainer Group. Please be patient, especially near release
-points; mistakes do occasionally happen, and people do sometimes run
-out of volunteer time.
+Maintainer's Corner"> at the Debian web site. Make sure that you
+are familiar with the necessary steps of the New Maintainer process
+before actually applying. If you are prepared well, you can save
+a lot of timer later on.
You have to keep the information available there up to date.
@@ -309,10 +300,14 @@ you're on vacation.
In order to inform the other developers, there's two things that you should do.
First send a mail to &email-debian-private; giving the period of time when
you will be on vacation. You can also give some special instructions on what to
-do if any problem occurs. Next you should update your information
+do if any problem occurs. Be aware that some people don't care for vacation
+notices and don't want to read them; you should prepend "[VAC] " to the
+subject of your message so that it can be easily filtered.
+
+Next you should update your information
available in the Debian LDAP database and mark yourself as ``on vacation''
(this information is only accessible to debian developers). Don't forget
-to remove the ``on vacation'' flag when you come back.
+to remove the ``on vacation'' flag when you come back!
@@ -339,31 +334,46 @@ Release Critical Bugs (RCB) are all bugs that have severity
critical, grave or serious.
Those bugs can delay the Debian release
and/or can justify the removal of a package at freeze time. That's why
-those bugs needs to be corrected as fast as possible. You must be
+these bugs need to be corrected as quickly as possible. You must be
aware that some developers who are part of the
Even though there is a dedicated group of people for Quality
-Assurance, QA duties are not reserved solely to them. You can
-participate in this effort by keeping your packages as bug free as
+Assurance, QA duties are not reserved solely for them. You can
+participate in this effort by keeping your packages as bug-free as
possible, and as lintian-clean (see ) as
-possible. If you think that it's quite impossible, then you should
-consider orphaning (see ) some of your packages so
-that you can do a good job with the other packages that you
-maintain. Alternatively you may ask the help of other people in order
-to catch up the backlog of bugs that you have (you can ask for help on
-&email-debian-qa; or &email-debian-devel;).
+possible. If you do not find that possible, then you should consider
+orphaning some of your packages (see ). Alternatively, you may ask the help of other people
+in order to catch up the backlog of bugs that you have (you can ask
+for help on &email-debian-qa; or &email-debian-devel;).
+
+
+If you notice that a package is lacking maintenance, you should
+make sure the maintainer is active and will continue to work on
+their packages. Try contacting them yourself.
+
+If you do not get a reply after a few weeks you should collect all
+useful information about this maintainer. Start by logging in to
+the
+Send all this information to &email-debian-qa;, in order to let the
+QA people do whatever is needed.
@@ -408,8 +418,8 @@ The following are the core Debian mailing lists: &email-debian-devel;,
&email-debian-policy;, &email-debian-user;, &email-debian-private;,
&email-debian-announce;, and &email-debian-devel-announce;. All
developers are expected to be subscribed to at least
-&email-debian-private; and &email-debian-devel-announce;. There are
-other mailing lists are available for a variety of special topics; see
+&email-debian-devel-announce;. There are
+other mailing lists available for a variety of special topics; see
@@ -559,7 +569,7 @@ id="&url-devel-machines;">.
-The Debian GNU/Linux distribution consists of a lot of Debian packages
+The &debian-formal; distribution consists of a lot of Debian packages
(.deb's, currently around &number-of-pkgs;) and a few
additional files (documentation, installation disk images, etc.).
@@ -598,10 +608,11 @@ further into subsections.
The main section of the Debian archive is what makes up the
-official Debian GNU/Linux distribution.
-The main section is official because it fully complies with
-all our guidelines. The other two sections do not, to different degrees;
-as such, they are not officially part of Debian GNU/Linux.
+official &debian-formal; distribution. The
+main section is official because it fully complies with all
+our guidelines. The other two sections do not, to different degrees;
+as such, they are not officially part of
+&debian-formal;.
Every package in the main section must fully comply with the
-Debian GNU/Linux 1.3 is only available as i386. Debian 2.0
+&debian-formal; 1.3 is only available as i386. Debian 2.0
shipped for i386 and m68k architectures. Debian 2.1
ships for the i386, m68k, alpha, and
sparc architectures. Debian 2.2 adds support for the
@@ -714,7 +725,7 @@ To summarize, the Debian archive has a root directory within an FTP
server. For instance, at the mirror site,
A distribution is comprised of Debian source and binary packages, and the
respective Sources and Packages index files, containing
@@ -723,9 +734,9 @@ the header information from all those packages. The former are kept in the
directory of the archive (because of backwards compatibility).
-
-There is always a distribution called stable (residing in
+There are always distributions called stable (residing in
dists/stable), one called testing (residing in
dists/testing), and one called unstable (residing in
dists/unstable). This reflects the development process of the
@@ -741,94 +752,91 @@ sometimes ``unstable.''
Packages get copied from unstable to testing if they
satisfy certain criteria. To get into testing distribution, a
-package needs to be in the archive for two weeks and not have any release
-critical bugs. After that period, it will propagate into testing
-as soon as anything it depends on is also added. This process is automatic.
+package needs to be in the archive for two weeks and not have any
+release critical bugs. After that period, it will propagate into
+testing as soon as anything it depends on is also added. This
+process is automatic. You can see some notes on this system as well
+as update_excuses (describing which packages are valid
+candidates, which are not, and why not) at
After a period of development, once the release manager deems fit, the
-testing distribution is renamed to frozen. Once
-that has been done, no changes are allowed to that distribution except
-bug fixes; that's why it's called ``frozen.'' After another month or
-a little longer, depending on the progress, the frozen distribution
+testing distribution is frozen, meaning that the policies
+which control how packages move from unstable to testing are
+tightened. Packages which are too buggy are removed. No changes are
+allowed into testing except for bug fixes. After some time
+has elapsed, depending on progress, the testing distribution
goes into a `deep freeze', when no changes are made to it except those
-needed for the installation system. This is called a ``test cycle'', and it
-can last up to two weeks. There can be several test cycles, until the
-distribution is prepared for release, as decided by the release manager.
-At the end of the last test cycle, the frozen distribution is
-renamed to stable, overriding the old stable distribution,
-which is removed at that time.
+needed for the installation system. This is called a ``test cycle'',
+and it can last up to two weeks. There can be several test cycles,
+until the distribution is prepared for release, as decided by the
+release manager. At the end of the last test cycle, the
+testing distribution is renamed to stable,
+overriding the old stable distribution, which is removed at
+that time (although they can be found at archive-host;).
This development cycle is based on the assumption that the
unstable distribution becomes stable after passing a
-period of testing as frozen. Even once a distribution is
-considered stable, a few bugs inevitably remain--that's why the stable
-distribution is updated every now and then. However, these updates are
-tested very carefully and have to be introduced into the archive
-individually to reduce the risk of introducing new bugs. You can find
-proposed additions to stable in the proposed-updates
-directory. Those packages in proposed-updates that pass
-muster are periodically moved as a batch into the stable distribution
-and the revision level of the stable distribution is incremented
-(e.g., `1.3' becomes `1.3r1', `2.0r2' becomes `2.0r3', and so forth).
+period of being in testing. Even once a distribution is
+considered stable, a few bugs inevitably remain &mdash that's why the
+stable distribution is updated every now and then. However, these
+updates are tested very carefully and have to be introduced into the
+archive individually to reduce the risk of introducing new bugs. You
+can find proposed additions to stable in the
+proposed-updates directory. Those packages in
+proposed-updates that pass muster are periodically moved as a
+batch into the stable distribution and the revision level of the
+stable distribution is incremented (e.g., `1.3' becomes `1.3r1',
+`2.0r2' becomes `2.0r3', and so forth).
Note that development under unstable continues during the
``freeze'' period, since the unstable distribution remains in
-place when the testing is moved to frozen.
-Another wrinkle is that when the frozen distribution is
-offically released, the old stable distribution is completely removed
-from the Debian archives (although they do live on at
-archive-host;).
-
-In summary, there is always a stable, a testing and an
-unstable distribution available, and a frozen distribution
-shows up for a couple of months from time to time.
-
+place in parallel with testing.
The experimental distribution is a specialty distribution.
It is not a full distribution in the same sense as `stable' and
`unstable' are. Instead, it is meant to be a temporary staging area
for highly experimental software where there's a good chance that the
-software could break your system. Users who download and install
+software could break your system, or software that's just too unstable
+even for the unstable distribution (but there is a reason to
+package it nevertheless). Users who download and install
packages from experimental are expected to have been duly
warned. In short, all bets are off for the experimental
distribution.
-Developers should be very selective in the use of the
-experimental distribution. Even if a package is highly
-unstable, it could still go into unstable; just state a
-few warnings in the description. However, if there is a chance that
-the software could do grave damage to a system, it might be better to
-put it into experimental.
-
-For instance, an experimental encrypted file system should probably go
-into experimental. A new, beta, version of some software
-which uses completely different configuration might go into
-experimental at the maintainer's discretion. New software
-which isn't likely to damage your system can go into
-unstable. 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 access.
-
-However, using experimental as a personal staging area is not
-always the best idea. You can't replace or upgrade the files in there
-on your own (it is done with Debian archive maintenance software).
-Additionally, you'll have to remember to ask the archive
-maintainers to delete the package once you have uploaded it to
-unstable. Using your personal web space on
-klecker.debian.org is generally a better idea, so that you put
-less strain on the Debian archive maintainers.
+If there is a chance that the software could do grave damage to a system,
+it is likely to be better to put it into experimental.
+For instance, an experimental compressed file system should probably go
+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
+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
+access.
+
+Some experimental software can still go into unstable, with a few
+warnings in the description, but that isn't recommended because packages
+from unstable are expected to propagate to testing and
+thus to stable.
+
+New software which isn't likely to damage your system can go directly into
+unstable.
+
+An alternative to experimental is to use your personal web space
+on people.debian.org (klecker.debian.org).
Every released Debian distribution has a code name: Debian
1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0,
-`hamm'; Debian 2.1, `slink'; and Debian 2.2, `potato'. There is also
+`hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; and Debian 3.0, `woody'. There is also
a ``pseudo-distribution'', called `sid', which is the current
`unstable' distribution; since packages are moved from `unstable' to
`testing' as they approach stability, `sid' itself is never released.
@@ -857,9 +865,9 @@ determined by their code names and not their release status (e.g.,
`slink'). These names stay the same during the development period and
after the release; symbolic links, which can be changed easily,
indicate the currently released stable distribution. That's why the
-real distribution directories use the code names, while symbolic
-links for stable, testing, unstable, and
-frozen point to the appropriate release directories.
+real distribution directories use the code names, while
+symbolic links for stable, testing, and
+unstable point to the appropriate release directories.
Please include a Closes: bug#nnnnn entry on the
@@ -917,11 +925,38 @@ better feel of what is going on, and what is new, in the project.
+
+Before you upload your package, you should do basic testing on it. At
+a minimum, you should try the following activities (you'll need to
+have an older version of the same Debian package around):
+
+Normally, a package should not be uploaded if it causes lintian
+to emit errors (they will start with E).
+
+For more information on
When a package is uploaded to the Debian FTP archive, it must be
accompanied by a .changes file, which gives directions to the
@@ -936,35 +971,10 @@ All of these fields are mandatory for a Debian upload. See the list
of control fields in the
-Notably, the Distribution field, which originates from the
-
-You should avoid combining `stable' with others because of potential
-problems with library dependencies (for your package and for the package
-built by the build daemons for other architecture).
-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
-&email-debian-release;) 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
@@ -987,6 +997,27 @@ is some reason why this is not the case, the new version of the
original source should be uploaded, possibly by using the -sa
flag.
+
+
+The Distribution field, which originates from the first line of
+the
+There are three possible values for this field: `stable', `unstable',
+and `experimental'. Normally, packages are uploaded into
+unstable.
+
+You should avoid combining `stable' with others because of potential
+problems with library dependencies (for your package and for the package
+built by the build daemons for other architecture).
+See for more information on when and how to
+upload to stable.
+
+It never makes sense to combine the experimental distribution
+with anything else.
+
+
-
-Before you upload your package, you should do basic testing on it. At
-a minimum, you should try the following activities (you'll need to
-have an older version of the same Debian package around):
+
+Uploading 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.
+
+Extra care should be taken when uploading to stable. Basically, a
+package should only be uploaded to stable if one of the following happens:
-Normally, a package should not be uploaded if it causes lintian
-to emit errors (they will start with E).
-
-For more information on
+It is discouraged to change anything else in the package that isn't
+important, because even trivial fixes can cause bugs later on. Uploading
+new upstream versions to fix security problems is deprecated; applying the
+specific patch from the new upstream version to the old one ("backporting"
+the patch) is the right thing to do in most cases.
+
+Packages uploaded to stable need to be compiled on systems running
+stable, so that their dependencies are limited to the libraries
+(and other packages) available in stable; for example, a package
+uploaded to stable that depends on a library package that only
+exists in unstable will be rejected. Making changes to dependencies of other
+packages (by messing with Provides or shlibs files), possibly making
+those other packages uninstallable, is strongly discouraged.
+
+The Release Team (which can be reached at &email-debian-release;) will
+regularly evaluate the uploads in proposed-updates and decide if
+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.
+
+
To upload a package, you need a personal account on
@@ -1094,10 +1135,12 @@ file:
As discussed above, export controlled software should not be uploaded
-to ftp-master. Instead, use
The program
-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
The Debian archive maintainers are responsible for handling package
uploads. For the most part, uploads are automatically handled on a
-daily basis by archive maintenance tools `dak'
-(also referred to as
In any case, you will receive email notification indicating that the
-package has been uploaded. 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.
+package has added to the archive, which also indicates which bugs will
+be closed by the upload. Please examine this notification carefully,
+checking if any bugs you meant to close didn't get triggered.
+
+The installation notification also includes information on what
+section the package was inserted into. If there is a disparity, you
+will receive a separate email notifying you of that. Read on below.
@@ -1247,11 +1287,20 @@ have control over these fields. The values in the
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
+To alter the actual section that a package is put in, you need to
+first make sure that the
For more information about override files, see
This chapter contains information providing guidelines for when and
how NMUs should be done. A fundamental distinction is made between
-source and binary NMUs, which is explained in the next section.
+source and binary-only NMUs, which is explained in the next section.
-There are two new terms used throughout this section: ``binary NMU''
+There are two new terms used throughout this section: ``binary-only NMU''
and ``source NMU''. These terms are used with specific technical
-meaning throughout this document. Both binary and source NMUs are
+meaning throughout this document. Both binary-only and source NMUs are
similar, since they involve an upload of a package by a developer who
is not the official maintainer of that package. That is why it's a
non-maintainer upload.
@@ -1289,24 +1338,27 @@ is not the official maintainer of that package. That is why it's a
A source NMU is an upload of a package by a developer who is not the
official maintainer, for the purposes of fixing a bug in the package.
Source NMUs always involves changes to the source (even if it is just
-a change to
-A binary NMU is a recompilation and upload of a binary package for a
-new architecture. As such, it is usually part of a porting effort. A
-binary NMU is a non-maintainer uploaded binary version of a package
-(often for another architecture), with no source changes required.
-There are many cases where porters must fix problems in the source in
-order to get them to compile for their target architecture; that would
-be considered a source NMU rather than a binary NMU. As you can see,
-we don't distinguish in terminology between porter NMUs and non-porter
-NMUs.
-
-Both classes of NMUs, source and binary, can be lumped by the term
-``NMU''. However, this often leads to confusion, since most people
-think ``source NMU'' when they think ``NMU''. So it's best to be
-careful. In this chapter, if I use the unqualified term ``NMU'', I
-mean both source and binary NMUs.
+a change to
+A binary-only NMU is a recompilation and upload of a binary package
+for a given architecture. As such, it is usually part of a porting
+effort. A binary-only NMU is a non-maintainer uploaded binary version
+of a package, with no source changes required. There are many cases
+where porters must fix problems in the source in order to get them to
+compile for their target architecture; that would be considered a
+source NMU rather than a binary-only NMU. As you can see, we don't
+distinguish in terminology between porter NMUs and non-porter NMUs.
+
+Both classes of NMUs, source and binary-only, can be lumped by the
+term ``NMU''. However, this often leads to confusion, since most
+people think ``source NMU'' when they think ``NMU''. So it's best to
+be careful. In this chapter, if we use the unqualified term ``NMU'',
+we refer to any type of non-maintainer upload NMUs, whether source and
+binary, or binary-only.
Guidelines for when to do a source NMU depend on the target
-distribution, i.e., stable, unstable, or frozen. Porters have
+distribution, i.e., stable, unstable, or experimental. Porters have
slightly different rules than non-porters, due to their unique
circumstances (see ).
-Only critical changes or security bug fixes make it into stable. When
-a security bug is detected, a fixed package should be uploaded as soon
-as possible. In this case, the Debian Security Managers should get in
+When a security bug is detected, a fixed package should be uploaded
+as soon as possible. In this case, the Debian security officers get in
contact with the package maintainer to make sure a fixed package is
uploaded within a reasonable time (less than 48 hours). If the package
maintainer cannot provide a fixed package fast enough or if he/she
-cannot be reached in time, the Security Manager may upload a fixed
+cannot be reached in time, a security officer may upload a fixed
package (i.e., do a source NMU).
-During the release freeze (see ), NMUs which
-fix serious or higher severity bugs are encouraged and accepted.
-Even during this window, however, you should endeavor to reach the
-current maintainer of the package; they might be just about to upload
-a fix for the problem. As with any source NMU, the guidelines found
-in need to be followed.
+During the release cycle (see ), NMUs which fix
+serious or higher severity bugs are encouraged and accepted. Even
+during this window, however, you should endeavor to reach the current
+maintainer of the package; they might be just about to upload a fix
+for the problem. As with any source NMU, the guidelines found in need to be followed.
Bug fixes to unstable by non-maintainers are also acceptable, but only
as a last resort or with permission. Try the following steps first,
@@ -1424,7 +1475,7 @@ the release should start with the debian-revision value
this, you'll have to invoke
Remember, porters who are simply recompiling a package for a different
architecture do not need to renumber. Porters should use new version
@@ -1462,33 +1513,32 @@ simply requires a recompile (i.e., a new shared library is available
to be linked against, a bug was fixed in
If the source NMU (non-maintainer upload) fixes some existing bugs,
-the bugs in the Bug Tracking System which are fixed need to be
-notified but not actually closed by the
-non-maintainer. Technically, only the official package maintainer or
-the original bug submitter are allowed to close bugs. However, the
-person making the non-maintainer release must send a short message to
-the relevant bugs explaining that the bugs have been fixed by the NMU.
-Using
-
-
-
-
-
+
-
-
+