From: hertzog Date: Thu, 9 May 2002 17:43:53 +0000 (+0000) Subject: - Various spelling fixes. X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=commitdiff_plain;h=7e6ba525682131d00e4d4c5a82c41dcc7b5824a5 - Various spelling fixes. - Sec "Developer Database": added a sentence about finger login@debian.org. - Update the total number of packages and the example directory tree of a Debian archive. - Updated the list of available architectures. - Commented out the "Subsections" section since it will RSN have nothing to with the Debian archive. It's just a generic information field of the package and nothing more. - Added more incentive to use experimental since it doesn't cause any pains to the ftpmasters. - Sec "When to do a source NMU": updated the NMU "protocol" and suggest the use of the delayed queue. - New Section "Acknowledging the NMUs" to explain the need to integrate the changes introduced by NMUs. Insists on the fact that one shouldn't be upset by a NMU. - Stubbed in new Section "Collaborative maintenance". - Stubbed in new Section "The Package Tracking System". git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1675 313b444b-1b9f-4f58-a734-7bb04f332e8d --- diff --git a/common.ent b/common.ent index a33b34a..17cf18e 100644 --- a/common.ent +++ b/common.ent @@ -9,7 +9,7 @@ - + @@ -150,39 +150,28 @@ dists/stable/main/ -dists/stable/main/binary-all/ -dists/stable/main/binary-all/admin/ -dists/stable/main/binary-all/base/ -dists/stable/main/binary-all/comm/ -dists/stable/main/binary-all/devel/ - ... dists/stable/main/binary-i386/ -dists/stable/main/binary-i386/admin/ -dists/stable/main/binary-i386/base/ - ... dists/stable/main/binary-m68k/ -dists/stable/main/binary-m68k/admin/ -dists/stable/main/binary-m68k/base/ +dists/stable/main/binary-alpha/ ... dists/stable/main/source/ -dists/stable/main/source/admin/ -dists/stable/main/source/base/ ... dists/stable/main/disks-i386/ dists/stable/main/disks-m68k/ +dists/stable/main/disks-alpha/ ... dists/stable/contrib/ -dists/stable/contrib/binary-all/ dists/stable/contrib/binary-i386/ dists/stable/contrib/binary-m68k/ +dists/stable/contrib/binary-alpha/ ... dists/stable/contrib/source/ dists/stable/non-free/ -dists/stable/non-free/binary-all/ dists/stable/non-free/binary-i386/ dists/stable/non-free/binary-m68k/ +dists/stable/non-free/binary-alpha/ ... dists/stable/non-free/source/ @@ -203,16 +192,19 @@ dists/unstable/non-free/ ... pool/ -pool/a/ -pool/a/apt/ +pool/main/a/ +pool/main/a/apt/ + ... +pool/main/b/ +pool/main/b/bash/ ... -pool/b/ -pool/b/bash/ +pool/main/liba/ +pool/main/liba/libalias-perl/ ... -pool/liba/ -pool/liba/libalias-perl/ +pool/main/m/ +pool/main/m/mailx/ ... -pool/m/ -pool/m/mailx/ +pool/non-free/n/ +pool/non-free/n/netscape/ ... "> diff --git a/debian/changelog b/debian/changelog index e0f043f..ed436e4 100644 --- a/debian/changelog +++ b/debian/changelog @@ -65,6 +65,24 @@ developers-reference (3.0) unstable; urgency=low - Sec "Handling bugs": added http://bugs.debian.org/login@debian.org - Sec "The Incoming system" in "Resources", describe how it works and also speak of the DELAYED directory. closes: #135562, #136774 + - Various spelling fixes. + - Sec "Developer Database": added a sentence about finger + login@debian.org. + - Update the total number of packages and the example directory tree + of a Debian archive. + - Updated the list of available architectures. + - Commented out the "Subsections" section since it will RSN have nothing + to with the Debian archive. It's just a generic information field + of the package and nothing more. + - Added more incentive to use experimental since it doesn't cause + any pain to the ftpmasters. + - Sec "When to do a source NMU": updated the NMU "protocol" and suggest + the use of the delayed queue. + - New Section "Acknowledging the NMUs" to explain the need to integrate + the changes introduced by NMUs. Insists on the fact that one shouldn't + be upset by a NMU. + - Stubbed in new Section "Collaborative maintenance". + - Stubbed in new Section "The Package Tracking System". * Antoine Hulin: - update French translation diff --git a/developers-reference.sgml b/developers-reference.sgml index 6b29681..ed83ffd 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + Packages

@@ -756,7 +760,7 @@ Active development is done in the unstable distribution (that's why this distribution is sometimes called the development distribution). Every Debian developer can update his or her packages in this distribution at any time. Thus, the contents of this -distribution change from day-to-day. Since no special effort is done +distribution changes from day-to-day. Since no special effort is done to make sure everything in this distribution is working properly, it is sometimes literally unstable.

@@ -792,8 +796,9 @@ 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., ‘3.0’ becomes ‘3.0r1’, -‘2.2r4’ becomes ‘2.0r5’, and so forth). +stable distribution is incremented (e.g., ‘3.0’ becomes +‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and +so forth).

Note that development under unstable continues during the freeze period, since the unstable distribution remains in @@ -801,7 +806,7 @@ place in parallel with testing. Experimental

-The experimental distribution is a specialty distribution. +The experimental distribution is a special 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 @@ -829,7 +834,10 @@ 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. +thus to stable. You should not be afraid to use +experimental since it does not cause any pain to the ftpmasters, +the experimental packages are automatically removed once you upload +the package in unstable with a higher version number.

New software which isn't likely to damage your system can go directly into unstable. @@ -896,14 +904,14 @@ the package is refused and is moved in the reject directory.

Once the package is accepted the system sends a confirmation mail to the maintainer, closes all the bugs marked as fixed by the upload -and the autobuilders may start recompiling it. The package is now publicly +and the autobuilders may start recompiling it. The package is now publically accessible at (there is no such URL for packages in the non-US archive) until it is really installed in the Debian archive. This happens only once a day, the package is then removed from incoming and installed in the pool along with all the other packages. Once all the other updates (generating new -Packages and Sources files for example) have been made, -a special script is called to ask all the primary mirrors to update +Packages and Sources index files for example) have been +made, a special script is called to ask all the primary mirrors to update themselves.

All debian developers have write access to the unchecked @@ -911,8 +919,10 @@ directory in order to upload their packages, they also have that access to the reject directory in order to remove their bad uploads or to move some files back in the unchecked directory. But all the other directories are only writable by the ftpmasters, that is -why you can not remove your upload once it has been accepted. -

+why you can not remove an upload once it has been accepted. + + Delayed incoming +

The unchecked directory has a special DELAYED subdirectory. It is itself subdivised in nine directories called 1-day to 9-day. Packages which are uploaded in @@ -1040,6 +1050,12 @@ the version in testing and that there has been a binary-only NMU of the package for the alpha architecture. Each time the package has been recompiled on most of the architectures. + The Package Tracking System +

+&FIXME; Include some documentation of the PTS. Explain how to use the +keyword mechanism and what they are for. Explain how to setup an +automatic forward of cvs commits. + Managing Packages

@@ -1112,7 +1128,7 @@ completed. This file will be installed in /usr/share/doc/package/changelog.gz for native packages.

-The debian/changelog file conform to a certain structure, +The debian/changelog file conforms to a certain structure, with a number of different fields. One field of note, the distribution, is described in . More information about the structure of this file can be found in @@ -1337,7 +1353,7 @@ package, post a message to &email-debian-devel; and ask.

You may also find the Debian packages dupload or dput useful -when uploading packages. These handy program are distributed with +when uploading packages. These handy programs are distributed with defaults for uploading via ftp to ftp-master, chiark, and erlangen. They can also be configured to use ssh or rsync. See -In any case, you will receive email notification indicating that the -package has added to the archive, which also indicates which bugs will +In any case, you will receive an email notification indicating that the +package has been 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.

@@ -1610,36 +1626,35 @@ 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, -and if they don't work, it is probably OK to do an NMU: +as a last resort or with permission. The following protocol should +be respected to do an NMU :

-Make sure that the package bug is in the Debian Bug Tracking System -(BTS). If not, submit a bug. - -Email the maintainer, and offer to help fix the package bug. Give it a -few days. - -Go ahead and fix the bug, submitting a patch to the right bug in the -BTS. Build the package and test it as discussed in . Use it locally. - -Wait a couple of weeks for a response. +Make sure that the package's bug is in the Debian Bug Tracking System +(BTS). If not, submit a bug. -Email the maintainer, asking if it is OK to do an NMU. +Wait a few days the response from the maintainer. If you don't get +any response, you may want to help him by sending the patch that fixes +the bug. Don't forget to tag the bug with the "patch" keyword. +Wait a few more days. If you still haven't got an answer from the +maintainer, send him a mail announcing your intent to NMU the package. +Prepare an NMU as described in , test it +carefully on your machine (cf. ). Double check that your patch doesn't have any unexpected side effects. -Make sure your patch is as small and as non-disruptive as it can be. +Make sure your patch is as small and as non-disruptive as it can be. -Wait another week for a response. +Upload your package to incoming in DELAYED/7-day (cf. +), send the final patch to the maintainer via +the BTS, and explain him that he has 7 days to react if he wants to cancel +the NMU. -Go ahead and do the source NMU, as described in . +Follow what happens, you're responsible for any bug that you introduced +with your NMU. You should probably use (PTS) +to stay informed of the state of the package after your NMU. - - How to do a source NMU

The following applies to porters insofar as they are playing the dual @@ -1762,7 +1777,23 @@ the debian/control file. Your name as given in the NMU entry of the debian/changelog file will be used for signing the changes file. - + Acknowledging an NMU +

+If one of your packages has been NMUed, you have to incorporate the +changes in your copy of the sources. This is easy, you just have +to apply the patch that has been sent to you. Once this is done, you +have to close the bugs that have been tagged fixed by the NMU. You +can either close them manually by sending the required mails to the +BTS or by adding the required closes: #nnnn in the changelog +entry of your next upload. +

+In any case, you should not be upset by the NMU. An NMU is not a +personal attack against the maintainer. It is just the proof that +someone cares enough about the package and was willing to help +you in your work. You should be thankful to him and you may want to +ask him if he would be interested to help you on a more frequent +basis as co-maintainer or backup maintainer +(see ). Porting and Being Ported @@ -1809,7 +1840,7 @@ are set properly. The best way to validate this is to use the debootstrap package to create an unstable chroot environment. Within that chrooted environment, install the build-essential package and any package -dependencies mention in Build-Depends and/or +dependencies mentioned in Build-Depends and/or Build-Depends-Indep. Finally, try building your package within that chrooted environment.

@@ -1879,7 +1910,7 @@ package, using the `binary-arch' target in debian/rules. Sometimes the initial porter upload is problematic because the environment in which the package was built was not good enough (outdated or obsolete library, bad compiler, ...). Then you may just need to recompile it in -an updated environment. However, you do have to bump the version number in +an updated environment. However, you have to bump the version number in this case, so that the old bad package can be replaced in the Debian archive (katie refuses to install new packages if they don't have a version number greater than the currently available one). Despite the @@ -2008,13 +2039,18 @@ headers for cross-compiling in a way similar to enhanced to support cross-compiling. + Collaborative maintenance +

+&FIXME; Speak about Uploaders: field, about the intelligent use +of the PTS. Insist that it's a "must have" for base and standard +packages. Moving, Removing, Renaming, Adopting, and Orphaning Packages

-Some archive manipulation operation are not automated in the Debian +Some archive manipulation operations are not automated in the Debian upload process. These procedures should be manually followed by maintainers. This chapter gives guidelines in what to do in these cases. @@ -2104,7 +2140,7 @@ at the same time.

If you can no longer maintain a package, you need to inform the others about that, and see that the package is marked as orphaned. -you should set the package maintainer to Debian QA Group +You should set the package maintainer to Debian QA Group &orphan-address; and submit a bug report against the pseudo package wnpp. The bug report should be titled O: package -- short description @@ -2117,8 +2153,9 @@ won't indicate the bug number). If the package is especially crucial to Debian, you should instead submit a bug against wnpp and title it RFA: package -- short description and set its severity to -important. Definitely copy the message to debian-devel in this -case, as described above. +important. RFA stands for Request For Adoption. +Definitely copy the message to debian-devel in this case, as described +above.

Read instructions on the for more information. @@ -2137,16 +2174,17 @@ current maintainer and ask them if you may take over the package. However, without their assent, you may not take over the package. Even if they ignore you, that is still not grounds to take over a package. If you really feel that a maintainer has gone AWOL (absent -without leave), post a query to &email-debian-private;. +without leave), post a query to &email-debian-private;. You may also +inform the QA group (cf. ).

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 automatically once you upload a new version with an updated Maintainer: field, although it can take a few hours after the upload is done. If you do not expect to upload a new version for a while, -send an email to &email-override; so that bug reports will go to you -right away. - +you can use to get the bug reports. However, +make sure that the old maintainer is not embarassed by the fact that +he will continue to receive the bugs during that time. Handling package bugs @@ -2183,8 +2221,13 @@ maintainer address. Responding to bugs

-Make sure that any discussions you have about bugs are sent both to +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., +123@bugs.debian.org). If you're writing a new +mail and you don't remember the submitter email address, you can +use the 123-submitter@bugs.debian.org email to +contact the submitter and to record your mail within the +bug log (that means you don't need to send a copy of the mail to 123@bugs.debian.org).

You should never close bugs via the bug server close @@ -2197,7 +2240,7 @@ closed. As a package maintainer, you will often find bugs in other packages or have bugs reported against your packages which are actually bugs in other packages. The document the technical operation of the BTS, such as +instructions"> document the technical operations of the BTS, such as how to file, reassign, merge, and tag bugs. This section contains some guidelines for managing your own bugs, based on the collective Debian developer experience. @@ -2238,7 +2281,7 @@ used: /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig -The author prefers the closes: #XXX) syntax, as +The author prefers the closes: #XXX syntax, as one of the most concise and easiest to integrate with the text of the changelog.

@@ -2394,9 +2437,9 @@ can use a simple email alias : <package>@&packages-host;. <package> can be the name of a source or a binary package.

You may also be interested by contacting the persons who are -subscribed to a given source package via the Package Tracking -System. You can do so by using the <package>@&pts-host; -address. +subscribed to a given source package via . +You can do so by using the <package>@&pts-host; +email address. @@ -2431,7 +2474,7 @@ doesn't matter that you left the prospective developer's name both in the changelog and the control file, the upload can still be traced to you.

If you are an application manager for a prospective developer, you can also -be their sponsor. That way you can also verify the how the applicant is +be their sponsor. That way you can also verify how the applicant is handling the 'Tasks and Skills' part of their application.