X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=ba8b075a043559a7f07ba79b040c261196e15892;hp=2749638dff44270226d622ae07432a2f9f846749;hb=aaed407b0c363c49306aff53515e6f88e807bd4a;hpb=b8bb53a2dc2ebe40322a0f29f174a5076f947d66 diff --git a/developers-reference.sgml b/developers-reference.sgml index 2749638..ba8b075 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -1,20 +1,19 @@ - %versiondata; - - %commondata; + %versiondata; + + %commondata; - + + - + revision of the original developer's reference in cvs-en-rev --> + - - FIXME: "> + + FIXME: "> ]> @@ -78,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 . @@ -126,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 @@ -142,7 +142,7 @@ name="New Maintainer's Corner">. It describes exactly the preparations you have to do before you can register to become a Debian developer. -For example, before you apply, you have to to read the . Registering as a developer means that you agree with and pledge to uphold the Debian Social Contract; it is very important that @@ -221,7 +221,7 @@ To apply as a new maintainer, you need an existing Debian maintainer to verify your application (an advocate). After you have contributed to Debian for a while, and you want to apply to become a registered developer, an existing developer with whom you -have worked over the past months has to express his belief that you +have worked over the past months has to express their belief that you can contribute to Debian successfully.

When you have found an advocate, have your GnuPG key signed and have @@ -256,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 . @@ -333,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. @@ -350,14 +351,15 @@ Don't forget to remove the "on vacation" flag when you come back!

A big part of your job as Debian maintainer will be to stay in contact with the upstream developers. Debian users will sometimes report bugs -to the Bug Tracking System that are not specific to Debian. You -must forward these bug reports to the upstream developers so that -they can be fixed in a future release. It's not your job to fix -non-Debian specific bugs. However, if you are able to do so, you are -encouraged to contribute to upstream development of the package by -providing a fix for the bug. Debian users and developers will often -submit patches to fix upstream bugs, and you should evaluate and -forward these patches upstream. +that are not specific to Debian to our bug tracking system. You +have to forward these bug reports to the upstream developers so that +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 +and forward these patches upstream.

If you need to modify the upstream sources in order to build a policy compliant package, then you should propose a nice fix to the upstream @@ -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. @@ -417,10 +419,29 @@ resources that are available to help you in your maintainer work. Mailing lists

-The mailing list server is at &lists-host;. +Much of the conversation between Debian developers (and users) is managed +through a wide array of mailing lists we host at +. +To find out more on how to subscribe or unsubscribe, how to post and how not +to post, where to find old posts and how to search them, how to contact the +list maintainers and see various other information about the mailing lists, +please read . This section will only cover +aspects of mailing lists that are of particular interest to developers. + + Basic rules for use +

+When replying to messages on the mailing list, please do not send a +carbon copy (CC) to the original poster unless they explicitly +request to be copied. Anyone who posts to a mailing list should read +it to see the responses.

-Online archives of mailing lists are available at . +Cross-posting (sending the same message to multiple lists) is discouraged. +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 +posting messages. +

+Please read the +for more information. Core development mailing lists

@@ -441,40 +462,8 @@ The core Debian mailing lists that developers should use are:

-There are -other mailing lists available for a variety of special topics; see - for a list. - - Subscribing and unsubscribing -

-To subscribe to or unsubscribe from any of the Debian mailing lists, email -debian-foo-REQUEST@&lists-host;, where -debian-foo is the name of the list, with the word -subscribe in the Subject to subscribe to the list or -unsubscribe to unsubscribe. -

-If you prefer to use a web page to subscribe to multiple mailing lists, -there's one at . -

-You can download the current list of mailing lists and basic usage -instructions from -or install the doc-debian package and have it -locally in &file-mail-lists;. - - Basic rules for use -

-When replying to messages on the mailing list, please do not send a -carbon copy (CC) to the original poster unless they explicitly -request to be copied. Anyone who posts to a mailing list should read -it to see the responses. -

-Cross-posting (sending the same message to multiple lists) is discouraged. -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 -posting messages. -

-Please read the -for more information. +There are other mailing lists available for a variety of special topics; +see for a list. Special lists

@@ -493,6 +482,18 @@ for Debian related correspondence such as contacting upstream authors about licenses, bugs, etc. or discussing the project with others where it might be useful to have the discussion archived somewhere. + Requesting new development-related lists +

+Before requesting a mailing list that relates to the development of a +package (or a small group of related packages), please consider if using +an alias (via a .forward-aliasname file on master.debian.org, which +translates into a reasonably nice you-aliasname@debian.org +address) or a self-managed mailing list on Alioth +is more appropriate. +

+If you decide that a regular mailing list on lists.debian.org is really what +you want, go ahead and fill in a request, following . IRC channels

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

@@ -608,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 @@ -678,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

@@ -715,7 +737,7 @@ Those features are documented at .

The &debian-formal; distribution consists of a lot of packages (.deb's, currently around &number-of-pkgs;) and a few -additional files (such documentation and installation disk images). +additional files (such as documentation and installation disk images).

Here is an example directory tree of a complete Debian archive:

@@ -740,13 +762,13 @@ In each of the areas, there is a directory for the source packages (source) and a directory for each supported architecture (binary-i386, binary-m68k, etc.).

-The main area contains additional directories which holds +The main area contains additional directories which hold the disk images and some essential pieces of documentation required for installing the Debian distribution on a specific architecture (disks-i386, disks-m68k, etc.). - Sections + Sections

The main section of the Debian archive is what makes up the official &debian-formal; distribution. The @@ -808,7 +830,7 @@ The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola Linux 2.2 kernel supports even more architectures, including ARM and UltraSPARC. Since Linux supports these platforms, Debian decided that it should, too. Therefore, Debian has ports underway; in fact, we -also have ports underway to non-Linux kernel. Aside from +also have ports underway to non-Linux kernels. Aside from i386 (our name for Intel x86), there is m68k, alpha, powerpc, sparc, hurd-i386, arm, ia64, hppa, s390, mips, @@ -822,7 +844,7 @@ ships for the i386, m68k, alpha, and support of five new architectures: ia64, hppa, s390, mips and mipsel.

-Information for developers or uses about the specific ports are +Information for developers and users about the specific ports are available at the . @@ -851,7 +873,7 @@ with checksums (md5sums) and some additional info about the package (maintainer, version, etc.). - Distribution directories + Distributions

The directory system described in the previous chapter is itself contained within distribution directories. Each @@ -887,11 +909,12 @@ 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.

- 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 -new packages have been installed. +new packages have been installed. See .

After a period of development, once the release manager deems fit, the testing distribution is frozen, meaning that the policies @@ -927,6 +950,62 @@ Note that development under unstable continues during the freeze period, since the unstable distribution remains in place in parallel with testing. + + More information about the testing distribution +

+The scripts that update the testing distribution are run each +day after the installation of the updated packages. They generate the +Packages files for the testing distribution, but +they do so in an intelligent manner trying to avoid any inconsistency +and trying to use only non-buggy packages. +

+The inclusion of a package from unstable is conditional on +the following: + + +The package must have been available in unstable for several days; +the precise number depends on the upload's urgency field. It +is 10 days for low urgency, 5 days for medium urgency and 2 days for high +urgency. Those delays may be doubled during a freeze; + +It must have less release-critical bugs than the version available +in testing; + +It must be available on all architectures on which it has been +previously built. may be of interest to +check that information; + +It must not break any dependency of a package that is already available +in testing; + +The packages on which it depends must either be available in testing +or they must be accepted into testing at the same time (and they will +if they respect all the necessary criteria); + +

+To find out whether a package is progressing into testing or not, see the +testing script output on the , or use the program grep-excuses +which is in the devscripts package. This utility can +easily be used in a to keep one +informed of the progression of their packages into testing. +

+The update_excuses file does not always give the precise reason +why the package is refused, one may have to find it on their own by looking +for what would break with the inclusion of the package. The + gives some more +information about the usual problems which may be causing such troubles. +

+Sometimes, some packages never enter testing because the set of +inter-relationship is too complicated and cannot be sorted out +by the scripts. In that case, the release manager must be +contacted, and he will force the inclusion of the packages. +

+In general, please refer to the for more information. It also includes +answers to some of the frequently asked questions. + + Experimental

The experimental distribution is a special distribution. @@ -955,7 +1034,7 @@ into experimental. Whenever there is a new upstream version of a package that introduces new features but breaks a lot of old ones, it should either not be uploaded, or be uploaded to experimental. A new, beta, version of some software -which uses completely different configuration can go into +which uses a completely different configuration can go into experimental, at the maintainer's discretion. If you are working on an incompatible or complex upgrade situation, you can also use experimental as a staging area, so that testers can get early @@ -974,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

@@ -1018,8 +1100,8 @@ symbolic links for stable, testing, and

The various download archives and the web site have several mirrors available in order to relieve our canonical servers from heavy load. -In fact, some of the canonical servers aren't public, and instead a -first tier of mirrors balances the load. That way, users always access +In fact, some of the canonical servers aren't public — a first tier +of mirrors balances the load instead. That way, users always access the mirrors and get used to using them, which allows Debian to better spread its bandwidth requirements over several servers and networks, and basically makes users avoid hammering on one primary location. @@ -1041,15 +1123,16 @@ have accounts on these machines. The Incoming system

-The Incoming system is responsible of collecting updated packages and +The Incoming system is responsible for collecting updated packages and installing them in the Debian archive. It consists of a set of directories and scripts that are installed both on &ftp-master-host; and &non-us-host;.

Packages are uploaded by all the maintainers into a directory called unchecked. This directory is scanned every 15 minutes by -the katie script, which verifies the integrity of the uploaded packages and the cryptographic -signatures. If the package is considered ready to be installed, it +the katie script, which verifies the integrity of the uploaded +packages and their cryptographic signatures. +If the package is considered ready to be installed, it is moved into the accepted directory. If this is the first upload of the package, it is moved in the new directory, where it waits for an approval of the ftpmasters. If the package contains files to be installed @@ -1084,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 @@ -1123,60 +1210,6 @@ easily upload a package in one of the delayed directories: DELAY=5 dupload --to delayed <changes-file> - - The "testing" distribution -

-The scripts that update the testing distribution are run each day -after the installation of the -updated packages. They generate the Packages files for -the testing distribution, but they do so in an intelligent manner -trying to avoid any inconsistency and trying to use only -non-buggy packages. -

The inclusion of a package from unstable is conditional on the following: - - -The package must have been available in unstable for several days; -the precise number depends on the upload's urgency field. It -is 10 days for low urgency, 5 days for medium urgency and 2 days for high -urgency. Those delays may be doubled during a freeze; - -It must have less release-critical bugs than the version available -in testing; - -It must be available on all architectures on which it has been -previously built. may be of interest to -check that information; - -It must not break any dependency of a package that is already available -in testing; - -The packages on which it depends must either be available in testing -or they must be accepted into testing at the same time (and they will -if they respect themselves all the criteria); - -

-To find out whether a package is progressing into testing or not, see the -testing script output on the , or use the program grep-excuses -which is in the devscripts package. This utility can -easily be used in a to keep one -informed of the progression of their packages into testing. -

-The update_excuses file does not always give the precise reason -why the package is refused, one may have to find it on their own by looking -what would break with the inclusion of the package. The gives some more information -about the usual problems which may be causing such troubles. -

-Sometimes, some packages never enter testing because the set of -inter-relationship is too complicated and can not be sorted out -by the scripts. In that case, the release manager must be -contacted, and he will force the inclusion of the packages. -

-In general, please refer to the for more information. It also includes -answers to some of the frequently asked questions. - Package information

@@ -1190,8 +1223,8 @@ available in the various distributions. Each version links to a page which provides information, including the package description, the dependencies and package download links.

-The bug tracking system track bugs for each package. You can -view the bugs of a given package at the URL +The bug tracking system tracks bugs for each package. +You can view the bugs of a given package at the URL http://&bugs-host;/package-name. The madison utility @@ -1218,12 +1251,13 @@ recompiled on most of the architectures. The Package Tracking System

-The Package Tracking System (PTS) is basically a tool to track by mail -the activity of a source package. You just have to subscribe -to a source package to start getting the mails related to it. -You get the same mails as the maintainer. Each mail -sent through the PTS is classified and associated to one of -the keyword listed below. This will let you select the mails that +The Package Tracking System (PTS) is an email-based tool to track +the activity of a source package. This really means that you can +get the same emails that the package maintainer gets, simply by +subscribing to the package in the PTS. +

+Each email sent through the PTS is classified under one of +the keywords listed below. This will let you select the mails that you want to receive.

By default you will get: @@ -1234,46 +1268,48 @@ All the bug reports and following discussions. bts-control -The control mails notifying a status change in one of the bugs. +The email notifications from control@bugs.debian.org +about bug report status changes. upload-source -The confirmation mail from katie when an uploaded source +The email notification from katie when an uploaded source package is accepted. katie-other -Other warning and error mails from katie (like the -override disparity for the section or priority field). +Other warning and error emails from katie (such as an +override disparity for the section and/or the priority field). default -Any non-automatic mail sent to the PTS by people who wanted to +Any non-automatic email sent to the PTS by people who wanted to contact the subscribers of the package. This can be done by sending mail -to srcpackage@&pts-host;. In order to prevent spam, -mails sent to these addresses must contain the header "X-PTS-Approved" -with a non-empty string. - +to sourcepackage@&pts-host;. In order to prevent spam, +all messages sent to these addresses must contain the X-PTS-Approved +header with a non-empty value. summary -In the future, you may receive regular summary mails to keep you -informed of the package's status (bug statistics, porting overview, -progression in testing, ...). +(This is a planned expansion.) +The regular summary emails about the package's status (bug statistics, +porting overview, progression in testing, ...). +

-You can also decide to receive some more information: +You can also decide to receive additional information: upload-binary -The confirmation mail from katie when an uploaded binary -package is accepted (to check that your package is recompiled for all -architectures). +The email notification from katie when an uploaded binary +package is accepted. In other words, whenever a build daemon or a porter +uploads your package for another architecture, you can get an email to +track how your package gets recompiled for all architectures. cvs -CVS commits if the maintainer has setup a system to forward commit -notification to the PTS. +CVS commit notifications, if the package has a CVS repository and the +maintainer has set up forwarding commit notifications to the PTS. ddtp @@ -1288,17 +1324,17 @@ various commands to pts@qa.debian.org. -subscribe <srcpackage> [<email>] +subscribe <sourcepackage> [<email>] Subscribes email to communications related to the source package - srcpackage. Sender address is used if the second argument is - not present. If srcpackage is not a valid source package, + sourcepackage. Sender address is used if the second argument is + not present. If sourcepackage is not a valid source package, you'll get a warning. However if it's a valid binary package, the PTS will subscribe you to the corresponding source package. -unsubscribe <srcpackage> [<email>] +unsubscribe <sourcepackage> [<email>] - Removes a previous subscription to the source package srcpackage + Removes a previous subscription to the source package sourcepackage using the specified email address or the sender address if the second argument is left out. @@ -1309,10 +1345,9 @@ various commands to pts@qa.debian.org. keyword [<email>] - Tells you the keywords that you are accepting. Each mail sent through - the Package Tracking System is associated to a keyword and you receive - only the mails associated to keywords that you are accepting. Here is - the list of available keywords: + Tells you the keywords that you are accepting. + For an explanation of keywords, see + above. Here's a quick summary: bts: mails coming from the Debian Bug Tracking System bts-control: reply to mails sent to &email-bts-control; @@ -1327,17 +1362,17 @@ various commands to pts@qa.debian.org. default: all the other mails (those which aren't "automatic") -keyword <srcpackage> [<email>] +keyword <sourcepackage> [<email>] - Same as previous item but for the given source package since + Same as the previous item but for the given source package, since you may select a different set of keywords for each source package. keyword [<email>] {+|-|=} <list of keywords> - Accept (+) or refuse (-) mails associated to the given keyword(s). + Accept (+) or refuse (-) mails classified under the given keyword(s). Define the list (=) of accepted keywords. -keyword <srcpackage> [<email>] {+|-|=} <list of keywords> +keyword <sourcepackage> [<email>] {+|-|=} <list of keywords> Same as previous item but overrides the keywords list for the indicated source package. @@ -1351,9 +1386,9 @@ various commands to pts@qa.debian.org. Filtering PTS mails

Once you are subscribed to a package, you will get the mails sent to -srcpackage@packages.qa.debian.org. Those mails +sourcepackage@packages.qa.debian.org. Those mails have special headers appended to let you filter them in a special -mailbox with procmail. The added headers are +mailbox (e.g. with procmail). The added headers are X-Loop, X-PTS-Package, X-PTS-Keyword and X-Unsubscribe.

@@ -1370,64 +1405,64 @@ X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org

If you use a publicly accessible CVS repository for maintaining your Debian package you may want to forward the commit notification -to the PTS so that the subscribers (possible co-maintainers) can +to the PTS so that the subscribers (and possible co-maintainers) can closely follow the package's evolution.

-It's very easy to setup. Once your CVS repository generates commit -notifications, you just have to make sure it sends a copy of those mails -to srcpackage_cvs@&pts-host;. Only people who -accepts the cvs keyword will receive the notifications. +Once you set up the CVS repository to generate commit notifications, +you just have to make sure it sends a copy of those mails +to sourcepackage_cvs@&pts-host;. Only the people +who accept the cvs keyword will receive these notifications. The PTS web interface

-The PTS has been extended with a web interface that puts together -many information about each source package. It features many useful +The PTS has a web interface at that puts +together a lot of information about each source package. It features many useful links (BTS, QA stats, contact information, DDTP translation status, -buildd logs) and gathers many more information from various places +buildd logs) and gathers much more information from various places (30 latest changelog entries, testing status, ...). It's a very useful tool if you want to know what's going on with a specific source -package. Furthermore there's a form that let you easily subscribe to -the mail service offered by the PTS. +package. Furthermore there's a form that allows easy subscription to +the PTS via email.

You can jump directly to the web page concerning a specific source package -with an url like http://&pts-host;/srcpackage. Otherwise -you can go through the . +with a URL like http://&pts-host;/sourcepackage.

This web interface has been designed like a portal for the development of -packages: you can add custom content on the pages of your packages. You can -add "static information" (news item that are meant to stay available +packages: you can add custom content on your packages' pages. You can +add "static information" (news items that are meant to stay available indefinitely) and news items in the "latest news" section.

-Static news can be used to indicate: +Static news items can be used to indicate: -the availability of a project hosted on alioth.debian.org for co-maintaining the package -a link to the upstream website -a link to the upstream bugtracker +the availability of a project hosted on Alioth for co-maintaining the package +a link to the upstream web site +a link to the upstream bug tracker the existence of an IRC channel dedicated to the software any other available resource that could be useful in the maintenance of the package -Usual news item may be used to announce that: +Usual news items may be used to announce that: -beta packages are available for test +beta packages are available for testing final packages are expected for next week the packaging is about to be redone from scratch backports are available -the maintainer is on vacation (if he wishes to publish this information) +the maintainer is on vacation (if they wish to publish this information) a NMU is being worked on something important will affect the package

-Both kind of news are generated in a similar manner: you just have to send a mail -either to pts-static-news@qa.debian.org or to -pts-news@qa.debian.org. The mail should indicate which package is -concerned by the news by giving the name of the source package in a +Both kinds of news are generated in a similar manner: you just have to send +an email either to pts-static-news@qa.debian.org or to +pts-news@qa.debian.org. The mail should indicate which +package is concerned by having the name of the source package in a X-PTS-Package mail header or in a Package pseudo-header (like the -BTS reports). If an URL is available in the X-PTS-Url mail header or in +BTS reports). If a URL is available in the X-PTS-Url mail header or in the Url pseudo-header, then the result is a link to that URL instead of a complete news item.

-Some examples of valid mails used to generate news item in the PTS are following. The first one -adds a link to the cvsweb interface of debian-cd in the "Static information" section. +Here are a few examples of valid mails used to generate news items in +the PTS. The first one adds a link to the cvsweb interface of debian-cd +in the "Static information" section: From: Raphael Hertzog <hertzog@debian.org> To: pts-static-news@qa.debian.org @@ -1436,9 +1471,10 @@ Subject: Browse debian-cd CVS repository with cvsweb Package: debian-cd Url: http://cvs.debian.org/debian-cd/ -The second one is an announce sent to a mailing list which is also sent +

+The second one is an announcement sent to a mailing list which is also sent to the PTS so that it is published on the PTS web page of the package. Note the -use of the BCC field to avoid answers sent to the PTS by mistake ... +use of the BCC field to avoid answers sent to the PTS by mistake. From: Raphael Hertzog <hertzog@debian.org> To: debian-gtk-gnome@lists.debian.org @@ -1446,17 +1482,17 @@ Bcc: pts-news@qa.debian.org Subject: Galeon 2.0 backported for woody X-PTS-Package: galeon -Hello gnomers ! +Hello gnomers! I'm glad to announce that galeon has been backported for woody. You'll find everything here: ...

-Think twice before adding a news to the PTS because you won't be able to -remove it later and you wan't be able to edit it either. The only thing that you -can do is send a second news that will deprecate the information contained in -the first news. +Think twice before adding a news item to the PTS because you won't be able +to remove it later and you wan't be able to edit it either. The only thing +that you can do is send a second news item that will deprecate the +information contained in the previous one. Developer's packages overview

@@ -1472,6 +1508,21 @@ It is a good idea to look up your own data regularly so that you don't forget any open bug, and so that you don't forget which packages are under your responsibility. + Debian *Forge: Alioth +

+Alioth is a fairly new Debian service, based on a slightly modified version +of the GForge software (which evolved from SourceForge). This software +offers developers access to easy-to-use tools such as bug trackers, patch +manager, project/task managers, file hosting services, mailing lists, CVS +repositories etc. All these tools are managed via a web interface. +

+It is intended to provide facilities to free software projects backed or led +by Debian, facilitate contributions from external developers to projects +started by Debian, and help projects whose goals are the promotion of Debian +or its derivatives. +

+For more information please visit . + Managing Packages

@@ -1553,7 +1604,7 @@ Changelog entries can be used to automatically close Debian bugs when the package is installed into the archive. See .

-It is conventional that the changelog entry notating of a package that +It is conventional that the changelog entry of a package that contains a new upstream version of the software looks like this: * new upstream version @@ -1656,13 +1707,11 @@ 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. - Uploads to stable + + Special case: uploads to the stable distribution

Uploading to stable means that the package will be placed into the stable-proposed-updates directory of the Debian archive for further @@ -1683,8 +1732,8 @@ appropriate proposed-updates archive when the advisory is released. See for detailed information on handling security problems.

-It is discouraged to change anything else in the package that isn't -important, because even trivial fixes can cause bugs later on. +Changing anything else in the package that isn't important is discouraged, +because even trivial fixes can cause bugs later on.

Packages uploaded to stable need to be compiled on systems running stable, so that their dependencies are limited to the libraries @@ -1700,8 +1749,13 @@ 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. - Uploads to testing-proposed-updates + + Special case: uploads to testing-proposed-updates

The testing distribution is fed with packages from unstable according to the rules explained in . However, the release manager may stop the testing @@ -1724,21 +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;. +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 @@ -1808,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 -

-Another upload queue is available in Germany: just upload the files -via anonymous FTP to . + Delayed uploads

-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. +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.

-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 @@ -1892,7 +1919,7 @@ will receive a separate email notifying you of that. Read on below. Note also that if you upload via queues, the queue daemon software will also send you a notification by email. - Determining section and priority of a package + Specifying the package section, subsection and priority

The debian/control file's Section and Priority fields do not actually specify where the file will @@ -1921,9 +1948,11 @@ For more information about override files, see and .

-Note also that the term "section" is used for the separation of packages -according to their licensing, e.g. main, contrib and -non-free. This is described in another section, . +Note that the Section field describes both the section as +well as the subsection, which are described in . If the section is "main", it should be +omitted. The list of allowable subsections can be found in . Handling bugs @@ -1935,8 +1964,8 @@ reorder them, and how to process and close them.

The bug tracking system's features interesting to developers are described in the . -This includes closing bugs, sending followup messages, assigning severities, -tags, marking bugs as forwarded and other issues. +This includes closing bugs, sending followup messages, assigning severities +and tags, marking bugs as forwarded and other issues.

Operations such as reassigning bugs to other packages, merging separate bug reports about the same issue, or reopening bugs when they are @@ -1970,15 +1999,18 @@ maintainer address. Responding to bugs

-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-host;). If you're writing a new +When responding to bugs, make sure that any discussion you have about +bugs is sent both to the original submitter of the bug, and to the bug +itself (e.g., 123@&bugs-host;). If you're writing a new mail and you don't remember the submitter email address, you can use the 123-submitter@&bugs-host; 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-host;).

+If you get a bug which mentions "FTBFS", that means "Fails to build +from source". Porters frequently use this acronym. +

Once you've dealt with a bug report (e.g. fixed it), mark it as done (close it) by sending an explanation message to 123-done@&bugs-host;. If you're fixing a bug by @@ -2013,14 +2045,14 @@ Here's a list of steps that you may follow to handle a bug report: Decide whether the report corresponds to a real bug or not. Sometimes users are just calling a program in the wrong way because they haven't read the documentation. If you diagnose this, just close the bug with -enough information to let the user correct his problem (give pointers +enough information to let the user correct their problem (give pointers to the good documentation and so on). If the same report comes up again and again you may ask yourself if the documentation is good enough or if the program shouldn't detect its misuse in order to give an informative error message. This is an issue that may need to be brought to the upstream author.

-If the bug submitter disagree with your decision to close the bug, +If the bug submitter disagrees with your decision to close the bug, they may reopen it until you find an agreement on how to handle it. If you don't find any, you may want to tag the bug wontfix to let people know that the bug exists but that it won't be corrected. @@ -2031,10 +2063,10 @@ the BTS if you wish to keep it reported against your package). Before doing so, please read the . If the bug is real but it's caused by another package, just reassign -the bug the right package. If you don't know which package it should +the bug to the right package. If you don't know which package it should be reassigned to, you may either ask for help on &email-debian-devel; or reassign it to debian-policy to let them decide which -package is in fault. +package is at fault.

Sometimes you also have to adjust the severity of the bug so that it matches our definition of the severity. That's because people tend to @@ -2042,8 +2074,8 @@ inflate the severity of bugs to make sure their bugs are fixed quickly. Some bugs may even be dropped to wishlist severity when the requested change is just cosmetic. -The bug submitter may have forgotten to provide some information, in that -case you have to ask him the information required. You may use the +The bug submitter may have forgotten to provide some information, in which +case you have to ask them the required information. You may use the moreinfo tag to mark the bug as such. Moreover if you can't reproduce the bug, you tag it unreproducible. Anyone who can reproduce the bug is then invited to provide more information @@ -2119,7 +2151,7 @@ changelog as described above. If you simply want to close bugs that don't have anything to do with an upload you made, do it by emailing an explanation to XXX-done@&bugs-host;. Do not close bugs in the changelog entry of a version if -the changes in that version of the package doesn't have any bearing on +the changes in that version of the package don't have any bearing on the bug.

For general information on how to write your changelog entries, see @@ -2141,8 +2173,10 @@ security advisories, and maintaining security.debian.org. When you become aware of a security-related bug in a Debian package, whether or not you are the maintainer, collect pertinent information about the problem, and promptly contact the security team at -&email-security-team; as soon as possible. Useful information -includes, for example: +&email-security-team; as soon as possible. DO NOT UPLOAD any +packages for stable; the security team will do that. + +Useful information includes, for example: What versions of the package are known to be affected by the @@ -2179,7 +2213,7 @@ There are a few ways a developer can learn of a security problem: he notices it on a public forum (mailing list, web site, etc.) someone files a bug report - someone informs him via private email + someone informs them via private email In the first two cases, the information is public and it is important @@ -2213,7 +2247,7 @@ itself is public, and can (and will) be examined by the general public.

There are two reasons for releasing information even though secrecy is -requested: the problem has been known for a while, or that the problem +requested: the problem has been known for a while, or the problem or exploit has become public. Security Advisories @@ -2286,30 +2320,48 @@ indeed succeeds on the unpatched package and fails on the fixed package. Test other, normal actions as well, as sometimes a security fix can break seemingly unrelated features in subtle ways.

+Do NOT include any changes in your package which are +not directly related to fixing the vulnerability. These will only +need to be reverted, and this wastes time. If there are other bugs in +your package that you would like to fix, make an upload to +proposed-updates in the usual way, after the security advisory is +issued. The security update mechanism is not a means for introducing +changes to your package which would otherwise be rejected from the +stable release, so please do not attempt to do this. +

Review and test your changes as much as possible. Check the differences from the previous version repeatedly (interdiff from the patchutils package and debdiff from devscripts are useful tools for this, see ).

-When packaging the fix, keep the following points in mind: +Be sure to verify the following items: - Make sure you target the right distribution in your + Target the right distribution in your debian/changelog. For stable this is stable-security and for testing this is testing-security, and for the previous stable release, this is oldstable-security. Do not target - distribution-proposed-updates! + distribution-proposed-updates or stable! + + The upload should have urgency=high. Make descriptive, meaningful changelog entries. Others will rely on them to determine whether a particular bug was fixed. - Whenever possible, include an external reference, preferably a CVE - identifier, so that it can be cross-referenced. + Always include an external reference, preferably a CVE + identifier, so that it can be cross-referenced. Include the same + information in the changelog for unstable, so that it is clear that + the same bug was fixed, as this is very helpful when verifying + that the bug is fixed in the next stable release. If a CVE + identifier has not yet been assigned, the security team will + request one so that it can be included in the package and in the advisory. Make sure the version number is proper. It must be greater than the current package, but less than package versions in later distributions. If in doubt, test it with dpkg - --compare-versions. For testing, there must be + --compare-versions. Be careful not to re-use a version + number that you have already used for a previous upload. For + testing, there must be a higher version in unstable. If there is none yet (for example, if testing and unstable have the same version) you must upload a new version to unstable first. @@ -2320,17 +2372,18 @@ When packaging the fix, keep the following points in mind: not build those. This point applies to normal package uploads as well. - If the upstream source has been uploaded to + Unless the upstream source has been uploaded to security.debian.org before (by a previous security update), build - the upload without the upstream source (dpkg-buildpackage - -sd). Otherwise, build with full source - (dpkg-buildpackage -sa). + the upload with full upstream source (dpkg-buildpackage + -sa). If there has been a previous upload to + security.debian.org with the same upstream version, you may upload + without upstream source (dpkg-buildpackage -sd). Be sure to use the exact same *.orig.tar.gz as used in the normal archive, otherwise it is not possible to move the security fix into the main archives later. - Be sure to build the package on a clean + Build the package on a clean system which only has packages installed from the distribution you are building for. If you do not have such a system yourself, you can use a debian.org machine (see ) @@ -2340,13 +2393,13 @@ When packaging the fix, keep the following points in mind: Uploading the fixed package

-DO NOT upload a package to the security upload queue +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.

-DO NOT upload your fix to proposed-updates without +Do NOT upload your fix to proposed-updates without coordinating with the security team. Packages from security.debian.org will be copied into the proposed-updates directory automatically. If a package with the same or a higher version number @@ -2426,9 +2479,9 @@ avoid unwanted removals and to keep a trace of why a package has been removed. For example, you can provide the name of the package that supersedes the one to be removed.

-Usually you only ask the removal of a package maintained by yourself. +Usually you only ask for the removal of a package maintained by yourself. If you want to remove another package, you have to get the approval -of its last maintainer. +of its maintainer.

If in doubt concerning whether a package is disposable, email &email-debian-devel; asking for opinions. Also of interest is the @@ -2436,6 +2489,7 @@ If in doubt concerning whether a package is disposable, email package. When invoked as apt-cache showpkg package, the program will show details for package, including reverse depends. +Removal of orphaned packages is discussed on &email-debian-qa;.

Once the package has been removed, the package's bugs should be handled. They should either be reassigned to another package in the case where @@ -2448,7 +2502,7 @@ software is simply no more part of Debian. In the past, it was possible to remove packages from incoming. However, with the introduction of the new incoming system, this is no longer possible. Instead, you have to upload a new revision of your package with -a higher version as the package you want to replace. Both versions will be +a higher version than the package you want to replace. Both versions will be installed in the archive but only the higher version will actually be available in unstable since the previous version will immediately be replaced by the higher. However, if you do proper testing of your @@ -2456,8 +2510,8 @@ packages, the need to replace a package should not occur too often anyway. Replacing or renaming packages

-Sometimes you made a mistake naming the package and you need to rename -it. In this case, you need to follow a two-step process. First, set +When you make a mistake naming your package, you should follow a two-step +process to rename it. First, set your debian/control file to replace and conflict with the obsolete name of the package (see the for details). Once you've uploaded @@ -2486,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

@@ -2542,7 +2596,7 @@ portability. Therefore, even if you are not a porter, you should read most of this chapter.

Porting is the act of building Debian packages for architectures that -is different from the original architecture of the package +are different from the original architecture of the package maintainer's binary package. It is a unique and essential activity. In fact, porters do most of the actual compiling of Debian packages. For instance, for a single i386 binary package, there must be @@ -2559,7 +2613,7 @@ the case. This section contains a checklist of ``gotchas'' often committed by Debian maintainers — common problems which often stymie porters, and make their jobs unnecessarily difficult.

-The first and most important watchword is to respond quickly to bug or +The first and most important thing is to respond quickly to bug or issues raised by porters. Please treat porters with courtesy, as if they were in fact co-maintainers of your package (which in a way, they are). Please be tolerant of succinct or even unclear bug reports, @@ -2608,7 +2662,7 @@ They should be removed by the `clean' target of Make sure you don't rely on locally installed or hacked configurations or programs. For instance, you should never be calling programs in /usr/local/bin or the like. Try not to rely on programs -be setup in a special way. Try building your package on another +being setup in a special way. Try building your package on another machine, even if it's the same architecture. Don't depend on the package you're building already being installed (a @@ -2623,7 +2677,7 @@ Make sure your debian/rules contains separate ``binary-arch'' and ``binary-indep'' targets, as the Debian Policy Manual requires. Make sure that both targets work independently, that is, that you can call the target without having called the other before. To test this, -try to run dpkg-buildpackage -b. +try to run dpkg-buildpackage -B. @@ -2721,7 +2775,7 @@ 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. Of course, such locations have no official -blessing or status, so buyer, beware. +blessing or status, so buyer beware. @@ -2795,7 +2849,7 @@ called a non-maintainer upload, or NMU. Debian porters, who compile packages for different architectures, occasionally do binary-only NMUs as part of their porting activity (see ). Another reason why NMUs are done is when a -Debian developers needs to fix another developers' packages in order to +Debian developer needs to fix another developer's packages in order to address serious security problems or crippling bugs, especially during the freeze, or when the package maintainer is unable to release a fix in a timely fashion. @@ -2876,12 +2930,12 @@ Make sure that the package's bugs that the NMU is meant to address are all filed in the Debian Bug Tracking System (BTS). If they are not, submit them immediately. -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 +Wait a few days for the response from the maintainer. If you don't get +any response, you may want to help them 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. +maintainer, send them 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. @@ -2909,8 +2963,8 @@ and act later.

The following applies to porters insofar as they are playing the dual role of being both package bug-fixers and package porters. If a -porter has to change the Debian source archive, automatically their -upload is a source NMU and is subject to its rules. If a porter is +porter has to change the Debian source archive, their upload is +automatically a source NMU and is subject to its rules. If a porter is simply uploading a recompiled binary package, the rules are different; see .

@@ -3036,7 +3090,7 @@ In any case, you should not be upset by the NMU. An NMU is not a personal attack against the maintainer. It is a proof that someone cares enough about the package and that they were willing to help you in your work, so you should be thankful. You may also want to -ask them if they would be interested to help you on a more frequent +ask them if they would be interested in helping you on a more frequent basis as co-maintainer or backup maintainer (see ). @@ -3052,12 +3106,13 @@ packages in which a priority of Standard or which are part of the base set have co-maintainers.

Generally there is a primary maintainer and one or more -co-maintainers. The primary maintainer is the whose name is listed in +co-maintainers. The primary maintainer is the person whose name is listed in the Maintainer field of the debian/control file. Co-maintainers are all the other maintainers.

In its most basic form, the process of adding a new co-maintainer is -quite easy: +quite easy: +

Setup the co-maintainer with access to the sources you build the @@ -3081,10 +3136,12 @@ Using the PTS (), the co-maintainers should subscribe themselves to the appropriate source package.

+

+Collaborative maintenance can often be further eased with the use of +tools on Alioth (see ). - Best Packaging Practices

@@ -3163,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 @@ -3221,7 +3278,7 @@ this using an hand-crafted debian/rules file.

The following practices are relevant to the debian/control file. They supplement the .

The description of the package, as defined by the corresponding field @@ -3298,9 +3355,9 @@ or, if the package name itself is a plural (such as package-name are synopsis. -This way of forming a sentance from the package name and synopsis +This way of forming a sentence from the package name and synopsis should be considered as a heuristic and not a strict rule. There are -some cases where it doesn't make sense to try to form a sentance. +some cases where it doesn't make sense to try to form a sentence. @@ -3331,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). + + @@ -3496,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!