X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=ba8b075a043559a7f07ba79b040c261196e15892;hb=aaed407b0c363c49306aff53515e6f88e807bd4a;hp=dc01e2a94d108b5fbaace1c6d37e0f1b1010df9b;hpb=9ff6174a5315853828d8f75429d040441a5f2d17;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index dc01e2a..ba8b075 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -2,11 +2,11 @@ %versiondata; - + %commondata; - + @@ -77,7 +77,7 @@ resources which can help maintainers with the quality of their packages ().

It should be clear that this reference does not discuss the technical -details of the Debian package nor how to generate Debian packages. +details of Debian packages nor how to generate them. Nor does this reference detail the standards to which Debian software must comply. All of such information can be found in the . @@ -125,7 +125,8 @@ with you on your package and upload it to the Debian archive once they are 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 +and 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 @@ -255,7 +256,8 @@ but are waiting for your new maintainer application to go through, you might be able find a sponsor to upload your package for you. Sponsors are people who are official Debian maintainers, and who are willing to criticize and upload your packages for you. Those who are seeking a -sponsor can request one at . +sponsor can request one at . Please read the +inofficial debian-mentors FAQ at first.

If you wish to be a mentor and/or sponsor, more information is available in . @@ -332,7 +334,7 @@ security update, etc.) occurs while you're on vacation. Sometimes it's nothing as critical as that, but it's still appropriate to let the others know that you're unavailable.

-In order to inform the other developers, there's two things that you should do. +In order to inform the other developers, there are two things that you should do. First send a mail to &email-debian-private; with "[VAC] " prepended to the subject of your messageThis is so that the message can be easily filtered by people who don't want to read vacation notices. @@ -356,7 +358,7 @@ they can be fixed in a future upstream release. While it's not your job to fix non-Debian specific bugs, you may freely do so if you're able. When you make such fixes, be sure to pass them on to the upstream maintainers as well. Debian users and developers will -sometimes submit patches to fix upstream bugs -- you should evaluate +sometimes submit patches to fix upstream bugs — you should evaluate and forward these patches upstream.

If you need to modify the upstream sources in order to build a policy @@ -370,7 +372,7 @@ need, always try not to fork from the upstream sources.

Generally you should deal with bug reports on your packages as described in . However, there's a special category of bugs that -you need to take care of -- the so-called release-critical bugs (RC bugs). +you need to take care of — the so-called release-critical bugs (RC bugs). All bug reports that have severity critical, grave or serious are considered to have an impact on whether the package can be released in the next stable release of Debian. @@ -589,17 +591,22 @@ administration (such as packages to be removed from the archive, suggestions for the web site, etc.), generally you'll report a bug against a ``pseudo-package''. See for information on how to submit bugs. +

+Some of the core servers are restricted, but the information from there +is mirror to another server. The bugs server

&bugs-host; is the canonical location for the Bug Tracking -System (BTS). If you plan on doing some statistical analysis or +System (BTS). +

+It is restricted; a mirror is available on merkel. +

+If you plan on doing some statistical analysis or processing of Debian bugs, this would be the place to do it. Please describe your plans on &email-debian-devel; before implementing anything, however, to reduce unnecessary duplication of effort or wasted processing time. -

-All Debian developers have accounts on &bugs-host;. The ftp-master server

@@ -607,6 +614,8 @@ The ftp-master.debian.org server holds the canonical copy of the Debian archive (excluding the non-US packages). Generally, package uploads go to this server; see .

+It is restricted; a mirror is available on merkel. +

Problems with the Debian FTP archive generally need to be reported as bugs against the ftp.debian.org pseudo-package or an email to &email-ftpmaster;, but also see the procedures in @@ -677,6 +686,20 @@ To request a CVS area, send a request via email to &email-debian-admin;. Include the name of the requested CVS area, the Debian account that should own the CVS root area, and why you need it. + chroots to different distributions +

+On some machines, there are chroots to different distributions available. +You can use them like + + +vore% dchroot unstable +Executing shell in chroot: /org/vore.debian.org/chroots/user/unstable + + +In all chroots, the normal user home directories are available. +You can find out which chroots are available via +&url-devel-machines;. + The Developers Database

@@ -886,7 +909,8 @@ 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.

-"testing" is generated automatically by taking +The "testing" distribution is generated +automatically by taking packages from unstable if they satisfy certain criteria. Those criteria should ensure a good quality for packages within testing. The update to testing is launched each day after the @@ -1029,7 +1053,10 @@ New software which isn't likely to damage your system can go directly into

An alternative to experimental is to use your personal web space on people.debian.org. - +

+Please consider to use the option -v to dpkg-buildpackage +if uploading a package to unstable to get the bugs finally closed that were +first fixed in experimental. Release code names

@@ -1140,7 +1167,11 @@ 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 an upload once it has been accepted. - Delayed incoming + Delayed incoming +

+Note: This description here is currently disabled, because +ftp-master is restricted. Please see for +the currently working way.

The unchecked directory has a special DELAYED subdirectory. It is itself subdivided in nine directories @@ -1676,11 +1707,8 @@ Actually, there are two other possible distributions: `stable-security' and `testing-security', but read for more information on those.

-It is technically possible to upload a package into several distributions -at the same time but it usually doesn't make sense to use that feature -because the dependencies of the package may vary with the distribution. -In particular, it never makes sense to combine the experimental -distribution with anything else (see ). +It is not possible to upload a package into several distributions +at the same time. Special case: uploads to the stable distribution @@ -1721,6 +1749,10 @@ 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. +

+It's best practice to speak with the stable release manager before +uploading to stable/stable-proposed-updates, so that the +uploaded package fits the needs of the next point release. Special case: uploads to testing-proposed-updates @@ -1746,25 +1778,17 @@ the authorization of the release manager before. Uploading to ftp-master

-To upload a package, you need a personal account on -&ftp-master-host;, which you should have as an -official maintainer. If you use scp or rsync -to transfer the files, place them into &us-upload-dir;; -if you use anonymous FTP to upload, place them into -&upload-queue;. -

-If you want to use the feature described in , -you'll have to upload to ftp-master. It is the only upload -point that supports delayed incoming. +To upload a package, you should upload the files (including the signed +changes and dsc-file) with anonymous ftp to +&ftp-master-host; in the directory &upload-queue;. +To get the files processed there, they need to be signed with a key in the +debian keyring.

Please note that you should transfer the changes file last. Otherwise, your upload may be rejected because the archive maintenance software will parse the changes file and see that not -all files have been uploaded. If you don't want to bother with transferring -the changes file last, you can simply copy your files to a temporary -directory on ftp-master and then move them to -&us-upload-dir;. -

+all files have been uploaded. +

Note: Do not upload to ftp-master cryptographic packages which belong to contrib or non-free. Uploads of such software should go to non-us (see ftp-master; depending on the case they may still be uploaded to non-US/non-free (it's in non-free because of distribution issues and not because of the license of the software). If you can't upload it to -ftp-master, then neither can you upload it to the overseas upload -queues on chiark or erlangen. If you are not sure +ftp-master, then neither can you upload it to backup +queues that finally also end up on ftp-master. If you are not sure whether U.S. patent controls or cryptographic controls apply to your package, post a message to &email-debian-devel; and ask.

You may also find the Debian packages or useful -when uploading packages. These handy programs help automate the +when uploading packages. These handy programs help automate the process of uploading packages into Debian.

-After uploading your package, you can check how the archive -maintenance software will process it by running dinstall -on your changes file: -dinstall -n foo.changes -

-Note that dput can do this for you automatically. +For removing packages, please see the README file in that ftp directory, +and the Debian package . Uploading to non-US

-As discussed above, export controlled software should not be uploaded -to ftp-master. Instead, upload the package to -non-us.debian.org, placing the files in -&non-us-upload-dir; (again, both and can do this for you if invoked properly). By default, -you can use the same account/password that works on -ftp-master. If you use anonymous FTP to upload, place the -files into &upload-queue;. +Note: non-us is currently not processed any more.

-You can check your upload the same way it's done on ftp-master, -with: -dinstall -n foo.changes +As discussed above, export controlled software should not be uploaded +to ftp-master. Instead, upload the package with anonymous FTP +to non-us.debian.org, placing the files in +&upload-queue; (again, both and can do this for you if invoked properly).

Note that U.S. residents or citizens are subject to restrictions on export of cryptographic software. As of this writing, U.S. citizens @@ -1834,64 +1849,50 @@ advice. Again, it is strongly recommended that U.S. citizens and residents consult a lawyer before doing uploads to non-US. - Uploads via chiark -

-If you have a slow network connection to ftp-master, there are -alternatives. One is to upload files to Incoming via a -upload queue in Europe on chiark. For details connect to -. -

-Note: Do not upload packages containing software that is -export-controlled by the United States government to the queue on -chiark. Since this upload queue goes to ftp-master, the -prescription found in applies here as well. -

-The program dupload comes with support for uploading to -chiark; please refer to the documentation that comes with the -program for details. - - - Uploads via erlangen + Delayed uploads

-Another upload queue is available in Germany: just upload the files -via anonymous FTP to . +Delayed uploads are done for the moment via the delayed queue at +gluck. The upload-directory is +gluck:~tfheen/DELAYED/[012345678]-day. +0-day is uploaded approximately one hour before dinstall runs.

-The upload must be a complete Debian upload, as you would put it into -ftp-master's Incoming, i.e., a .changes files -along with the other files mentioned in the .changes. The -queue daemon also checks that the .changes is correctly -signed with GnuPG or OpenPGP by a Debian developer, so that no bogus files can find -their way to ftp-master via this queue. Please also make sure that -the Maintainer field in the .changes contains -your e-mail address. The address found there is used for all -replies, just as on ftp-master. -

-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 a -mail reply from the queue daemon explaining what happened to your -upload. Hopefully it should have been moved to ftp-master, but in -case of errors you're notified, too. +With a fairly recent dput, this section + +[tfheen_delayed] +method = scp +fqdn = gluck.debian.org +incoming = ~tfheen + +in ~/.dput.cf should work fine for uploading to the DELAYED queue.

-Note: Do not upload packages containing software that is -export-controlled by the United States government to the queue on -erlangen. Since this upload queue goes to ftp-master, the +Note: +Since this upload queue goes to ftp-master, the prescription found in applies here as well. -

-The program dupload comes with support for uploading to -erlangen; please refer to the documentation that comes with -the program for details. + Security uploads +

+Do NOT upload a package to the security upload queue (oldstable-security, +stable-security, etc.) without prior authorization from the security +team. If the package does not exactly meet the team's requirements, it +will cause many problems and delays in dealing with the unwanted upload. +For details, please see section . Other upload queues

-Another upload queue is available which is based in the US, and is a -good backup when there are problems reaching ftp-master. You can -upload files, just as in erlangen, to . +The scp queues on ftp-master, non-us and security are mostly unuseable +due to the login restrictions on those hosts.

-An upload queue is available in Japan: just upload the files via -anonymous FTP to . - +The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are +currently down. Work is underway to resurrect those. +

+The queues on master.debian.org, samosa.debian.org, master.debian.or.jp +and ftp.chiark.greenend.org.uk are down permanently and will not be +resurrected. The queue in Japan will be replaced with a new queue on +hp.debian.or.jp some day. +

+For the time being, the anonymous ftp queue on auric.debian.org (the +former ftp-master) works, but it is deprecated and will be removed at +some point in the future. Notification that a new package has been installed @@ -2539,20 +2540,20 @@ You should set the package maintainer to Debian QA Group against the pseudo package wnpp. The bug report should be titled O: package -- short description indicating that the package is now orphaned. The severity of the bug -should be set to normal. If you feel it's necessary, send a copy +should be set to normal; if the package has a priority of standard +or higher, it should be set to important. +If you feel it's necessary, send a copy to &email-debian-devel; by putting the address in the X-Debbugs-CC: header of the message (no, don't use CC:, because that way the message's subject won't indicate the bug number).

-If the package is especially crucial to Debian, you should instead submit +If you just intend to give the package away, but you can keep maintainership +for the moment, then you should instead submit a bug against wnpp and title it RFA: package -- -short description and set its severity to -important. RFA stands for Request For Adoption. -Definitely copy the message to debian-devel in this case, as described -above. +short description. +RFA stands for Request For Adoption.

-Read instructions on the -for more information. +More information is on the . Adopting a package

@@ -3219,7 +3220,7 @@ available at . Separating your patches into multiple files

Big, complex packages may have many bugs that you need to deal with. -If you correct a number of bug directly in the source, if you're not +If you correct a number of bugs directly in the source, and you're not careful, it can get hard to differentiate the various patches that you applied. It can get quite messy when you have to update the package to a new upstream version which integrates some of the fixes (but not @@ -3387,6 +3388,32 @@ spell-check it. ispell has a special -g option for debian/control files: ispell -d american -g debian/control +

+User usually expect these questions to be answered in the package +description. + + +What does the package do? If it is an add-on to another package, +then the short description of the package we are an add on to +should be put in here. + +Why should I want this package? This is related to the above, +but not the same (this is a mail user agent; this is cool, fast, +interfaces with pgp and ldap and imap, has features X, Y, and Z). + +If this package should not be installed directly, but is pulled in +by another package, this should be mentioned. + +If the package is experimental, or there are other reasons it +should not be used, if there are other packages that should be +used instead, it should be here as well. + +How is this package different from the competition? Is it a better +implementation? more features? different features? Why should I +choose this package (2. should talk about the class of packages, and +this about this particular package, if you have information related to both). + + @@ -3552,6 +3579,44 @@ changelog). Where's the description? If you can't think of a descriptive message, start by inserting the title of each different bug. + + + Suplimenting changelogs with NEWS.Debian files +

+Important news about changes in a package can also be put in NEWS.Debian +files. The news will be displayed by tools like apt-listchanges, before +all the rest of the changelogs. This is the preferred means to let the user +know about significant changes in a package. It is better than using +debconf notes since it is less annoying and the user can go back and refer +to the NEWS.Debian file after the install. And it's better than listing +major changes in README.Debian, since the user can easily miss such notes. +

+The file format is the same as a debian changelog file, but leave off +the asterisks and describe each news item with a full paragraph when +necessary rather than the more concise summaries that would go in a +changelog. It's a good idea to run your file through dpkg-parsechangelog to +check its formatting as it will not be automatically checked during build +as the changelog is. Here is an example of a real NEWS.Debian file: + +cron (3.0pl1-74) unstable; urgency=low + + The checksecurity script is no longer included with the cron package: + it now has its own package, "checksecurity". If you liked the + functionality provided with that script, please install the new + package. + + -- Steve Greenland <stevegr&debian.org> Sat, 6 Sep 2003 17:15:03 -0500 + +

+The NEWS.Debian file is installed as +/usr/share/doc/<package>/NEWS.Debian.gz. It is compressed, and +always has that name even in Debian native packages. If you use debhelper, +dh_installchangelogs will install debian/NEWS files for you. +

+Unlike changelog files, you need not update NEWS.Debian files with every +release. Only update them if you have something particularly newsworthy +that user should know about. If you have no news at all, there's no need +to ship a NEWS.Debian file in your package. No news is good news!