X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=87d1cfefdaad9c29b99daf7e7b0c395f51c27469;hb=0b664d545ec02d4e1c6bf860a8dd987ab3383709;hp=da075a0665fd913370b4ea5bb02ece71995bff83;hpb=986a7b2f49859e3006c18e383970eb8c35c4ebd7;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index da075a0..87d1cfe 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -7,25 +7,24 @@ Debian Developer's Reference - <author>Adam P. Harris, current maintainer <email/aph@debian.org/ + <author>Adam Di Carlo, current maintainer <email/aph@debian.org/ <author>Christian Schwarz <email/schwarz@debian.org/ <author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/ <version>ver. &version;, &date; <copyright> <copyrightsummary><!-- this tag not working right --> - <p> -Copyright ©1998 Adam P. Harris. Copyright ©1997,1998 -Christian Schwarz. +copyright ©1998 Adam Di Carlo, ©1997,1998 +Christian Schwarz</copyrightsummary> <p> This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the @@ -368,7 +367,7 @@ The main web page listing the available public FTP (and, usually, HTTP) servers can be found at <url id="http://www.debian.org/distrib/ftplist">. More information concerning Debian mirrors can be found at <url -id="http://www.debian.org/devel/mirror/">. This useful page includes +id="http://www.debian.org/mirror">. This useful page includes information and tools which can be helpful if you are interested in setting up your own mirror, either for internal or public access. <p> @@ -455,13 +454,15 @@ 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. <p> -Every package in the main section must fully comply with the <url +Every package in the main section must fully comply with the <!-- work +around quoting of fragment idendifiers bug <url id="http://www.debian.org/social_contract#guidelines" name="Debian -Free Software Guidelines"> (DFSG) and with all other policy -requirements as described in the <url -id="http://www.debian.org/doc/debian-policy/" name="Debian Policy -Manual">. The DFSG is our definition of ``free software.'' Check out -the Debian Policy Manual for details. +Free Software Guidelines"> --> <url +id="http://www.debian.org/social_contract" name="Debian Free Software +Guidelines"> (DFSG) and with all other policy requirements as +described in the <url id="http://www.debian.org/doc/debian-policy/" +name="Debian Policy Manual">. The DFSG is our definition of ``free +software.'' Check out the Debian Policy Manual for details. <p> The packages which do not apply to the DFSG are placed in the <em/non-free/ section. These packages are not considered as part of @@ -509,8 +510,9 @@ of this writing. <p> Debian GNU/Linux 1.3 is only available as <em>i386</em>. Debian 2.0 supports <em>i386</em> and <em>m68k</em> architectures. The next -version of Debian is likely to also support all these, in addition to -<em>alpha</em>, <em>ppc</em>, and <em>sparc</em> architectures. +version of Debian is likely to support <em>i386</em>, <em>m68k</em>, +<em>alpha</em>, and possibly <em>ppc</em> and <em>sparc</em> +architectures. <sect>Subsections @@ -518,11 +520,11 @@ version of Debian is likely to also support all these, in addition to The sections <em/main/, <em/contrib/, and <em/non-free/ are split into <em/subsections/ to simplify the installation process and the maintainance of the archive. Subsections are not formally defined, -excepting perhaps for the `base' subsection. Subsections exist simply +excepting perhaps the `base' subsection. Subsections exist simply to simplify the organization and browsing of available packages. Please check the current Debian distribution to see which sections are available. - +<p> <sect>Packages @@ -953,7 +955,7 @@ the <tt>.changes</tt> file must have a valid PGP signature from one of the keys of the developers key-ring. - <sect>Announcing package uploads + <sect id="upload-announce">Announcing package uploads <p> When a package is uploaded an announcement should be posted to one of the ``debian-changes'' lists. The announcement should give the (source) @@ -1011,20 +1013,36 @@ priorities for packages in the <em/override file/. Sometimes the <package/ftp.debian.org/. <p> For more information about <em/override files/, see -<manref name="dpkg-scanpackages" section="8">, +<manref name="dpkg-scanpackages" section="8"/>, <tt>/usr/doc/debian/bug-log-mailserver.txt</tt>, and <tt>/usr/doc/debian/bug-maint-info.txt</tt>. - <sect id="nmu">Interim releases - <p> + + <chapt id="nmu">Non-Maintainer Uploads (NMUs) and Porters + + <p> Under certain circumstances it is necessary for someone other than the -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 or bug may have come to light requiring -immediate attention. +usual package maintainer to make a release of a package. This is +called a non-maintainer upload, or NMU. + <p> +Debian porters, who compile packages for different architectures, do +binary NMUs as part of their normal porting activity. Sometimes, +Debian developers do NMUs in order to fix a serious security problem +or a crippling bug, especially when the package maintainer is unable +to release a fix in a timely fashion. + <p> +This chapter contains information providing guidelines for when and +how NMUs should be done. + + +<sect id="nmu-who">Who can do an NMU + <p> +Only an official Debian developers can do an NMU. +<!-- TODO: link to section talking about how non-maintainers can still + contribute --> + +<sect id="nmu-when">When to do an NMU <p> When a security bug is detected a fixed package should be uploaded as soon as possible. In this case, the Debian Security Managers should @@ -1034,14 +1052,93 @@ 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 package. <p> -When someone other than the usual maintainer releases a package they -should add a new component to the <var/debian-revision/ component of -the version number--that is, the portion after the (last) hyphen. -This extra component will start at `1'. This is to avoid -`stealing' one of the usual maintainer's version numbers, possibly -disrupting their work. If there is no <var/debian-revision/ component -in the version number then one should be created, starting at `1'. +During the release freeze (see <ref id="upload-frozen">), NMUs which +fix important 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. <p> +Bug fixes to unstable by non-maintainers are also acceptable, but only +as a last resort. Try the following steps first, and if they don't +work, it is ok to do an NMU: + <p> +<list> + <item> +Make sure that the package bug is in the Debian BTS. If not, submit a +bug. + <item> +Email the maintainer, and offer to help fix the package bug. Give it a +few days. + <item> +Go ahead and fix the bug, submitting a patch to the right bug in +the Bug Tracking System. + <item> +Wait a couple of weeks for a response. + <item> +Email the maintainer, asking if it is ok to do an NMU. + <item> +Wait a couple of weeks for a response. + <item> +Double check that your patch doesn't have any unexpected side effects. +Build the package and test it as discussed in <ref id="upload-checking">. + </list> + + <sect1>When to do an NMU if you are a porter + <p> +Porters who have to patch the source package in order to get the +package to compile need to follow these steps as well, although their +window of time that they should wait is smaller, since they deal with +a high quantity of packages. + <p> +Again, the situation will vary depending on the distribution they are +uploading to. Crucial fixes (i.e., changes need to get a source package +to compile) can be uploaded with <em/no/ waiting period for the `frozen' +distribution. + <p> +However, if you are a porter doing an NMU for `unstable', the above +guidelines for porting should be followed, with one variation. +If you need to alter the source of a package in order to get a +released port of Debian to compile, the bug you submit to the BTS +should be of severity `important' or greater. This ensures that a +single source package can be used to compile every supported Debian +architecture. + <p> +An acceptable waiting period -- the time between when the bug is +submitted to the BTS and when it is ok to do an NMU -- is ten days +for porters working on the unstable distribution. + <p> +Try to avoid patches which simply kluge around bugs in the current +version of the compile environment, kernel, or libc. Sometimes +that can't be helped. If you have to kluge around compilers bugs and +the like, make sure you <tt>#ifdef</tt> your work properly; also, +document your kluge so that people know to remove it once the external +problems have been fixed. + <p> +Porters may also have an unofficial location where they can put the results +of their work during the waiting period. This helps others running +the port have the benefit of the porter's work, even during the waiting +period. + + +<sect id="nmu-guidelines">How to do an NMU + <p> +When someone other than the usual maintainer releases a package they +should add a new minor version number to the <var/debian-revision/ part of +the version number (the portion after the last hyphen). +This extra minor number will start at `1'. For example, consider +the package `foo', which is at version 1.1-3. In the archive, the source +package control file would be <tt>foo_1.1-3.dsc</tt>. The upstream +version is `1.1' and the Debian revision is `3'. The next NMU would +add a new minor number `.1' to the Debian revision; the new source +control file would be <tt>foo_1.1-3.1.dsc</tt>. + <p> +The Debian revision minor number is needed to avoid +`stealing' one of the package maintainer's version numbers, which might +disrupt their work. It also has the benefit of making it visually +clear that a package in the archive was made by an NMU. + <p> +If there is no <var/debian-revision/ component +in the version number then one should be created, starting at `0.1'. If it is absolutely necessary for someone other than the usual maintainer to make a release based on a new upstream version then the person making the release should start with the <var/debian-revision/ @@ -1051,10 +1148,11 @@ you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the <tt/-sa/ switch to force the build system to pick up the new source package (normally it only looks for Debian revisions of '0' or '1'). <p> +<!-- HERE --> 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 (<tt/diff -u/) detailing their changes to the bug -tracking system properly flagged with the correct package so that the +tracking system. properly flagged with the correct package so that the usual maintainer is kept aware of the situation. <p> If the non-maintainer upload (as known as an ``NMU'') fixes some @@ -1086,30 +1184,7 @@ In addition, the normal maintainer should <em/always/ include an entry in the changelog file documenting the non-maintainer upload. - <sect>Maintainer changes - <p> -Periodically, a listing of packages in need of new maintainers will be -sent to <email/debian-devel@lists.debian.org</email> list. This list -is also available at in the Work-Needing and Prospective Packages -document (WNPP), <url -id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html"> -and at <url id="http://www.debian.org/doc/prospective-packages.html">. -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 <email/wnpp@debian.org/. - - <p> -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 -<tt/Maintainer:/ field. If you do not expect to upload a new version -for a while, send an email to <email/override-change@debian.org/ so -that bug reports will go to you. - - - - <chapt id="archive-manip">Moving, Removing, Renaming, and Orphaning Packages + <chapt id="archive-manip">Moving, Removing, Renaming, Adopting, and Orphaning Packages <p> Some archive manipulation operation are not automated in the Debian upload process. This chapter gives guidelines in what to do in these @@ -1160,6 +1235,7 @@ against <tt/ftp.debian.org/ asking to remove the package with the obsolete name. + <sect>Orphaning a package <p> If you can no longer maintain a package, then you should set the @@ -1171,6 +1247,30 @@ email <email/debian-devel@lists.debian.org/ asking for a new maintainer. + <sect>Adopting a package + <p> +Periodically, a listing of packages in need of new maintainers will be +sent to <email/debian-devel@lists.debian.org</email> list. This list +is also available at in the Work-Needing and Prospective Packages +document (WNPP), <url +id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html"> +and at <url id="http://www.debian.org/doc/prospective-packages.html">. +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 <email/wnpp@debian.org/. + + <p> +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 +<tt/Maintainer:/ field. If you do not expect to upload a new version +for a while, send an email to <email/override-change@debian.org/ so +that bug reports will go to you. + + + + <chapt id="bug-handling">Handling Bug Reports <sect>Monitoring bugs