From 7e99c4cd5a13c624fa4919b9a89f74cbd64399a0 Mon Sep 17 00:00:00 2001 From: aph Date: Sun, 20 Sep 1998 23:42:23 +0000 Subject: [PATCH] first cut for 2.4.1.4, which is a lot of changes. Still need to fix terminology for "section" and "distribution" and the like git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@652 313b444b-1b9f-4f58-a734-7bb04f332e8d --- developers-reference.sgml | 346 +++++++++++++++++++++++++++----------- 1 file changed, 248 insertions(+), 98 deletions(-) diff --git a/developers-reference.sgml b/developers-reference.sgml index 4921045..9ee6d90 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -8,7 +8,7 @@ Topics to be included someday: - bugs in upstream versions should be reported upstream! - - how to be a good non-maintainer + - pointer for useful tools for maintainers --> @@ -51,31 +51,32 @@ in the -Firstly, subscribe to You should subscribe and lurk for a bit before doing any coding, and you should post about your intentions to work on something to avoid duplicated effort.

-If you do not have a PGP key yet generate one. You should probably -read the PGP manual, as it has much important information which is +If you do not have a PGP key yet, generate one. You should probably +read the PGP manual, since it has much important information which is critical to its security. Many more security failures are due to human error than to software failure or high-powered spy techniques.

Due to export restrictions by the United States government some Debian packages, including PGP, have been moved to an ftp site outside of the United States. You can find the current locations of those packages on -/pub/debian/README.non-US -file. +/pub/debian/README.non-US file.

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. This does not apply in France, where I believe only encryption and not authentication is forbidden. -

+ Registering as a Debian developer

@@ -88,20 +89,24 @@ After that, you should send a message to developer so that you will be able to upload your packages.

The message should say what you've done and who you are, and should -ask for an account on master and to be subscribed to debian-private -(the developers-only mailing list). It should contain your PGP or RSA -public key (extracted using `pgp -kxa', in the case of PGP) for the -database of keys which is distributed on the FTP server -(doc/debian-keyring.tar.gz). Please be sure to sign your -request message with your chosen PGP or RSA key. In addition, you have -to mention that you've read the ``Debian Social Contract'' (see above) -and you are expected to know where to find the ``Debian Policy +ask for an account on pgp -kxa in the case of PGP; note that , or +the debian-keyring> package). Please be sure to sign +your request message with your chosen PGP or RSA key. In addition, you +have to mention that you've read the ``Debian Social Contract'' (see +above) and you are expected to know where to find the ``Debian Policy Manual'' and the ``Debian Packaging Manual.''

-Please be sure to include your preferred login name on master (seven -characters or less), as well as the E-mail address at which you'd -prefer to be subscribed to debian-private (typically this will be -either your primary mail address or your new debian.org address). +Please be sure to include your preferred login name on debian.org address).

You should also include some mechanism by which we can verify your real-life identity. For example, any of the following mechanisms @@ -143,9 +148,9 @@ overworked, and mistakes do occasionally happen. Debian Mentors

-There is a mailing list called Every new developer is invited to subscribe to that list (see for details). @@ -171,8 +176,12 @@ original poster. Anyone who posts to a mailing list should read it to see the responses.

In addition, all messages should usually only be sent to one of the -following mailing lists: 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 @@ -181,6 +190,10 @@ posting messages. The master server

+The master server, . All Debian +developers have accounts on this machine. The FTP servers

@@ -194,7 +207,7 @@ posting messages. Overview

The Debian GNU/Linux distribution consists of a lot of Debian packages -( Here is an example directory tree of a complete Debian distribution: @@ -232,6 +245,21 @@ non-free/source/ As you can see, the top-level directory of the distribution contains three directories, namely main, contrib, and non-free. These directories are called sections. +

In each section, there is a directory with the source packages (source), a directory for each supported architecture (binary-i386, @@ -295,7 +323,8 @@ The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs, M68000 machines (like Atari and Amiga), MIPS, and PowerPC.

Debian GNU/Linux 1.3 is only available for Intel platforms. Debian -2.0 supports Intel and m68k architectures. +2.0 supports Intel and m68k architectures. The next version of Debian +is likely to also support Sparc, PPC, and Alpha, if not more. Sub sections @@ -334,15 +363,20 @@ checksums (md5sums) and some additional info about the package If you have a look at the Debian FTP server or one of its mirrors, you'll discover that there is one additional directory level on top of the directory tree, as described in the previous chapter. These -directories are the -There is always a distribution called dists/stable) and one called dists/unstable. This reflects the development process of the +Debian project.

The ``development'' is done in the Note, that development is continued during the ``freeze'' period, since a new ``unstable'' distribution will be created at that time. @@ -374,9 +409,13 @@ month from time to time.

Every released Debian distribution has a -Since the Debian has an open development (i.e., everyone can +Since the Debian has an open development model (i.e., everyone can participate and follow the development) even the ``development versions'' (unstable) are distributed via the Internet on the Debian FTP server. This FTP server is mirrored by lots of other @@ -399,19 +438,27 @@ there may be symbolic links, which can be changed.

That's why the distribution directories use the Package uploads + Package uploads Announcing new packages

If you want to create a new package for the Debian distribution, you -have to send a short email to -This has the following advantages: - +should first check the page. Checking +the WNPP ensures that effort is not duplicated or wasted; namely, that +no-one is already working on packaging that software. Assuming no-one +else is currently working on your prospective package, you have to +send a short email to +There are a number of reasons why we ask maintainers to follow these +steps. It helps the (potentially new) maintainer to tap into the experience @@ -420,12 +467,15 @@ on it already. It lets other people thinking about working on the package know that -there already is a volunteer, and efforts may be shared. +there already is a volunteer, and efforts may be shared. The "intent +to package" message to It lets the rest of the maintainers know more about the package than the one line description and the changelog entry "Initial version" -that generally gets posted to debian-devel-changes by default. +that generally gets posted to It is helpful to the people who live off unstable (and form our first @@ -444,9 +494,10 @@ testers. If we appreciate alpha testers, than any name changes have to be backwards compatible with the people who already installed the old -package (conflict and replace old package name at a minimum) +package (conflict and replace old package name at a minimum). - + + Uploading a package Generating the changes file @@ -456,7 +507,7 @@ accompanied by a This file is a control file with the following fields: - + Checking the package prior to upload +

+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). + + install the package and make sure the software + works + + upgrade the package from an older version to your + new version + + downgrade the package to the previous version + (this tests the remove the package + + run lintian -v + package-NN.changes. This will check the + source package as well as the binary package. If you + don't understand the output that + + Transferring the files to master

-To upload a package, you need a personal account on the master -server. Just log in via ftp and transfer the files to -/home/Debian/ftp/private/project/Incoming. (You cannot -upload to Incoming on master using anonymous FTP--you must use your -user-name and password.) +To upload a package, you need a personal account on +master.debian.org. All maintainers should already +have this account. You can use either /home/Debian/ftp/private/project/Incoming. (You +cannot upload to Incoming on master using anonymous FTP--you must use +your user-name and password.)

-You may also find the Debian package 'dupload' useful in -uploading new packages to master. See the 'dupload' -documentation for more information. +You may also find the Debian package and for more information. Uploads via Chiark

-If you have a slow network connection to the master system, there are -two alternatives: You can upload files to Incoming via a cron-driven -upload queue in Europe on ftp.chiark.greenend.org.uk. For details -connect to chiark using anonymous FTP and read -/pub/debian/private/project/README.how-to-upload. +If you have a slow network connection to ftp.chiark.greenend.org.uk using anonymous FTP and +read +/pub/debian/private/project/README.how-to-upload.

-The program Uploads via Erlangen

-Another cron-driven upload queue is available in Germany: Just upload -the files via anonymous FTP to -ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue. +Another cron-driven 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 -master's incoming, i.e. a 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 @@ -542,9 +628,9 @@ 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.

-The program +The program Uploading to the non-us server

@@ -572,7 +658,29 @@ If a package is released with +If you use dupload, it is clever enough to determine for itself where +the announcement should go, and will automatically mail the +announcement. + + Notification that a new package has been installed +

+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 +In any case, you will receive notification indicating that the package +has been uploaded via email. Please examine this notification +carefully. Sometimes the "override" file which the archive +maintainers use to indicate where packages go, is incorrect or +out-of-sync with your control file. In these cases, you should either +correct your control file or file a bug against Interim releases

@@ -581,8 +689,8 @@ usual package maintainer to make a release of a package. For example, a porter for another architecture may have to make some small changes to the source package and does not wish to wait with uploading their release until the main maintainer has incorporated the patch, or a -serious security problem may have come to light requiring immediate -attention. +serious security problem or bug may have come to light requiring +immediate attention.

When a security bug is detected a fixed package should be uploaded as soon as possible. In this case, the Debian Security Managers should @@ -610,12 +718,20 @@ Maintainers other than the usual package maintainer should make as few changes to the package as possible, and they should always send a unified context diff ( +If the non-maintainer upload (as known as an "NMU") fixes some +existing bugs, the bug reports should not be closed. Technically, +only the official package maintainer or the original bug submitter are +allowed to close bugs. However, the person making the non-maintainer +release should send a short message to the bug tracking system to all +the fixed bugs explaining that they have been fixed. Using + The normal maintainer should do at least one of @@ -637,13 +753,16 @@ in the changelog file documenting the non-maintainer upload. Maintainer changes

Periodically, a listing of packages in need of new maintainers will be -sent to the debian-devel list. This list is also available at -ftp.debian.org in -/debian/doc/package-developer/prospective-packages.html If -you wish to take over maintenance of any of those packages, or if you -can no longer maintain the packages you have, or you simply want to -know if any one is working on a new package, send a message to - list. This list +is also available at in the Work-Needing and Prospective Packages +document (WNPP), +and at . If you wish +to take over maintenance of any of the packages listed in the WNPP, or +if you can no longer maintain a packages you have, or you simply want +to know if any one is working on a new package, send a message to + If you take over an old package, you probably want to be listed as the package's official maintainer in the bug system. This will happen @@ -655,14 +774,45 @@ that bug reports will go to you. Handling bug reports + Bugs in your packages +

+If you want to be a good maintainer, you should periodically check the + for your packages. The BTS contains all the open bugs against +your packages. +

+If you fix a bug in your packages, it is your responsibility as the +package maintainer to close the bug when it has been fixed. However, +you should not close the bug until the package which fixes the bug has +been accepted into the Debian archive. Therefore, once you get +notification that your updated package has been installed into the +archive, you can and should close the bug in the BTS. +

+Maintainers interact with the BTS via email addresses at +/usr/doc/debian/bug-* from the Lintian reports +

+You should periodically get the new . That page, which is +updated automatically, contains lintian reports against the latest +version of the package (usually from 'unstable') using the latest +Reporting lots of bugs at once

If you report more then 10 bugs on the same topic at once, it is -recommended that you send a message to debian-devel describing your -intention before submitting the report. This will allow other -developers to verify that the bug is a real problem. In addition, it -will prevent the situation where several maintainers start filing the -same bug report simultaneously. +recommended that you send a message to + Note, that when sending lots of bugs on the same subject, you should send the bug report to