X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=72e4c3a1aa8083097e3289d4569e275ffcb79563;hb=25d4d612ad700f4daa88037123e2a783d5913c3f;hp=f64955c1f615143efec57b1d292507eec09b0037;hpb=4d3846471cf785e8bc5623e71adcb46bba604efe;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index f64955c..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!
@@ -364,6 +359,22 @@ id="orphaning">). 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.
+
If you choose to leave the Debian project, you should make sure you do
@@ -407,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
@@ -558,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.).
@@ -597,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
@@ -722,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
@@ -740,48 +752,46 @@ 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 &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).
+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.
@@ -855,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
@@ -915,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
@@ -934,29 +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).
-See for more information on when and how to
-upload to stable.
+
The first time a version is uploaded which corresponds to a particular
upstream version, the original source tar file should be uploaded and
@@ -979,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.
+
+
+
@@ -1058,36 +1099,7 @@ inclusion.
-
-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
@@ -1236,7 +1248,7 @@ send those announcements (check its documentation and look for
If a package is released with the Distribution: set to
`stable', the announcement is sent to &email-debian-changes;. If a
package is released with Distribution: set to `unstable',
-`experimental', or `frozen' (when present), the announcement will be
+or `experimental', the announcement will be
posted to &email-debian-devel-changes; instead.
The
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 ).
@@ -1375,12 +1387,12 @@ maintainer cannot provide a fixed package fast enough or if he/she
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,
@@ -1506,28 +1518,27 @@ porters who have to do recompiles — chalk it up as a weakness in how
we maintain our archive.)
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
-The normal maintainer will either apply the patch or employ an
-alternate method of fixing the problem. Sometimes bugs are fixed
-independently upstream, which is another good reason to back out an
-NMU's patch. If the maintainer decides not to apply the NMU's patch
-but to release a new version, the maintainer needs to ensure that the
-new upstream version really fixes each problem that was fixed in the
-non-maintainer release.
+these bugs should be tagged fixed in the Bug Tracking
+System rather than closed. By convention, only the official package
+maintainer or the original bug submitter are allowed to close bugs.
+Fortunately, Debian's archive system recognizes NMUs and thus marks
+the bugs fixed in the NMU appropriately if the person doing the NMU
+has listed all bugs in the changelog with the Closes:
+bug#nnnnn syntax (see for
+more information describing how to close bugs via the changelog).
+Tagging the bugs fixed ensures that everyone knows that the
+bug was fixed in an NMU; however the bug is left open until the
+changes in the NMU are incorporated officially into the package by
+the official package maintainer.
+
+Also, after doing an NMU, you have to open a new bug and include a
+patch showing all the changes you have made. The normal maintainer
+will either apply the patch or employ an alternate method of fixing
+the problem. Sometimes bugs are fixed independently upstream, which
+is another good reason to back out an NMU's patch. If the maintainer
+decides not to apply the NMU's patch but to release a new version,
+the maintainer needs to ensure that the new upstream version really
+fixes each problem that was fixed in the non-maintainer release.
In addition, the normal maintainer should always retain the
entry in the changelog file documenting the non-maintainer upload.
@@ -1690,11 +1701,16 @@ Porters doing a source NMU generally follow the guidelines found in
the wait cycle for a porter's source NMU is smaller than for a
non-porter, since porters have to cope with a large quantity of
packages.
-
Again, the situation varies depending on the distribution they are
-uploading to. Crucial fixes (i.e., changes need to get a source
+uploading to.
+
+
However, if you are a porter doing an NMU for `unstable', the above
guidelines for porting should be followed, with two variations.
@@ -2035,7 +2051,7 @@ list.
This chapter describes procedures that existing Debian developers should
follow when it comes to dealing with wannabe developers.
-
Sponsoring a package means uploading a package for a maintainer who is not
able to do it on their own, a new maintainer applicant. Sponsoring a package
-
-
-
-
-
+
-
-
-
+