X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=ba8b075a043559a7f07ba79b040c261196e15892;hb=aaed407b0c363c49306aff53515e6f88e807bd4a;hp=5c10c64b691f8767e791273618abcf2a766761f8;hpb=5074eeb91731c7595f423fb646f822e0efa44aa8;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 5c10c64..ba8b075 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + @@ -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 . @@ -684,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

@@ -1037,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

@@ -3369,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). + + @@ -3534,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!