X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=91f3f32646f376b5e93cca5546ab3e130827b6e6;hb=43b79fbe2961593b31b41d895f1c323ccfc39500;hp=2749638dff44270226d622ae07432a2f9f846749;hpb=b8bb53a2dc2ebe40322a0f29f174a5076f947d66;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 2749638..91f3f32 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -1,20 +1,20 @@ - %versiondata; + %versiondata; - %commondata; + %commondata; - + - - FIXME: "> + + FIXME: "> ]> @@ -350,14 +350,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 @@ -417,10 +418,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. +

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

-Online archives of mailing lists are available at . +Please read the +for more information. Core development mailing lists

@@ -441,40 +461,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 +481,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

@@ -851,7 +851,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 @@ -927,6 +927,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 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. + + Experimental

The experimental distribution is a special distribution. @@ -1123,60 +1179,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

@@ -1218,12 +1220,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 and associated to 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 +1237,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 +1293,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 +1314,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,9 +1331,9 @@ 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> @@ -1337,7 +1341,7 @@ various commands to pts@qa.debian.org. Accept (+) or refuse (-) mails associated to 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 +1355,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 +1374,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 kind 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 +1440,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 +1451,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 +1477,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

@@ -1662,7 +1682,8 @@ 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 ). - 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 @@ -1701,7 +1722,8 @@ verbose, if necessary) in your changelog entries for uploads to stable, because otherwise the package won't be considered for inclusion. - 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 @@ -1731,6 +1753,10 @@ 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 feature described in , +you'll have to upload to ftp-master. It is the only upload +point that supports delayed incoming. +

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 @@ -1970,15 +1996,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 @@ -2340,13 +2369,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 @@ -2623,7 +2652,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. @@ -3057,7 +3086,8 @@ 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 +3111,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

@@ -3298,9 +3330,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. @@ -3579,7 +3611,7 @@ interaction. This will enable non-interactive installations in the future.

Debconf is a great tool but it is often poorly used. Many common mistakes -are listed in the man page. +are listed in the man page. It is something that you must read if you decide to use debconf. @@ -4042,9 +4074,8 @@ that need to be made. It often takes several rounds of back-and-forth email before the package is in acceptable shape. Being a sponsor means being a mentor.

-Once the package meets Debian standards, build the package with -dpkg-buildpackage -us -uc and sign it -with debsign -m"FULLNAME email-addr" changes-file +Once the package meets Debian standards, build and sign it with +dpkg-buildpackage -kKEY-ID before uploading it to the incoming directory.

The Maintainer field of the control file and the