chiark / gitweb /
no generic mail ids
[developers-reference.git] / developers-reference.sgml
1 <!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
2   <!-- include version information so we don't have to hard code it
3        within the document -->
4   <!ENTITY % versiondata SYSTEM "version.ent"> %versiondata;
5   <!-- common, language independent entities -->
6   <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
7   <!ENTITY % dynamicdata  SYSTEM "dynamic.ent" > %dynamicdata;
8
9   <!-- CVS revision of this document -->
10   <!ENTITY cvs-rev "$Revision: 1.311 $">
11
12   <!-- if you are translating this document, please notate the CVS
13        revision of the original developer's reference in cvs-en-rev -->
14   <!-- <!ENTITY cvs-en-rev "X.YZW"> -->
15
16   <!-- how to mark a section that needs more work -->
17   <!ENTITY FIXME "<em>FIXME:</em>&nbsp;">
18
19 ]>
20 <debiandoc>
21   <book>
22       <title>Debian Developer's Reference
23
24       <author>Developer's Reference Team &email-devel-ref;
25       <author>Andreas Barth
26       <author>Adam Di Carlo
27       <author>Raphaël Hertzog
28       <author>Christian Schwarz
29       <author>Ian Jackson
30       <version>ver. &version;, &date-en;
31
32       <copyright>
33         <copyrightsummary>
34 copyright &copy; 2004&mdash;2006 Andreas Barth</copyrightsummary>
35         <copyrightsummary>
36 copyright &copy; 1998&mdash;2003 Adam Di Carlo</copyrightsummary>
37         <copyrightsummary>
38 copyright &copy; 2002&mdash;2003 Raphaël Hertzog</copyrightsummary>
39         <copyrightsummary>
40 copyright &copy; 1997, 1998 Christian Schwarz</copyrightsummary>
41         <p>
42 This manual is free software; you may redistribute it and/or modify it
43 under the terms of the GNU General Public License as published by the
44 Free Software Foundation; either version 2, or (at your option) any
45 later version.
46         <p>
47 This is distributed in the hope that it will be useful, but
48 <em>without any warranty</em>; without even the implied warranty of
49 merchantability or fitness for a particular purpose.  See the GNU
50 General Public License for more details.
51         <p>
52 A copy of the GNU General Public License is available as &file-GPL; in
53 the &debian-formal; distribution or on the World Wide Web at <url
54 id="&url-gpl;" name="the GNU web site">.  You can also obtain it by
55 writing to the &fsf-addr;.
56
57 <![ %htmltext [
58        <p>
59 If you want to print this reference, you should use the <url
60 id="developers-reference.pdf" name="pdf version">.
61 This page is also available in <url id="index.fr.html" name="French">.
62 ]]>
63
64     <toc detail="sect1">
65
66     <chapt id="scope">Scope of This Document
67       <p>
68 The purpose of this document is to provide an overview of the
69 recommended procedures and the available resources for Debian
70 developers.
71
72 <!-- FIXME: rewrites -->
73       <p>
74 The procedures discussed within include how to become a maintainer
75 (<ref id="new-maintainer">); how to create new packages
76 (<ref id="newpackage">) and how to upload packages (<ref id="upload">);
77 how to handle bug reports (<ref id="bug-handling">); how to move,
78 remove, or orphan packages (<ref id="archive-manip">); how to port
79 packages (<ref id="porting">); and how and when to do interim
80 releases of other maintainers' packages (<ref id="nmu">).
81       <p>
82 The resources discussed in this reference include the mailing lists
83 (<ref id="mailing-lists">) and servers (<ref id="server-machines">); a
84 discussion of the structure of the Debian archive (<ref
85 id="archive">); explanation of the different servers which accept
86 package uploads (<ref id="upload-ftp-master">); and a discussion of
87 resources which can help maintainers with the quality of their
88 packages (<ref id="tools">).
89       <p>
90 It should be clear that this reference does not discuss the technical
91 details of Debian packages nor how to generate them.
92 Nor does this reference detail the standards to which Debian software
93 must comply.  All of such information can be found in the <url
94 id="&url-debian-policy;" name="Debian Policy Manual">.
95       <p>
96 Furthermore, this document is <em>not an expression of formal
97 policy</em>.  It contains documentation for the Debian system and
98 generally agreed-upon best practices.  Thus, it is not what is called a
99 ``normative'' document.
100
101
102     <chapt id="new-maintainer">Applying to Become a Maintainer
103         
104       <sect id="getting-started">Getting started
105         <p>
106 So, you've read all the documentation, you've gone through the <url
107 id="&url-newmaint-guide;" name="Debian New Maintainers' Guide">,
108 understand what everything in the <package>hello</package> example
109 package is for, and you're about to Debianize your favorite piece of
110 software.  How do you actually become a Debian developer so that your
111 work can be incorporated into the Project?
112         <p>
113 Firstly, subscribe to &email-debian-devel; if you haven't already.
114 Send the word <tt>subscribe</tt> in the <em>Subject</em> of an email
115 to &email-debian-devel-req;.  In case of problems, contact the list
116 administrator at &email-listmaster;.  More information on available
117 mailing lists can be found in <ref id="mailing-lists">.
118 &email-debian-devel-announce; is another list which is mandatory
119 for anyone who wishes to follow Debian's development.
120         <p>
121 You should subscribe and lurk (that is, read without posting) for a
122 bit before doing any coding, and you should post about your intentions
123 to work on something to avoid duplicated effort.
124         <p>
125 Another good list to subscribe to is &email-debian-mentors;.  See <ref
126 id="mentors"> for details.  The IRC channel <tt>#debian</tt> can also be
127 helpful; see <ref id="irc-channels">.
128
129         <p>
130 When you know how you want to contribute to &debian-formal;, you
131 should get in contact with existing Debian maintainers who are working
132 on similar tasks.  That way, you can learn from experienced developers.
133 For example, if you are interested in packaging existing software for
134 Debian, you should try to get a sponsor.  A sponsor will work together
135 with you on your package and upload it to the Debian archive once they
136 are happy with the packaging work you have done.  You can find a sponsor
137 by mailing the &email-debian-mentors; mailing list, describing your
138 package and yourself and asking for a sponsor (see <ref id="sponsoring">
139 and <url id="&url-mentors;"> for more information on sponsoring).
140 On the other hand, if you are
141 interested in porting Debian to alternative architectures or kernels
142 you can subscribe to port specific mailing lists and ask there how to
143 get started.  Finally, if you are interested in documentation or
144 Quality Assurance (QA) work you can join maintainers already working on
145 these tasks and submit patches and improvements.
146
147         <p>
148 One pitfall could be a too-generic local part in your mailadress:
149 Terms like mail, admin, root, master should be avoided, please
150 see <url id="http://www.debian.org/MailingLists/"> for details.
151
152
153       <sect id="mentors">Debian mentors and sponsors
154         <p>
155 The mailing list &email-debian-mentors; has been set up for novice
156 maintainers who seek help with initial packaging and other
157 developer-related issues.  Every new developer is invited to subscribe
158 to that list (see <ref id="mailing-lists"> for details).
159         <p>
160 Those who prefer one-on-one help (e.g., via private email) should also
161 post to that list and an experienced developer will volunteer to help.
162         <p>
163 In addition, if you have some packages ready for inclusion in Debian,
164 but are waiting for your new maintainer application to go through, you
165 might be able find a sponsor to upload your package for you.  Sponsors
166 are people who are official Debian Developers, and who are willing to
167 criticize and upload your packages for you.
168 <!-- FIXME - out of order
169 Those who are seeking a
170 sponsor can request one at <url id="&url-sponsors;">.
171 -->
172 Please read the
173 unofficial debian-mentors FAQ at <url id="&url-mentors;"> first.
174         <p>
175 If you wish to be a mentor and/or sponsor, more information is
176 available in <ref id="newmaint">.
177  
178
179       <sect id="registering">Registering as a Debian developer
180         <p>
181 Before you decide to register with &debian-formal;, you will need to
182 read all the information available at the <url id="&url-newmaint;"
183 name="New Maintainer's Corner">.  It describes in detail the
184 preparations you have to do before you can register to become a Debian
185 developer.
186
187 For example, before you apply, you have to read the <url
188 id="&url-social-contract;" name="Debian Social Contract">.
189 Registering as a developer means that you agree with and pledge to
190 uphold the Debian Social Contract; it is very important that
191 maintainers are in accord with the essential ideas behind
192 &debian-formal;.  Reading the <url id="&url-gnu-manifesto;" name="GNU
193 Manifesto"> would also be a good idea.
194         <p>
195 The process of registering as a developer is a process of verifying
196 your identity and intentions, and checking your technical skills.  As
197 the number of people working on &debian-formal; has grown to over
198 &number-of-maintainers; and our systems are used in several
199 very important places, we have to be careful about being compromised.
200 Therefore, we need to verify new maintainers before we can give them
201 accounts on our servers and let them upload packages.
202         <p>
203 Before you actually register you should have shown that you can do
204 competent work and will be a good contributor.
205 You show this by submitting patches through the Bug Tracking System
206 and having a package
207 sponsored by an existing Debian Developer for a while.
208 Also, we expect that
209 contributors are interested in the whole project and not just in
210 maintaining their own packages.  If you can help other maintainers by
211 providing further information on a bug or even a patch, then do so!
212         <p>
213 Registration requires that you are familiar with Debian's philosophy
214 and technical documentation.  Furthermore, you need a GnuPG key which
215 has been signed by an existing Debian maintainer.  If your GnuPG key
216 is not signed yet, you should try to meet a Debian Developer in
217 person to get your key signed.  There's a <url id="&url-gpg-coord;"
218 name="GnuPG Key Signing Coordination page"> which should help you find
219 a Debian Developer close to you. 
220 (If there is no Debian Developer close to you,
221 alternative ways to pass the ID check may be permitted
222 as an absolute exception on a case-by-case-basis.
223 See the <url id="&url-newmaint-id;" name="identification page">
224 for more information.)
225
226         <p>
227 If you do not have an OpenPGP key yet, generate one. Every developer
228 needs an OpenPGP key in order to sign and verify package uploads. You
229 should read the manual for the software you are using, since it has
230 much important information which is critical to its security.  Many
231 more security failures are due to human error than to software failure
232 or high-powered spy techniques.  See <ref id="key-maint"> for more
233 information on maintaining your public key.
234         <p>
235 Debian uses the <prgn>GNU Privacy Guard</prgn> (package
236 <package>gnupg</package> version 1 or better) as its baseline standard.
237 You can use some other implementation of OpenPGP as well.  Note that
238 OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC
239 2440">.
240         <p>
241 You need a version 4 key for use in Debian Development.
242 Your key length must be at least 1024
243 bits; there is no reason to use a smaller key, and doing so would be
244 much less secure.
245 <footnote>Version 4 keys are keys conforming to
246 the OpenPGP standard as defined in RFC 2440.  Version 4 is the key
247 type that has always been created when using GnuPG.  PGP versions
248 since 5.x also could create v4 keys, the other choice having beein
249 pgp 2.6.x compatible v3 keys (also called "legacy RSA" by PGP).
250 <p>
251 Version 4 (primary) keys can either use the RSA or the DSA algorithms,
252 so this has nothing to do with GnuPG's question about "which kind
253 of key do you want: (1) DSA and Elgamal, (2) DSA (sign only), (5)
254 RSA (sign only)".  If you don't have any special requirements just pick
255 the defailt.
256 <p>
257 The easiest way to tell whether an existing key is a v4 key or a v3
258 (or v2) key is to look at the fingerprint:
259 Fingerprints of version 4 keys are the SHA-1 hash of some key matieral,
260 so they are 40 hex digits, usually grouped in blocks of 4.  Fingerprints
261 of older key format versions used MD5 and are generally shown in blocks
262 of 2 hex digits.  For example if your fingerprint looks like
263 <tt>5B00&nbsp;C96D&nbsp;5D54&nbsp;AEE1&nbsp;206B&nbsp;&nbsp;AF84&nbsp;DE7A&nbsp;AF6E&nbsp;94C0&nbsp;9C7F</tt>
264 then it's a v4 key.
265 <p>
266 Another possibility is to pipe the key into <prgn>pgpdump</prgn>,
267 which will say something like "Public Key Packet - Ver 4".
268 <p>
269 Also note that your key must be self-signed (i.e. it has to sign
270 all its own user IDs; this prevents user ID tampering).  All
271 modern OpenPGP software does that automatically, but if you
272 have an older key you may have to manually add those signatures.
273 </footnote>
274         <p>
275 If your public key isn't on a public key server such as &pgp-keyserv;,
276 please read the documentation available at
277 <url id="&url-newmaint-id;" name="NM Step 2: Identification">.
278 That document contains instructions on how to put your key on the
279 public key servers.  The New Maintainer Group will put your public key
280 on the servers if it isn't already there.
281         <p>
282 Some countries restrict the use of cryptographic software by their
283 citizens.  This need not impede one's activities as a Debian package
284 maintainer however, as it may be perfectly legal to use cryptographic
285 products for authentication, rather than encryption purposes.
286 If you live in a country where use of
287 cryptography even for authentication is forbidden
288 then please contact us so we can make special arrangements.
289         <p>
290 To apply as a new maintainer, you need an existing Debian Developer
291 to support your application (an <em>advocate</em>).  After you have
292 contributed to Debian for a while, and you want to apply to become a
293 registered developer, an existing developer with whom you
294 have worked over the past months has to express their belief that you
295 can contribute to Debian successfully.
296         <p>
297 When you have found an advocate, have your GnuPG key signed and have
298 already contributed to Debian for a while, you're ready to apply.
299 You can simply register on our <url id="&url-newmaint-apply;"
300 name="application page">.  After you have signed up, your advocate
301 has to confirm your application.  When your advocate has completed
302 this step you will be assigned an Application Manager who will
303 go with you through the necessary steps of the New Maintainer process.
304 You can always check your status on the <url id="&url-newmaint-db;"
305 name="applications status board">.
306         <p>
307 For more details, please consult <url id="&url-newmaint;" name="New
308 Maintainer's Corner"> at the Debian web site.  Make sure that you
309 are familiar with the necessary steps of the New Maintainer process
310 before actually applying.  If you are well prepared, you can save
311 a lot of time later on.
312
313
314     <chapt id="developer-duties">Debian Developer's Duties
315
316       <sect id="user-maint">Maintaining your Debian information
317         <p>
318 There's a LDAP database containing information about Debian developers at
319 <url id="&url-debian-db;">. You should enter your information there and
320 update it as it changes. Most notably, make sure that the address where your
321 debian.org email gets forwarded to is always up to date, as well as the
322 address where you get your debian-private subscription if you choose to
323 subscribe there.
324         <p>
325 For more information about the database, please see <ref id="devel-db">.
326
327
328
329       <sect id="key-maint">Maintaining your public key
330         <p>
331 Be very careful with your private keys.  Do not place them on any
332 public servers or multiuser machines, such as the Debian servers
333 (see <ref id="server-machines">).  Back your keys up; keep a copy offline.
334 Read the documentation that comes with your software; read the <url
335 id="&url-pgp-faq;" name="PGP FAQ">.
336         <p>
337 You need to ensure not only that your key is secure against being stolen,
338 but also that it is secure against being lost. Generate and make a copy
339 (best also in paper form) of your revocation certificate; this is needed if
340 your key is lost.
341         <p>
342 If you add signatures to your public key, or add user identities, you
343 can update the Debian key ring by sending your key to the key server at
344 <tt>&keyserver-host;</tt>.
345        <p>
346 If you need to add a completely new key or remove an old key, you need
347 to get the new key signed by another developer. 
348 If the old key is compromised or invalid, you
349 also have to add the revocation certificate. If there is no real
350 reason for a new key, the Keyring Maintainers might reject the new key.
351 Details can be found at 
352 <url id="http://keyring.debian.org/replacing_keys.html">.
353        <p>
354 The same key extraction routines discussed in <ref id="registering">
355 apply. 
356         <p>
357 You can find a more in-depth discussion of Debian key maintenance in
358 the documentation of the <package>debian-keyring</package> package.
359
360
361        <sect id="voting">Voting
362         <p>
363 Even though Debian isn't really a democracy, we use a democratic
364 process to elect our leaders and to approve general resolutions.
365 These procedures are defined by the
366 <url id="&url-constitution;" name="Debian Constitution">.
367         <p>
368 Other than the yearly leader election, votes are not routinely held, and
369 they are not undertaken lightly. Each proposal is first discussed on
370 the &email-debian-vote; mailing list and it requires several endorsements
371 before the project secretary starts the voting procedure.
372         <p>
373 You don't have to track the pre-vote discussions, as the secretary will
374 issue several calls for votes on &email-debian-devel-announce; (and all
375 developers are expected to be subscribed to that list). Democracy doesn't
376 work well if people don't take part in the vote, which is why we encourage
377 all developers to vote. Voting is conducted via GPG-signed/encrypted email
378 messages.
379         <p>
380 The list of all proposals (past and current) is available on the
381 <url id="&url-vote;" name="Debian Voting Information"> page, along with
382 information on how to make, second and vote on proposals.
383
384
385       <sect id="inform-vacation">Going on vacation gracefully
386         <p>
387 It is common for developers to have periods of absence, whether those are
388 planned vacations or simply being buried in other work. The important thing
389 to notice is that other developers need to know that you're on vacation
390 so that they can do whatever is needed if a problem occurs with your
391 packages or other duties in the project.
392         <p>
393 Usually this means that other developers are allowed to NMU (see
394 <ref id="nmu">) your package if a big problem (release critical bug,
395 security update, etc.) occurs while you're on vacation. Sometimes it's
396 nothing as critical as that, but it's still appropriate to let others
397 know that you're unavailable.
398         <p>
399 In order to inform the other developers, there are two things that you should do.
400 First send a mail to &email-debian-private; with "[VAC] " prepended to the
401 subject of your message<footnote>This is so that the message can be easily
402 filtered by people who don't want to read vacation notices.</footnote>
403 and state the period of time when you will be on vacation. You can also give
404 some special instructions on what to do if a problem occurs.
405         <p>
406 The other thing to do is to mark yourself as "on vacation" in the
407 <qref id="devel-db">Debian developers' LDAP database</qref> (this
408 information is only accessible to Debian developers).
409 Don't forget to remove the "on vacation" flag when you come back!
410         <p>
411 Ideally, you should sign up at the
412 <url id="http://nm.debian.org/gpg.php" name="GPG coordination site">
413 when booking a holiday and check if anyone there is looking for signing.
414 This is especially important when people go to exotic places
415 where we don't have any developers yet but
416 where there are people who are interested in applying.
417
418
419       <sect id="upstream-coordination">Coordination with upstream developers
420         <p>
421 A big part of your job as Debian maintainer will be to stay in contact
422 with the upstream developers.  Debian users will sometimes report bugs
423 that are not specific to Debian to our bug tracking system.  You
424 have to forward these bug reports to the upstream developers so that
425 they can be fixed in a future upstream release.
426         <p>
427 While it's not your job to fix non-Debian specific bugs, you may freely
428 do so if you're able. When you make such fixes, be sure to pass them on
429 to the upstream maintainers as well. Debian users and developers will
430 sometimes submit patches to fix upstream bugs &mdash; you should evaluate
431 and forward these patches upstream.
432         <p>
433 If you need to modify the upstream sources in order to build a policy
434 compliant package, then you should propose a nice fix to the upstream
435 developers which can be included there, so that you won't have to
436 modify the sources of the next upstream version. Whatever changes you
437 need, always try not to fork from the upstream sources.
438
439
440       <sect id="rc-bugs">Managing release-critical bugs
441         <p>
442 Generally you should deal with bug reports on your packages as described in
443 <ref id="bug-handling">. However, there's a special category of bugs that
444 you need to take care of &mdash; the so-called release-critical bugs (RC bugs).
445 All bug reports that have severity <em>critical</em>, <em>grave</em> or
446 <em>serious</em> are considered to have an impact on whether the package can
447 be released in the next stable release of Debian.
448 These bugs can delay the Debian release
449 and/or can justify the removal of a package at freeze time. That's why
450 these bugs need to be corrected as quickly as possible.
451         <p>
452 Developers who are part of the <url id="&url-debian-qa;"
453 name="Quality Assurance"> group are following all such bugs, and trying
454 to help whenever possible. If, for any reason, you aren't able fix an
455 RC bug in a package of yours within 2 weeks, you should either ask for help
456 by sending a mail to the Quality Assurance (QA) group
457 &email-debian-qa;, or explain your difficulties and present a plan to fix
458 them by sending a mail to the bug report. Otherwise, people
459 from the QA group may want to do a Non-Maintainer Upload (see
460 <ref id="nmu">) after trying to contact you (they might not wait as long as
461 usual before they do their NMU if they have seen no recent activity from you
462 in the BTS).
463
464
465       <sect>Retiring
466         <p>
467 If you choose to leave the Debian project, you should make sure you do
468 the following steps:
469 <enumlist>
470             <item>
471 Orphan all your packages, as described in <ref id="orphaning">.
472             <item>
473 Send an gpg-signed email about why you are leaving the project to
474 &email-debian-private;.
475             <item>
476 Notify the Debian key ring maintainers that you are leaving by
477 emailing to &email-debian-keyring;.
478 </enumlist>
479
480
481
482    <chapt id="resources">Resources for Debian Developers
483      <p>
484 In this chapter you will find a very brief road map of the Debian
485 mailing lists, the Debian machines
486 which may be available to you as a developer, and all the other
487 resources that are available to help you in your maintainer work.
488
489       <sect id="mailing-lists">Mailing lists
490         <p>
491 Much of the conversation between Debian developers (and users) is managed
492 through a wide array of mailing lists we host at
493 <tt><url id="http://&lists-host;/" name="&lists-host;"></tt>.
494 To find out more on how to subscribe or unsubscribe, how to post and how not
495 to post, where to find old posts and how to search them, how to contact the
496 list maintainers and see various other information about the mailing lists,
497 please read <url id="&url-debian-lists;">. This section will only cover
498 aspects of mailing lists that are of particular interest to developers.
499
500         <sect1 id="mailing-lists-rules">Basic rules for use
501         <p>
502 When replying to messages on the mailing list, please do not send a
503 carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
504 request to be copied.  Anyone who posts to a mailing list should read
505 it to see the responses.
506         <p>
507 Cross-posting (sending the same message to multiple lists) is discouraged.
508 As ever on the net, please trim down the quoting of articles you're
509 replying to.  In general, please adhere to the usual conventions for
510 posting messages.
511         <p>
512 Please read the <url name="code of conduct" id="&url-debian-lists;#codeofconduct">
513 for more information.
514
515         <sect1 id="core-devel-mailing-lists">Core development mailing lists
516         <p>
517 The core Debian mailing lists that developers should use are:
518 <list>
519   <item>&email-debian-devel-announce;, used to announce important things to
520         developers.
521         All developers are expected to be subscribed to this list.
522   </item>
523   <item>&email-debian-devel;, used to discuss various development related
524         technical issues.
525   </item>
526   <item>&email-debian-policy;, where the Debian Policy is discussed and
527         voted on.
528   </item>
529   <item>&email-debian-project;, used to discuss various non-technical
530         issues related to the project.
531   </item>
532 </list>
533         <p>
534 There are other mailing lists available for a variety of special topics;
535 see <url id="http://&lists-host;/"> for a list.
536
537         <sect1 id="mailing-lists-special">Special lists
538         <p>
539 &email-debian-private; is a special mailing list for private
540 discussions amongst Debian developers.  It is meant to be used for
541 posts which for whatever reason should not be published publicly.
542 As such, it is a low volume list, and users are urged not to use
543 &email-debian-private; unless it is really necessary.  Moreover, do
544 <em>not</em> forward email from that list to anyone.  Archives of this
545 list are not available on the web for obvious reasons, but you can see
546 them using your shell account on <tt>lists.debian.org</tt> and looking
547 in the <file>~debian/archive/debian-private</file> directory.
548         <p>
549 &email-debian-email; is a special mailing list used as a grab-bag 
550 for Debian related correspondence such as contacting upstream authors
551 about licenses, bugs, etc. or discussing the project with others where it
552 might be useful to have the discussion archived somewhere.
553
554         <sect1 id="mailing-lists-new">Requesting new development-related lists
555         <p>
556 Before requesting a mailing list that relates to the development of a
557 package (or a small group of related packages), please consider if using
558 an alias (via a .forward-aliasname file on master.debian.org, which
559 translates into a reasonably nice <var>you-aliasname@debian.org</var>
560 address) or a self-managed mailing list on <qref id="alioth">Alioth</qref>
561 is more appropriate.
562         <p>
563 If you decide that a regular mailing list on lists.debian.org is really what
564 you want, go ahead and fill in a request, following <url name="the HOWTO"
565 id="&url-debian-lists-new;">.
566
567       <sect id="irc-channels">IRC channels
568         <p>
569 Several IRC channels are dedicated to Debian's development. They are mainly
570 hosted on the <url id="&url-oftc;" name="Open and free technology community
571 (OFTC)"> network.  The <tt>irc.debian.org</tt> DNS entry is an alias to
572 <tt>irc.oftc.net</tt>.
573         <p>
574 The main channel for Debian in general is <em>#debian</em>. This is a large,
575 general-purpose channel where users can find recent news in the topic and
576 served by bots. <em>#debian</em> is for English speakers; there are also
577 <em>#debian.de</em>, <em>#debian-fr</em>, <em>#debian-br</em> and other
578 similarly named channels for speakers of other languages.
579         <p>
580 The main channel for Debian development is <em>#debian-devel</em>.
581 It is a very active channel since usually over 150 people are always
582 logged in. It's a channel for people who work
583 on Debian, it's not a support channel (there's <em>#debian</em> for that).
584 It is however open to anyone who wants to lurk (and learn). Its topic is
585 commonly full of interesting information for developers.
586         <p>
587 Since <em>#debian-devel</em> is an open channel, you
588 should not speak there of issues that are discussed in
589 &email-debian-private;. There's another channel for this purpose,
590 it's called <em>#debian-private</em> and it's protected by a key.
591 This key is available in the archives of debian-private in
592 <file>master.debian.org:&file-debian-private-archive;</file>,
593 just <prgn>zgrep</prgn> for <em>#debian-private</em> in
594 all the files.
595         <p>
596 There are other additional channels dedicated to specific subjects.
597 <em>#debian-bugs</em> is used for coordinating bug squashing parties.
598 <em>#debian-boot</em> is used to coordinate the work on the debian-installer.
599 <em>#debian-doc</em> is
600 occasionally used to talk about documentation, like the document you are
601 reading. Other channels are dedicated to an architecture or a set of
602 packages: <em>#debian-bsd</em>, <em>#debian-kde</em>, <em>#debian-jr</em>,
603 <em>#debian-edu</em>,
604 <em>#debian-sf</em> (SourceForge package), <em>#debian-oo</em> (OpenOffice
605 package) ...
606         <p>
607 Some non-English developers' channels exist as well, for example
608 <em>#debian-devel-fr</em> for
609 French speaking people interested in Debian's development.
610         <p>
611 Channels dedicated to Debian also exist on other IRC networks, notably on
612 the <url id="&url-openprojects;" name="freenode"> IRC network, which was 
613 pointed at by the <tt>irc.debian.org</tt> alias until 4th June 2006.
614         <p>
615 To get a cloak on freenode, you send J&ouml;rg Jaspert &lt;joerg@debian.org&gt;
616 a signed mail where you tell what your nick is.
617 Put "cloak" somewhere in the Subject: header.
618 The nick should be registered:
619 <url id="http://freenode.net/faq.shtml#nicksetup" name="Nick Setup Page">.
620 The mail needs to be signed by a key in the Debian keyring.
621 Please see
622 <url id="http://freenode.net/faq.shtml#projectcloak" name="Freenodes documentation">
623 for more information about cloaks.
624
625
626       <sect id="doc-rsrcs">Documentation
627         <p>
628 This document contains a lot of information
629 which is useful to Debian developers,
630 but it cannot contain everything. Most of the other interesting documents
631 are linked from <url id="&url-devel-docs;" name="The Developers' Corner">.
632 Take the time to browse all the links, you will learn many more things.
633
634
635       <sect id="server-machines">Debian machines
636         <p>
637 Debian has several computers working as servers, most of which serve
638 critical functions in the Debian project. Most of the machines are used
639 for porting activities, and they all have a permanent connection to the
640 Internet.
641         <p>
642 Most of the machines are available for individual developers to use,
643 as long as the developers follow the rules set forth in the
644 <url name="Debian Machine Usage Policies" id="&url-dmup;">.
645         <p>
646 Generally speaking, you can use these machines for Debian-related purposes
647 as you see fit.  Please be kind to system administrators, and do not use
648 up tons and tons of disk space, network bandwidth, or CPU without first
649 getting the approval of the system administrators.  Usually these machines are run by
650 volunteers.
651         <p>
652 Please take care to protect your Debian passwords and SSH keys installed on
653 Debian machines. Avoid login or upload methods which send passwords over
654 the Internet in the clear, such as telnet, FTP, POP etc.
655         <p>
656 Please do not put any material that doesn't relate to Debian on the Debian
657 servers, unless you have prior permission.
658         <p>
659 The current list of Debian machines is available at
660 <url id="&url-devel-machines;">. That web page contains machine names,
661 contact information, information about who can log in, SSH keys etc.
662         <p>
663 If you have a problem with the operation of a Debian server, and you
664 think that the system operators need to be notified of this problem,
665 the Debian system administrator team is reachable at
666 <email>debian-admin@lists.debian.org</email>.
667         <p>
668 If you have a problem with a certain service, not related to the system
669 administration (such as packages to be removed from the archive,
670 suggestions for the web site, etc.),
671 generally you'll report a bug against a ``pseudo-package''.  See <ref
672 id="submit-bug"> for information on how to submit bugs.
673         <p>
674 Some of the core servers are restricted, but the information from there
675 is mirrored to another server.
676
677       <sect1 id="servers-bugs">The bugs server
678         <p>
679 <tt>&bugs-host;</tt> is the canonical location for the Bug Tracking
680 System (BTS).
681         <p>
682 It is restricted; a mirror is available on <tt>merkel</tt>.
683         <p>
684 If you plan on doing some statistical analysis or
685 processing of Debian bugs, this would be the place to do it.  Please
686 describe your plans on &email-debian-devel; before implementing
687 anything, however, to reduce unnecessary duplication of effort or
688 wasted processing time.
689
690       <sect1 id="servers-ftp-master">The ftp-master server
691         <p>
692 The <tt>ftp-master.debian.org</tt> server holds the canonical copy of the Debian
693 archive (excluding the non-US packages). Generally, package uploads
694 go to this server; see <ref id="upload">.
695         <p>
696 It is restricted; a mirror is available on <tt>merkel</tt>.
697         <p>
698 Problems with the Debian FTP archive generally need to be reported as
699 bugs against the <package>ftp.debian.org</package> pseudo-package or
700 an email to &email-ftpmaster;, but also see the procedures in
701 <ref id="archive-manip">.
702
703       <sect1 id="servers-non-us">The non-US server
704         <p>
705 The non-US server <tt>non-us.debian.org</tt>
706 was discontinued with the release of sarge. The pseudo-package
707 <package>nonus.debian.org</package>
708 still exists for now.
709
710       <sect1 id="servers-www">The www-master server
711         <p>
712 The main web server is <tt>www-master.debian.org</tt>.
713 It holds the official web pages, the face
714 of Debian for most newbies.
715         <p>
716 If you find a problem with the Debian web server, you should generally
717 submit a bug against the pseudo-package,
718 <package>www.debian.org</package>. Remember to check whether or not someone
719 else has already reported the problem to the
720 <url id="http://&bugs-host;/www.debian.org" name="Bug Tracking System">.
721
722       <sect1 id="servers-people">The people web server
723         <p>
724 <tt>people.debian.org</tt> is the server used
725 for developers' own web pages about anything related to Debian.
726         <p>
727 If you have some Debian-specific information which you want to serve
728 on the web, you can do this by putting material in the
729 <file>public_html</file> directory under your home directory on
730 <tt>people.debian.org</tt>.
731 This will be accessible at the URL
732 <tt>http://people.debian.org/~<var>your-user-id</var>/</tt>.
733         <p>
734 You should only use this particular location because it will be backed up,
735 whereas on other hosts it won't.
736         <p>
737 Usually the only reason to use a different host is when you need to publish
738 materials subject to the U.S. export restrictions, in which case you can use
739 one of the other servers located outside the United States.
740         <p>
741 Send mail to &email-debian-devel; if you have any questions.
742
743       <sect1 id="servers-cvs">The CVS server
744 <!-- TODO: document svn.debian.org, arch.debian.org also -->
745         <p>
746 Our CVS server is located on <tt>cvs.debian.org</tt>.
747         <p>
748 If you need to use a publicly accessible CVS
749 server, for instance, to help coordinate work on a package between
750 many different developers, you can request a CVS area on the server.
751           <p>
752 Generally, <tt>cvs.debian.org</tt> offers a combination of local CVS
753 access, anonymous client-server read-only access, and full
754 client-server access through <prgn>ssh</prgn>.  Also, the CVS area can
755 be accessed read-only via the Web at <url id="&url-cvsweb;">.
756         <p>
757 To request a CVS area, send a request via email to
758 &email-debian-admin;.  Include the name of the requested CVS area,
759 the Debian account that should own the CVS root area, and why you need it.
760
761       <sect1 id="dchroot">chroots to different distributions
762         <p>
763 On some machines, there are chroots to different distributions available.
764 You can use them like this:
765
766 <example>
767 vore% dchroot unstable
768 Executing shell in chroot: /org/vore.debian.org/chroots/user/unstable
769 </example>
770
771 In all chroots, the normal user home directories are available.
772 You can find out which chroots are available via
773 <tt>&url-devel-machines;</tt>.
774
775
776     <sect id="devel-db">The Developers Database
777         <p>
778 The Developers Database, at <url id="&url-debian-db;">, is an LDAP
779 directory for managing Debian developer attributes.  You can use this
780 resource to search the list of Debian developers.
781 Part of this information is also available through
782 the finger service on Debian servers, try
783 <prgn>finger yourlogin@db.debian.org</prgn> to see what it reports.
784         <p>
785 Developers can <url name="log into the database" id="&url-debian-db-login;">
786 to change various information about themselves, such as:
787 <list>
788         <item>forwarding address for your debian.org email
789         <item>subscription to debian-private
790         <item>whether you are on vacation
791         <item>personal information such as your address, country,
792               the latitude and longitude of the place where you live
793               for use in <url name="the world map of Debian developers"
794               id="&url-worldmap;">, phone and fax numbers, IRC nickname
795               and web page
796         <item>password and preferred shell on Debian Project machines
797 </list>
798         <p>
799 Most of the information is not accessible to the public, naturally.
800 For more information please read the online documentation that you can find
801 at <url id="&url-debian-db-doc;">.
802         <p>
803 Developers can also submit their SSH keys to be used for authorization on the
804 official Debian machines, and even add new *.debian.net DNS entries.
805 Those features are documented at <url id="&url-debian-db-mail-gw;">.
806
807
808     <sect id="archive">The Debian archive
809         <p>
810 The &debian-formal; distribution consists of a lot of packages
811 (<file>.deb</file>'s, currently around &number-of-pkgs;) and a few
812 additional files (such as documentation and installation disk images).
813         <p>
814 Here is an example directory tree of a complete Debian archive:
815         <p>
816 &sample-dist-dirtree;
817         <p>
818 As you can see, the top-level directory contains two directories,
819 <file>dists/</file> and <file>pool/</file>. The latter is a &ldquo;pool&rdquo; in which the
820 packages actually are, and which is handled by the archive maintenance
821 database and the accompanying programs. The former contains the
822 distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>.
823 The <file>Packages</file> and <file>Sources</file> files in the
824 distribution subdirectories can reference files in the <file>pool/</file>
825 directory. The directory tree below each of the distributions is arranged
826 in an identical manner.  What we describe below for <em>stable</em> is
827 equally applicable to the <em>unstable</em> and <em>testing</em>
828 distributions. 
829         <p>
830 <file>dists/stable</file> contains three directories, namely <file>main</file>,
831 <file>contrib</file>, and <file>non-free</file>. 
832         <p>
833 In each of the areas, there is a directory for the source packages
834 (<file>source</file>) and a directory for each supported architecture
835 (<file>binary-i386</file>, <file>binary-m68k</file>, etc.).
836         <p>
837 The <file>main</file> area contains additional directories which hold
838 the disk images and some essential pieces of documentation required
839 for installing the Debian distribution on a specific architecture
840 (<file>disks-i386</file>, <file>disks-m68k</file>, etc.).
841
842
843       <sect1 id="archive-sections">Sections
844         <p>
845 The <em>main</em> section of the Debian archive is what makes up the
846 <strong>official &debian-formal; distribution</strong>.  The
847 <em>main</em> section is official because it fully complies with all
848 our guidelines.  The other two sections do not, to different degrees;
849 as such, they are <strong>not</strong> officially part of
850 &debian-formal;.
851         <p>
852 Every package in the main section must fully comply with the <url
853 id="&url-dfsg;" name="Debian Free Software Guidelines"> (DFSG) and
854 with all other policy requirements as described in the <url
855 id="&url-debian-policy;" name="Debian Policy Manual">.  The DFSG is
856 our definition of &ldquo;free software.&rdquo;  Check out the Debian Policy
857 Manual for details.
858         <p>
859 Packages in the <em>contrib</em> section have to comply with the DFSG,
860 but may fail other requirements.  For instance, they may depend on
861 non-free packages.
862         <p>
863 Packages which do not conform to the DFSG are placed in the
864 <em>non-free</em> section. These packages are not considered as part
865 of the Debian distribution, though we support their use, and we
866 provide infrastructure (such as our bug-tracking system and mailing
867 lists) for non-free software packages.
868         <p>
869 The <url id="&url-debian-policy;" name="Debian Policy Manual">
870 contains a more exact definition of the three sections. The above
871 discussion is just an introduction.
872         <p>
873 The separation of the three sections at the top-level of the archive
874 is important for all people who want to distribute Debian, either via
875 FTP servers on the Internet or on CD-ROMs: by distributing only the
876 <em>main</em> and <em>contrib</em> sections, one can avoid any legal
877 risks.  Some packages in the <em>non-free</em> section do not allow
878 commercial distribution, for example.
879         <p>
880 On the other hand, a CD-ROM vendor could easily check the individual
881 package licenses of the packages in <em>non-free</em> and include as
882 many on the CD-ROMs as it's allowed to. (Since this varies greatly from
883 vendor to vendor, this job can't be done by the Debian developers.)
884         <p>
885 Note that the term "section" is also used to refer to categories
886 which simplify the organization and browsing of available packages, e.g.
887 <em>admin</em>, <em>net</em>, <em>utils</em> etc. Once upon a time, these
888 sections (subsections, rather) existed in the form of subdirectories within
889 the Debian archive. Nowadays, these exist only in the "Section" header
890 fields of packages.
891
892
893       <sect1>Architectures
894         <p>
895 In the first days, the Linux kernel was only available for Intel
896 i386 (or greater) platforms, and so was Debian. But as Linux became
897 more and more popular, the kernel was ported to other architectures,
898 too.
899         <p>
900 The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola
901 680x0 (like Atari, Amiga and Macintoshes), MIPS, and PowerPC.  The
902 Linux 2.2 kernel supports even more architectures, including ARM and
903 UltraSPARC.  Since Linux supports these platforms, Debian decided that
904 it should, too.  Therefore, Debian has ports underway; in fact, we
905 also have ports underway to non-Linux kernels.  Aside from
906 <em>i386</em> (our name for Intel x86), there is <em>m68k</em>,
907 <em>alpha</em>, <em>powerpc</em>, <em>sparc</em>, <em>hurd-i386</em>,
908 <em>arm</em>, <em>ia64</em>, <em>hppa</em>, <em>s390</em>, <em>mips</em>,
909 <em>mipsel</em> and <em>sh</em> as of this writing.
910         <p>
911 &debian-formal; 1.3 is only available as <em>i386</em>.  Debian 2.0
912 shipped for <em>i386</em> and <em>m68k</em> architectures.  Debian 2.1
913 ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and
914 <em>sparc</em> architectures.  Debian 2.2 added support for the
915 <em>powerpc</em> and <em>arm</em> architectures. Debian 3.0 added
916 support of five new architectures: <em>ia64</em>, <em>hppa</em>,
917 <em>s390</em>, <em>mips</em> and <em>mipsel</em>.
918         <p>
919 Information for developers and users about the specific ports are
920 available at the <url id="&url-debian-ports;" name="Debian Ports web
921 pages">.
922
923
924
925       <sect1>Packages
926         <p>
927 There are two types of Debian packages, namely <em>source</em> and
928 <em>binary</em> packages.
929         <p>
930 Source packages consist of either two or three files: a <file>.dsc</file>
931 file, and either a <file>.tar.gz</file> file or both an
932 <file>.orig.tar.gz</file> and a <file>.diff.gz</file> file.
933         <p>
934 If a package is developed specially for Debian and is not distributed
935 outside of Debian, there is just one <file>.tar.gz</file> file which
936 contains the sources of the program.  If a package is distributed
937 elsewhere too, the <file>.orig.tar.gz</file> file stores the so-called
938 <em>upstream source code</em>, that is the source code that's
939 distributed by the <em>upstream maintainer</em> (often the author of
940 the software). In this case, the <file>.diff.gz</file> contains the
941 changes made by the Debian maintainer.
942         <p>
943 The <file>.dsc</file> file lists all the files in the source package together
944 with checksums (<prgn>md5sums</prgn>) and some additional info about
945 the package (maintainer, version, etc.).
946
947
948       <sect1>Distributions
949         <p>
950 The directory system described in the previous chapter is itself
951 contained within <em>distribution directories</em>.  Each
952 distribution is actually contained in the <file>pool</file> directory in the
953 top-level of the Debian archive itself.
954         <p>
955 To summarize, the Debian archive has a root directory within an FTP
956 server.  For instance, at the mirror site,
957 <ftpsite>ftp.us.debian.org</ftpsite>, the Debian archive itself is
958 contained in <ftppath>/debian</ftppath>, which is a common location
959 (another is <file>/pub/debian</file>).
960         <p>
961 A distribution comprises Debian source and binary packages, and the
962 respective <file>Sources</file> and <file>Packages</file> index files, containing
963 the header information from all those packages. The former are kept in the
964 <file>pool/</file> directory, while the latter are kept in the <file>dists/</file>
965 directory of the archive (for backwards compatibility).
966
967
968         <sect2 id="sec-dists">Stable, testing, and unstable
969         <p>
970 There are always distributions called <em>stable</em> (residing in
971 <file>dists/stable</file>), <em>testing</em> (residing in
972 <file>dists/testing</file>), and <em>unstable</em> (residing in
973 <file>dists/unstable</file>). This reflects the development process of the
974 Debian project.
975         <p>
976 Active development is done in the <em>unstable</em> distribution
977 (that's why this distribution is sometimes called the <em>development
978 distribution</em>). Every Debian developer can update his or her
979 packages in this distribution at any time. Thus, the contents of this
980 distribution change from day to day. Since no special effort is made
981 to make sure everything in this distribution is working properly, it is
982 sometimes literally unstable.
983         <p>
984 The <qref id="testing">"testing"</qref> distribution is generated
985 automatically by taking
986 packages from unstable if they satisfy certain criteria. Those
987 criteria should ensure a good quality for packages within testing.
988 The update to testing is launched each day after the
989 new packages have been installed. See <ref id="testing">.
990         <p>
991 After a period of development, once the release manager deems fit, the
992 <em>testing</em> distribution is frozen, meaning that the policies
993 which control how packages move from <em>unstable</em> to <em>testing</em> are
994 tightened.  Packages which are too buggy are removed.  No changes are
995 allowed into <em>testing</em> except for bug fixes.  After some time
996 has elapsed, depending on progress, the <em>testing</em> distribution
997 is frozen even further.
998 Details of the handling of the testing distribution are published
999 by the Release Team on debian-devel-announce.
1000 After the open issues are solved to the satisfaction of the Release Team,
1001 the distribution is released.
1002 Releasing means
1003 that <em>testing</em> is renamed to <em>stable</em>,
1004 and a new copy is created for the new <em>testing</em>,
1005 and the previous <em>stable</em> is renamed to <em>oldstable</em>
1006 and stays there until it is finally archived.
1007 On archiving, the contents are moved to <tt>&archive-host;</tt>).
1008         <p>
1009 This development cycle is based on the assumption that the
1010 <em>unstable</em> distribution becomes <em>stable</em> after passing a
1011 period of being in <em>testing</em>.  Even once a distribution is
1012 considered stable, a few bugs inevitably remain &mdash; that's why the
1013 stable distribution is updated every now and then. However, these
1014 updates are tested very carefully and have to be introduced into the
1015 archive individually to reduce the risk of introducing new bugs.  You
1016 can find proposed additions to <em>stable</em> in the
1017 <file>proposed-updates</file> directory.  Those packages in
1018 <file>proposed-updates</file> that pass muster are periodically moved as a
1019 batch into the stable distribution and the revision level of the
1020 stable distribution is incremented (e.g., &lsquo;3.0&rsquo; becomes
1021 &lsquo;3.0r1&rsquo;, &lsquo;2.2r4&rsquo; becomes &lsquo;2.2r5&rsquo;, and
1022 so forth).
1023 Please refer to
1024 <qref id="upload-stable">uploads to the <em>stable</em> distribution</qref>
1025 for details.
1026         <p>
1027 Note that development under <em>unstable</em> continues during the
1028 freeze period, since the <em>unstable</em> distribution remains in
1029 place in parallel with <em>testing</em>.
1030
1031     <sect2>
1032         <heading>More information about the testing distribution</heading>
1033         <p>
1034 Packages are usually installed into the `testing' distribution after they
1035 have undergone some degree of testing in unstable.
1036         <p>
1037 For more details, please see the <qref id="testing">information about the
1038 testing distribution</qref>.
1039
1040         <sect2 id="experimental">Experimental
1041           <p>
1042 The <em>experimental</em> distribution is a special distribution.
1043 It is not a full distribution in the same sense as `stable' and
1044 `unstable' are.  Instead, it is meant to be a temporary staging area
1045 for highly experimental software where there's a good chance that the
1046 software could break your system, or software that's just too unstable
1047 even for the <em>unstable</em> distribution (but there is a reason to
1048 package it nevertheless).  Users who download and install
1049 packages from <em>experimental</em> are expected to have been duly
1050 warned.  In short, all bets are off for the <em>experimental</em>
1051 distribution.
1052           <p>
1053 These are the <manref name="sources.list" section="5"> lines for
1054 <em>experimental</em>:
1055 <example>
1056 deb http://ftp.<var>xy</var>.debian.org/debian/ experimental main
1057 deb-src http://ftp.<var>xy</var>.debian.org/debian/ experimental main
1058 </example>
1059           <p>
1060 If there is a chance that the software could do grave damage to a system,
1061 it is likely to be better to put it into <em>experimental</em>.
1062 For instance, an experimental compressed file system should probably go
1063 into <em>experimental</em>.
1064           <p>
1065 Whenever there is a new upstream version of a package that introduces new
1066 features but breaks a lot of old ones, it should either not be uploaded, or
1067 be uploaded to <em>experimental</em>. A new, beta, version of some software
1068 which uses a completely different configuration can go into
1069 <em>experimental</em>, at the maintainer's discretion. If you are working
1070 on an incompatible or complex upgrade situation, you can also use
1071 <em>experimental</em> as a staging area, so that testers can get early
1072 access.
1073           <p>
1074 Some experimental software can still go into <em>unstable</em>, with a few
1075 warnings in the description, but that isn't recommended because packages
1076 from <em>unstable</em> are expected to propagate to <em>testing</em> and
1077 thus to <em>stable</em>. You should not be afraid to use
1078 <em>experimental</em> since it does not cause any pain to the ftpmasters,
1079 the experimental packages are automatically removed once you upload
1080 the package in <em>unstable</em> with a higher version number.
1081           <p>
1082 New software which isn't likely to damage your system can go directly into
1083 <em>unstable</em>.
1084           <p>
1085 An alternative to <em>experimental</em> is to use your personal web space
1086 on <tt>people.debian.org</tt>.
1087           <p>
1088 When uploading to unstable a package which had bugs fixed in experimental,
1089 please consider using the option <tt>-v</tt> to <prgn>dpkg-buildpackage</prgn>
1090 to finally get them closed.
1091
1092       <sect1 id="codenames">Release code names
1093         <p>
1094 Every released Debian distribution has a <em>code name</em>: Debian
1095 1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0,
1096 `hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; Debian 3.0, `woody';
1097 Debian 3.1, "sarge";
1098 Debian 4.0, "etch".  
1099 There is also a ``pseudo-distribution'', called `sid', which is the current
1100 `unstable' distribution; since packages are moved from `unstable' to
1101 `testing' as they approach stability, `sid' itself is never released.
1102 As well as the usual contents of a Debian distribution, `sid' contains
1103 packages for architectures which are not yet officially supported or
1104 released by Debian.  These architectures are planned to be integrated
1105 into the mainstream distribution at some future date.
1106         <p>
1107 Since Debian has an open development model (i.e., everyone can
1108 participate and follow the development) even the `unstable' and `testing'
1109 distributions are distributed to the Internet through the Debian FTP and
1110 HTTP server network. Thus, if we had called the directory which contains
1111 the release candidate version `testing', then we would have to rename it
1112 to `stable' when the version is released, which would cause all FTP
1113 mirrors to re-retrieve the whole distribution (which is quite large).
1114         <p>
1115 On the other hand, if we called the distribution directories
1116 <em>Debian-x.y</em> from the beginning, people would think that Debian
1117 release <em>x.y</em> is available. (This happened in the past, where a
1118 CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development
1119 version. That's the reason why the first official Debian release was
1120 1.1, and not 1.0.)
1121         <p>
1122 Thus, the names of the distribution directories in the archive are
1123 determined by their code names and not their release status (e.g.,
1124 `slink').  These names stay the same during the development period and
1125 after the release; symbolic links, which can be changed easily,
1126 indicate the currently released stable distribution.  That's why the
1127 real distribution directories use the <em>code names</em>, while
1128 symbolic links for <em>stable</em>, <em>testing</em>, and
1129 <em>unstable</em> point to the appropriate release directories.
1130
1131
1132     <sect id="mirrors">Debian mirrors
1133         <p>
1134 The various download archives and the web site have several mirrors
1135 available in order to relieve our canonical servers from heavy load.
1136 In fact, some of the canonical servers aren't public &mdash; a first tier
1137 of mirrors balances the load instead. That way, users always access
1138 the mirrors and get used to using them, which allows Debian to better
1139 spread its bandwidth requirements over several servers and networks,
1140 and basically makes users avoid hammering on one primary location.
1141 Note that the first tier of mirrors is as up-to-date as it can be since
1142 they update when triggered from the internal sites (we call this
1143 "push mirroring").
1144         <p>
1145 All the information on Debian mirrors, including a list of the available
1146 public FTP/HTTP servers, can be found at <url id="&url-debian-mirrors;">.
1147 This useful page also includes information and tools which can be helpful if
1148 you are interested in setting up your own mirror, either for internal or
1149 public access.
1150         <p>
1151 Note that mirrors are generally run by third-parties who are
1152 interested in helping Debian.  As such, developers generally do not
1153 have accounts on these machines.
1154
1155
1156     <sect id="incoming-system">
1157         <heading>The Incoming system
1158         <p>
1159 The Incoming system is responsible for collecting updated packages and
1160 installing them in the Debian archive. It consists of a set of
1161 directories and scripts that are installed on <tt>&ftp-master-host;</tt>.
1162         <p>
1163 Packages are uploaded by all the maintainers into a directory called
1164 <file>UploadQueue</file>. 
1165 This directory is scanned every few minutes by a daemon called
1166 <prgn>queued</prgn>, <file>*.command</file>-files are executed, and
1167 remaining and correctly signed <file>*.changes</file>-files are moved
1168 together with their corresponding files to the <file>unchecked</file>
1169 directory.
1170 This directory is not visible for most Developers, as ftp-master is restricted;
1171 it is scanned every 15 minutes by
1172 the <prgn>katie</prgn> script, which verifies the integrity of the uploaded
1173 packages and their cryptographic signatures.
1174 If the package is considered ready to be installed, it
1175 is moved into the <file>accepted</file> directory. If this is the first upload of
1176 the package (or it has new binary packages),
1177 it is moved to the <file>new</file> directory, where it waits
1178 for approval by the ftpmasters. If the package contains files to be installed
1179 "by hand" it is moved to the <file>byhand</file> directory, where it waits
1180 for manual installation by the ftpmasters. Otherwise, if any error has been detected,
1181 the package is refused and is moved to the <file>reject</file> directory.
1182         <p>
1183 Once the package is accepted, the system sends a confirmation
1184 mail to the maintainer and closes all the bugs marked as fixed by the upload,
1185 and the auto-builders may start recompiling it. The package is now publicly
1186 accessible at <url id="&url-incoming;">
1187 until it is really installed
1188 in the Debian archive.
1189 This happens only once a day
1190 (and is also called the `dinstall run' for historical reasons);
1191 the package
1192 is then removed from incoming and installed in the pool along with all
1193 the other packages. Once all the other updates (generating new
1194 <file>Packages</file> and <file>Sources</file> index files for example) have been
1195 made, a special script is called to ask all the primary mirrors to update
1196 themselves.
1197         <p>
1198 The archive maintenance software will also send the OpenPGP/GnuPG signed
1199 <file>.changes</file> file that you uploaded to the appropriate mailing
1200 lists. If a package is released with the <tt>Distribution:</tt> set to
1201 `stable', the announcement is sent to &email-debian-changes;.
1202 If a package is released with <tt>Distribution:</tt> set to `unstable'
1203 or `experimental', the announcement will be posted to
1204 &email-debian-devel-changes; instead.
1205         <p>
1206 Though ftp-master is restricted, a copy of the installation is available
1207 to all developers on <tt>&ftp-master-mirror;</tt>.
1208 <!-- FIXME: delete it or keep it for historical purposes?
1209         <p>
1210 All Debian developers have write access to the <file>unchecked</file>
1211 directory in order to upload their packages; they also have that access
1212 to the <file>reject</file> directory in order to remove their bad uploads
1213 or to move some files back to the <file>unchecked</file> directory. But
1214 all the other directories are only writable by the ftpmasters, which is
1215 why you cannot remove an upload once it has been accepted.
1216
1217       <sect1 id="delayed-incoming-broken">Delayed incoming
1218         <p>
1219 <em>Note:</em> This description here is currently not working, because
1220 ftp-master is restricted. Please see <ref id="delayed-incoming"> for
1221 the currently working way.
1222         <p>
1223 The <file>unchecked</file> directory has a special <file>DELAYED</file>
1224 subdirectory. It is itself subdivided in nine directories
1225 called <file>1-day</file> to <file>9-day</file>. Packages which are uploaded to
1226 one of those directories will be moved to the real unchecked
1227 directory after the corresponding number of days.
1228 This is done by a script which is run each day and which moves the
1229 packages between the directories. Those which are in "1-day" are
1230 installed in <file>unchecked</file> while the others are moved to the 
1231 adjacent directory (for example, a package in <file>5-day</file> will
1232 be moved to <file>4-day</file>). This feature is particularly useful
1233 for people who are doing non-maintainer uploads. Instead of
1234 waiting before uploading a NMU, it is uploaded as soon as it is
1235 ready, but to one of those <file>DELAYED/<var>x</var>-day</file> directories.
1236 That leaves the corresponding number of days for the maintainer
1237 to react and upload another fix themselves if they are not
1238 completely satisfied with the NMU. Alternatively they can remove
1239 the NMU.
1240         <p>
1241 The use of that delayed feature can be simplified with a bit
1242 of integration with your upload tool.  For instance, if you use 
1243 <prgn>dupload</prgn> (see <ref id="dupload">), you can add this
1244 snippet to your configuration file:
1245 <example>
1246 $delay = ($ENV{DELAY} || 7);
1247 $cfg{'delayed'} = {
1248          fqdn => "&ftp-master-host;",
1249          login => "yourdebianlogin",
1250          incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
1251          dinstall_runs => 1,
1252          method => "scpb"
1253 };
1254 </example>
1255 Once you've made that change, <prgn>dupload</prgn> can be used to
1256 easily upload a package in one of the delayed directories:
1257 <example>DELAY=5 dupload -X-to delayed &lt;changes-file&gt;</example>
1258 -->
1259
1260
1261     <sect id="pkg-info">Package information
1262         <p>
1263
1264       <sect1 id="pkg-info-web">On the web
1265         <p>
1266 Each package has several dedicated web pages.
1267 <tt>http://&packages-host;/<var>package-name</var></tt>
1268 displays each version of the package
1269 available in the various distributions.  Each version links to a page
1270 which provides information, including the package description,
1271 the dependencies, and package download links.
1272         <p>
1273 The bug tracking system tracks bugs for each package.
1274 You can view the bugs of a given package at the URL
1275 <tt>http://&bugs-host;/<var>package-name</var></tt>.
1276
1277       <sect1 id="madison">The <prgn>madison</prgn> utility
1278         <p>
1279 <prgn>madison</prgn> is a command-line utility that is available
1280 on <tt>&ftp-master-host;</tt>, and on
1281 the mirror on <tt>&ftp-master-mirror;</tt>. It
1282 uses a single argument corresponding to a package name. In result
1283 it displays which version of the package is available for each
1284 architecture and distribution combination. An example will explain
1285 it better.
1286         <p>
1287 <example>
1288 $ madison libdbd-mysql-perl
1289 libdbd-mysql-perl |   1.2202-4 |        stable | source, alpha, arm, i386, m68k, powerpc, sparc
1290 libdbd-mysql-perl |   1.2216-2 |       testing | source, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
1291 libdbd-mysql-perl | 1.2216-2.0.1 |       testing | alpha
1292 libdbd-mysql-perl |   1.2219-1 |      unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
1293 </example>
1294         <p>
1295 In this example, you can see that the version in <em>unstable</em> differs from
1296 the version in <em>testing</em> and that there has been a binary-only NMU of the
1297 package for the alpha architecture. Each version of the package has been
1298 recompiled on most of the architectures.
1299
1300     <sect id="pkg-tracking-system">The Package Tracking System
1301         <p>
1302 The Package Tracking System (PTS) is an email-based tool to track
1303 the activity of a source package. This really means that you can
1304 get the same emails that the package maintainer gets, simply by
1305 subscribing to the package in the PTS.
1306         <p>
1307 Each email sent through the PTS is classified under one of
1308 the keywords listed below. This will let you select the mails that
1309 you want to receive.
1310         <p>
1311 By default you will get:
1312 <taglist>
1313     <tag><tt>bts</tt>
1314     <item>
1315 All the bug reports and following discussions.
1316
1317     <tag><tt>bts-control</tt>
1318     <item>
1319 The email notifications from <email>control@bugs.debian.org</email>
1320 about bug report status changes.
1321     
1322     <tag><tt>upload-source</tt>
1323     <item>
1324 The email notification from <prgn>katie</prgn> when an uploaded source
1325 package is accepted.
1326
1327     <tag><tt>katie-other</tt>
1328     <item>
1329 Other warning and error emails from <prgn>katie</prgn> (such as an
1330 override disparity for the section and/or the priority field).
1331
1332     <tag><tt>default</tt>
1333     <item>
1334 Any non-automatic email sent to the PTS by people who wanted to
1335 contact the subscribers of the package. This can be done by sending mail
1336 to <tt><var>sourcepackage</var>@&pts-host;</tt>. In order to prevent spam,
1337 all messages sent to these addresses must contain the <tt>X-PTS-Approved</tt>
1338 header with a non-empty value.
1339
1340     <tag><tt>summary</tt>
1341     <item>
1342 (This is a planned expansion.)
1343 The regular summary emails about the package's status (bug statistics,
1344 porting overview, progression in <em>testing</em>, ...).
1345 </taglist>
1346
1347         <p>
1348 You can also decide to receive additional information:
1349 <taglist>
1350     <tag><tt>upload-binary</tt>
1351     <item>
1352 The email notification from <prgn>katie</prgn> when an uploaded binary
1353 package is accepted. In other words, whenever a build daemon or a porter
1354 uploads your package for another architecture, you can get an email to
1355 track how your package gets recompiled for all architectures.
1356
1357     <tag><tt>cvs</tt>
1358     <item>
1359 CVS commit notifications, if the package has a CVS repository and the
1360 maintainer has set up forwarding commit notifications to the PTS.
1361
1362     <tag><tt>ddtp</tt>
1363     <item>
1364 Translations of descriptions or debconf templates
1365 submitted to the Debian Description Translation Project.
1366
1367     <tag><tt>derivatives</tt>
1368     <item>
1369 Information about changes made to the package in derivative distributions
1370 (for example Ubuntu).
1371 </taglist>
1372
1373         <sect1 id="pts-commands">The PTS email interface
1374         <p>
1375 You can control your subscription(s) to the PTS by sending
1376 various commands to <email>pts@qa.debian.org</email>. 
1377
1378 <taglist>
1379
1380 <tag><tt>subscribe &lt;sourcepackage&gt; [&lt;email&gt;]</tt>
1381 <item>
1382   Subscribes <var>email</var> to communications related to the source package
1383   <var>sourcepackage</var>. Sender address is used if the second argument is
1384   not present. If <var>sourcepackage</var> is not a valid source package,
1385   you'll get a warning. However if it's a valid binary package, the PTS
1386   will subscribe you to the corresponding source package.
1387
1388 <tag><tt>unsubscribe &lt;sourcepackage&gt; [&lt;email&gt;]</tt>
1389 <item>
1390   Removes a previous subscription to the source package <var>sourcepackage</var>
1391   using the specified email address or the sender address if the second
1392   argument is left out. 
1393
1394 <tag><tt>unsubscribeall [&lt;email&gt;]</tt>
1395 <item>
1396   Removes all subscriptions of the specified email address or the sender
1397   address if the second argument is left out. 
1398
1399 <tag><tt>which [&lt;email&gt;]</tt>
1400 <item>
1401   Lists all subscriptions for the sender or the email address optionally 
1402   specified.
1403
1404 <tag><tt>keyword [&lt;email&gt;]</tt>
1405 <item>
1406   Tells you the keywords that you are accepting.
1407   For an explanation of keywords, <qref id="pkg-tracking-system">see
1408   above</qref>. Here's a quick summary:
1409   <list>
1410   <item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
1411   <item><tt>bts-control</tt>: reply to mails sent to &email-bts-control;
1412   <item><tt>summary</tt>: automatic summary mails about the state of a package
1413   <item><tt>cvs</tt>: notification of CVS commits
1414   <item><tt>ddtp</tt>: translations of descriptions and debconf templates
1415   <item><tt>derivatives</tt>: changes made on the package by derivative distributions
1416   <item><tt>upload-source</tt>: announce of a new source upload that
1417         has been accepted
1418   <item><tt>upload-binary</tt>: announce of a new binary-only upload (porting)
1419   <item><tt>katie-other</tt>: other mails from ftpmasters
1420         (override disparity, etc.)
1421   <item><tt>default</tt>: all the other mails (those which aren't "automatic")
1422   </list>
1423
1424 <tag><tt>keyword &lt;sourcepackage&gt; [&lt;email&gt;]</tt>
1425 <item>
1426   Same as the previous item but for the given source package, since
1427   you may select a different set of keywords for each source package.
1428
1429 <tag><tt>keyword [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</tt>
1430 <item>
1431   Accept (+) or refuse (-) mails classified under the given keyword(s).
1432   Define the list (=) of accepted keywords. This changes the default set
1433   of keywords accepted by a user.
1434
1435 <tag><tt>keywordall [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</tt>
1436 <item>
1437   Accept (+) or refuse (-) mails classified under the given keyword(s).
1438   Define the list (=) of accepted keywords. This changes the set of
1439   accepted keywords of all the currently active subscriptions of a user.
1440
1441 <tag><tt>keyword &lt;sourcepackage&gt; [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</tt>
1442 <item>
1443   Same as previous item but overrides the keywords list for the
1444   indicated source package.
1445   
1446 <tag><tt>quit | thanks | --</tt>
1447 <item>
1448   Stops processing commands. All following lines are ignored by
1449   the bot.
1450 </taglist>
1451
1452         <p>
1453 The <prgn>pts-subscribe</prgn> command-line utility (from the
1454 <package>devscripts</package> package) can be handy to temporarily
1455 subscribe to some packages, for example after having made an
1456 non-maintainer upload.
1457
1458         <sect1 id="pts-mail-filtering">Filtering PTS mails
1459         <p>
1460 Once you are subscribed to a package, you will get the mails sent to
1461 <tt><var>sourcepackage</var>@packages.qa.debian.org</tt>. Those mails
1462 have special headers appended to let you filter them in a special
1463 mailbox (e.g. with <prgn>procmail</prgn>). The added headers are
1464 <tt>X-Loop</tt>, <tt>X-PTS-Package</tt>, <tt>X-PTS-Keyword</tt> and
1465 <tt>X-Unsubscribe</tt>.
1466         <p>
1467 Here is an example of added headers for a source upload notification
1468 on the <package>dpkg</package> package:
1469 <example>
1470 X-Loop: dpkg@&pts-host;
1471 X-PTS-Package: dpkg
1472 X-PTS-Keyword: upload-source
1473 X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org
1474 </example>
1475
1476         <sect1 id="pts-cvs-commit">Forwarding CVS commits in the PTS
1477         <p>
1478 If you use a publicly accessible CVS repository for maintaining
1479 your Debian package, you may want to forward the commit notification
1480 to the PTS so that the subscribers (and possible co-maintainers) can
1481 closely follow the package's evolution.
1482         <p>
1483 Once you set up the CVS repository to generate commit notifications,
1484 you just have to make sure it sends a copy of those mails
1485 to <tt><var>sourcepackage</var>_cvs@&pts-host;</tt>. Only the people
1486 who accept the <em>cvs</em> keyword will receive these notifications.
1487
1488         <sect1 id="pts-web">The PTS web interface
1489         <p>
1490 The PTS has a web interface at <url id="http://&pts-host;/"> that puts
1491 together a lot of information about each source package. It features many useful
1492 links (BTS, QA stats, contact information, DDTP translation status,
1493 buildd logs) and gathers much more information from various places
1494 (30 latest changelog entries, testing status, ...). It's a very useful
1495 tool if you want to know what's going on with a specific source
1496 package. Furthermore there's a form that allows easy subscription to
1497 the PTS via email.
1498         <p>
1499 You can jump directly to the web page concerning a specific source package
1500 with a URL like <tt>http://&pts-host;/<var>sourcepackage</var></tt>.
1501         <p>
1502 This web interface has been designed like a portal for the development of
1503 packages: you can add custom content on your packages' pages. You can
1504 add "static information" (news items that are meant to stay available
1505 indefinitely) and news items in the "latest news" section.
1506         <p>
1507 Static news items can be used to indicate:
1508 <list>
1509 <item>the availability of a project hosted on <qref id="alioth">Alioth</qref> for co-maintaining the package
1510 <item>a link to the upstream web site
1511 <item>a link to the upstream bug tracker
1512 <item>the existence of an IRC channel dedicated to the software
1513 <item>any other available resource that could be useful in the maintenance of the package
1514 </list>
1515 Usual news items may be used to announce that:
1516 <list>
1517 <item>beta packages are available for testing
1518 <item>final packages are expected for next week
1519 <item>the packaging is about to be redone from scratch
1520 <item>backports are available
1521 <item>the maintainer is on vacation (if they wish to publish this information)
1522 <item>a NMU is being worked on
1523 <item>something important will affect the package
1524 </list>
1525         <p>
1526 Both kinds of news are generated in a similar manner: you just have to send
1527 an email either to <email>pts-static-news@qa.debian.org</email> or to
1528 <email>pts-news@qa.debian.org</email>. The mail should indicate which
1529 package is concerned by having the name of the source package in a
1530 <tt>X-PTS-Package</tt> mail header or in a <tt>Package</tt> pseudo-header (like the
1531 BTS reports). If a URL is available in the <tt>X-PTS-Url</tt> mail header or in
1532 the <tt>Url</tt> pseudo-header, then the result is a link to that URL instead
1533 of a complete news item.
1534         <p>
1535 Here are a few examples of valid mails used to generate news items in
1536 the PTS. The first one adds a link to the cvsweb interface of debian-cd
1537 in the "Static information" section:
1538 <example>
1539 From: Raphael Hertzog &lt;hertzog@debian.org&gt;
1540 To: pts-static-news@qa.debian.org
1541 Subject: Browse debian-cd CVS repository with cvsweb
1542
1543 Package: debian-cd
1544 Url: http://cvs.debian.org/debian-cd/
1545 </example>
1546         <p>
1547 The second one is an announcement sent to a mailing list which is also sent
1548 to the PTS so that it is published on the PTS web page of the package. Note the
1549 use of the BCC field to avoid answers sent to the PTS by mistake.
1550 <example>
1551 From: Raphael Hertzog &lt;hertzog@debian.org&gt;
1552 To: debian-gtk-gnome@lists.debian.org
1553 Bcc: pts-news@qa.debian.org
1554 Subject: Galeon 2.0 backported for woody
1555 X-PTS-Package: galeon
1556
1557 Hello gnomers!
1558
1559 I'm glad to announce that galeon has been backported for woody. You'll find
1560 everything here:
1561 ...
1562 </example>
1563         <p>
1564 Think twice before adding a news item to the PTS because you won't be able
1565 to remove it later and you won't be able to edit it either. The only thing
1566 that you can do is send a second news item that will deprecate the
1567 information contained in the previous one.
1568
1569     <sect id="ddpo">Developer's packages overview
1570         <p>
1571 A QA (quality assurance) web portal is available at <url
1572             id="&url-ddpo;"> which displays a table listing all the packages
1573 of a single developer (including those where the party is listed as
1574 a co-maintainer). The table gives a good summary about the developer's 
1575 packages: number of bugs by severity, list of available versions in each
1576 distribution, testing status and much more including links to any other
1577 useful information.
1578         <p>
1579 It is a good idea to look up your own data regularly so that
1580 you don't forget any open bugs, and so that you don't forget which
1581 packages are your responsibility.
1582
1583     <sect id="alioth">Debian *Forge: Alioth
1584         <p>
1585 Alioth is a fairly new Debian service, based on a slightly modified version
1586 of the GForge software (which evolved from SourceForge). This software
1587 offers developers access to easy-to-use tools such as bug trackers, patch
1588 manager, project/task managers, file hosting services, mailing lists, CVS
1589 repositories etc. All these tools are managed via a web interface.
1590         <p>
1591 It is intended to provide facilities to free software projects backed or led
1592 by Debian, facilitate contributions from external developers to projects
1593 started by Debian, and help projects whose goals are the promotion of Debian
1594 or its derivatives.
1595         <p>
1596 All Debian developers automatically have an account on Alioth.
1597 They can activate it by using the recover password facility.
1598 External developers can request guest accounts on Alioth.
1599         <p>
1600 For more information please visit <url id="&url-alioth;">.
1601
1602     <sect id="developer-misc">Goodies for Developers
1603         <p>
1604      <sect1 id="lwn">LWN Subscriptions
1605         <p>
1606 Since October of 2002, HP has sponsored a subscription to LWN for all 
1607 interested Debian developers.
1608
1609 Details on how to get access to this benefit are in
1610 <url id="http://lists.debian.org/debian-devel-announce/2002/10/msg00018.html">.
1611
1612
1613
1614    <chapt id="pkgs">Managing Packages
1615         <p>
1616 This chapter contains information related to creating, uploading,
1617 maintaining, and porting packages.
1618
1619
1620     <sect id="newpackage">New packages
1621         <p>
1622 If you want to create a new package for the Debian distribution, you
1623 should first check the <url id="&url-wnpp;" name="Work-Needing and
1624 Prospective Packages (WNPP)"> list. Checking the WNPP list ensures that
1625 no one is already working on packaging that software, and that effort is
1626 not duplicated. Read the <url id="&url-wnpp;" name="WNPP web pages"> for
1627 more information.
1628         <p>
1629 Assuming no one else is already working on your prospective package,
1630 you must then submit a bug report (<ref id="submit-bug">) against the
1631 pseudo-package <package>wnpp</package> 
1632 describing your plan to create a new package, including, but not
1633 limiting yourself to, a description of the package, the license of the
1634 prospective package, and the current URL where it can be downloaded
1635 from.
1636         <p>
1637 You should set the subject of the bug to ``ITP: <var>foo</var>
1638 -- <var>short description</var>'', substituting the name of the new
1639 package for <var>foo</var>.  The severity of the bug report must be set
1640 to <em>wishlist</em>. If you feel it's necessary, send a copy to
1641 &email-debian-devel; by putting the address in the <tt>X-Debbugs-CC:</tt> header
1642 of the message (no, don't use <tt>CC:</tt>, because that way the message's subject
1643 won't indicate the bug number).
1644         <p>
1645 Please include a <tt>Closes: bug#<var>nnnnn</var></tt> entry in the
1646 changelog of the new package in order for the bug report to be
1647 automatically closed once the new package is installed in the archive
1648 (see <ref id="upload-bugfix">).
1649         <p>
1650 When closing security bugs include CVE numbers as well as the 
1651 "Closes: #nnnnn".
1652 This is useful for the security team to track vulnerabilities.
1653 If an upload is made to fix the bug before the advisory ID is known,
1654 it is encouraged to modify the historical changelog entry with the next upload.
1655 Even in this case, please include all available pointers to background
1656 information in the original changelog entry.
1657
1658         <p>
1659 There are a number of reasons why we ask maintainers to announce their
1660 intentions:
1661           <list compact>
1662             <item>
1663 It helps the (potentially new) maintainer to tap into the experience
1664 of people on the list, and lets them know if anyone else is working
1665 on it already.
1666             <item>
1667 It lets other people thinking about working on the package know that
1668 there already is a volunteer, so efforts may be shared.
1669             <item>
1670 It lets the rest of the maintainers know more about the package than
1671 the one line description and the usual changelog entry ``Initial release''
1672 that gets posted to <tt>debian-devel-changes</tt>.
1673             <item>
1674 It is helpful to the people who live off unstable (and form our first
1675 line of testers).  We should encourage these people.
1676             <item>
1677 The announcements give maintainers and other interested parties a
1678 better feel of what is going on, and what is new, in the project.
1679           </list>
1680         <p>
1681 Please see <url id="http://ftp-master.debian.org/REJECT-FAQ.html">
1682 for common rejection reasons for a new package.
1683
1684     <sect id="changelog-entries">Recording changes in the package
1685           <p>
1686 Changes that you make to the package need to be recorded in the
1687 <file>debian/changelog</file>.  These changes should provide a concise
1688 description of what was changed, why (if it's in doubt), and note if
1689 any bugs were closed.  They also record when the package was
1690 completed.  This file will be installed in
1691 <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>, or
1692 <file>/usr/share/doc/<var>package</var>/changelog.gz</file> for native
1693 packages.
1694           <p>
1695 The <file>debian/changelog</file> file conforms to a certain structure,
1696 with a number of different fields.  One field of note, the
1697 <em>distribution</em>, is described in <ref id="distribution">.  More
1698 information about the structure of this file can be found in
1699 the Debian Policy section titled "<file>debian/changelog</file>".
1700           <p>
1701 Changelog entries can be used to automatically close Debian bugs when
1702 the package is installed into the archive.  See <ref
1703 id="upload-bugfix">.
1704           <p>
1705 It is conventional that the changelog entry of a package that
1706 contains a new upstream version of the software looks like this:
1707 <example>
1708   * new upstream version
1709 </example>
1710           <p>
1711 There are tools to help you create entries and finalize the
1712 <file>changelog</file> for release &mdash; see <ref id="devscripts">
1713 and <ref id="dpkg-dev-el">.
1714           <p>
1715 See also <ref id="bpp-debian-changelog">.
1716
1717
1718     <sect id="sanitycheck">Testing the package
1719         <p>
1720 Before you upload your package, you should do basic testing on it.  At
1721 a minimum, you should try the following activities (you'll need to
1722 have an older version of the same Debian package around):
1723 <list>
1724               <item>
1725 Install the package and make sure the software works, or upgrade the
1726 package from an older version to your new version if a Debian package
1727 for it already exists.
1728               <item>
1729 Run <prgn>lintian</prgn> over the package.  You can run
1730 <prgn>lintian</prgn> as follows: <tt>lintian -v
1731 <var>package-version</var>.changes</tt>. This will check the source
1732 package as well as the binary package.  If you don't understand the
1733 output that <prgn>lintian</prgn> generates, try adding the <tt>-i</tt>
1734 switch, which will cause <prgn>lintian</prgn> to output a very verbose
1735 description of the problem.
1736                 <p>
1737 Normally, a package should <em>not</em> be uploaded if it causes lintian
1738 to emit errors (they will start with <tt>E</tt>).
1739                 <p>
1740 For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
1741               <item>
1742 Optionally run <ref id="debdiff"> to analyze changes from an older version,
1743 if one exists.
1744               <item>
1745 Downgrade the package to the previous version (if one exists) &mdash; this
1746 tests the <file>postrm</file> and <file>prerm</file> scripts.
1747               <item>
1748 Remove the package, then reinstall it.
1749              <item>
1750 Copy the source package in a different directory and try unpacking it and
1751 rebuilding it.  This tests if the package relies on existing files outside of
1752 it, or if it relies on permissions being preserved on the files shipped inside
1753 the .diff.gz file.
1754             </list>
1755
1756
1757     <sect id="sourcelayout">Layout of the source package
1758         <p>
1759 There are two types of Debian source packages:
1760         <list>
1761           <item>the so-called <em>native</em> packages, where there is no
1762                 distinction between the original sources and the patches
1763                 applied for Debian
1764           <item>the (more common) packages where there's an original source
1765                 tarball file accompanied by another file that contains the
1766                 patches applied for Debian
1767         </list>
1768         <p>
1769 For the native packages, the source package includes a Debian source control
1770 file (<tt>.dsc</tt>) and the source tarball (<tt>.tar.gz</tt>). A source
1771 package of a non-native package includes a Debian source control file, the
1772 original source tarball (<tt>.orig.tar.gz</tt>) and the Debian patches
1773 (<tt>.diff.gz</tt>).
1774         <p>
1775 Whether a package is native or not is determined when it is built by
1776 <manref name="dpkg-buildpackage" section="1">. The rest of this section
1777 relates only to non-native packages.
1778         <p>
1779 The first time a version is uploaded which corresponds to a particular
1780 upstream version, the original source tar file should be uploaded and
1781 included in the <file>.changes</file> file.  Subsequently, this very same
1782 tar file should be used to build the new diffs and <file>.dsc</file>
1783 files, and will not need to be re-uploaded.
1784         <p>
1785 By default, <prgn>dpkg-genchanges</prgn> and
1786 <prgn>dpkg-buildpackage</prgn> will include the original source tar
1787 file if and only if the Debian revision part of the source version
1788 number is 0 or 1, indicating a new upstream version.  This behavior
1789 may be modified by using <tt>-sa</tt> to always include it or
1790 <tt>-sd</tt> to always leave it out.
1791         <p>
1792 If no original source is included in the upload, the original
1793 source tar-file used by <prgn>dpkg-source</prgn> when constructing the
1794 <file>.dsc</file> file and diff to be uploaded <em>must</em> be
1795 byte-for-byte identical with the one already in the archive.
1796        <p>
1797 Please notice that, in non-native packages, permissions on files that are not
1798 present in the .orig.tar.gz will not be preserved, as diff does not store file
1799 permissions in the patch.
1800
1801
1802     <sect id="distribution">Picking a distribution
1803         <p>
1804 Each upload needs to specify which distribution the package is intended
1805 for. The package build process extracts this information from the first
1806 line of the <file>debian/changelog</file> file and places it in the
1807 <tt>Distribution</tt> field of the <tt>.changes</tt> file.
1808         <p>
1809 There are several possible values for this field: `stable', `unstable',
1810 `testing-proposed-updates' and `experimental'. Normally, packages are
1811 uploaded into <em>unstable</em>.
1812         <p>
1813 Actually, there are two other possible distributions: `stable-security' and
1814 `testing-security', but read <ref id="bug-security"> for more information on
1815 those.
1816         <p>
1817 It is not possible to upload a package into several distributions
1818 at the same time.
1819
1820         <sect1 id="upload-stable">
1821           <heading>Special case: uploads to the <em>stable</em> distribution</heading>
1822           <p>
1823 Uploading to <em>stable</em> means that the package will be placed into the
1824 <file>stable-proposed-updates</file> directory of the Debian archive for further
1825 testing before it is actually included in <em>stable</em>.
1826           <p>
1827 Extra care should be taken when uploading to <em>stable</em>. Basically, a
1828 package should only be uploaded to stable if one of the following happens:
1829 <list>
1830         <item>a truly critical functionality problem
1831         <item>the package becomes uninstallable
1832         <item>a released architecture lacks the package
1833 </list>
1834 <p>
1835 In the past, uploads to <em>stable</em> were used to address security
1836 problems as well.  However, this practice is deprecated, as uploads
1837 used for Debian security advisories are automatically copied to the
1838 appropriate <file>proposed-updates</file> archive when the advisory is
1839 released.  See <ref id="bug-security"> for detailed information on
1840 handling security problems.
1841           <p>
1842 Changing anything else in the package that isn't important is discouraged,
1843 because even trivial fixes can cause bugs later on.
1844           <p>
1845 Packages uploaded to <em>stable</em> need to be compiled on systems running
1846 <em>stable</em>, so that their dependencies are limited to the libraries
1847 (and other packages) available in <em>stable</em>; for example, a package
1848 uploaded to <em>stable</em> that depends on a library package that only
1849 exists in unstable will be rejected. Making changes to dependencies of other
1850 packages (by messing with <tt>Provides</tt> or shlibs files), possibly making
1851 those other packages uninstallable, is strongly discouraged.
1852           <p>
1853 The Release Team (which can be reached at &email-debian-release;) will
1854 regularly evaluate the uploads in <em>stable-proposed-updates</em> and decide if
1855 your package can be included in <em>stable</em>. Please be clear (and
1856 verbose, if necessary) in your changelog entries for uploads to
1857 <em>stable</em>, because otherwise the package won't be considered for
1858 inclusion.
1859           <p>
1860 It's best practice to speak with the stable release manager <em>before</em>
1861 uploading to <em>stable</em>/<em>stable-proposed-updates</em>, so that the
1862 uploaded package fits the needs of the next point release.
1863
1864         <sect1 id="upload-t-p-u">
1865           <heading>Special case: uploads to <em>testing/testing-proposed-updates</em></heading>
1866           <p>
1867 Please see the information in the <qref id="t-p-u">testing section</qref> for details.
1868
1869
1870     <sect id="upload">Uploading a package
1871
1872         <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
1873           <p>
1874 To upload a package, you should upload the files (including the signed
1875 changes and dsc-file) with anonymous ftp to
1876 <ftpsite>&ftp-master-host;</ftpsite> in the directory &upload-queue;.
1877 To get the files processed there, they need to be signed with a key in the
1878 debian keyring.
1879           <p>
1880 Please note that you should transfer
1881 the changes file last.  Otherwise, your upload may be rejected because the
1882 archive maintenance software will parse the changes file and see that not
1883 all files have been uploaded.
1884           <p>
1885 You may also find the Debian packages <ref id="dupload"> or
1886 <ref id="dput"> useful
1887 when uploading packages. These handy programs help automate the
1888 process of uploading packages into Debian.
1889           <p>
1890 For removing packages, please see the README file in that ftp directory,
1891 and the Debian package <ref id="dcut">.
1892
1893         <sect1 id="upload-non-us">Uploading to <tt>non-US</tt>
1894           <p>
1895 <em>Note:</em> non-us was discontinued with the release of sarge.
1896
1897
1898         <sect1 id="delayed-incoming">Delayed uploads
1899           <p>
1900 Delayed uploads are done for the moment via the delayed queue at
1901 gluck. The upload-directory is
1902 <ftpsite>gluck:~tfheen/DELAYED/[012345678]-day</ftpsite>.
1903 0-day is uploaded multiple times per day to ftp-master.
1904           <p>
1905 With a fairly recent dput, this section
1906 <example>
1907 [tfheen_delayed]
1908 method = scp
1909 fqdn = gluck.debian.org
1910 incoming = ~tfheen
1911 </example>
1912 in ~/.dput.cf should work fine for uploading to the DELAYED queue.
1913           <p>
1914 <em>Note:</em>
1915 Since this upload queue goes to <tt>ftp-master</tt>, the
1916 prescription found in <ref id="upload-ftp-master"> applies here as well.
1917
1918         <sect1>Security uploads
1919           <p>
1920 Do <strong>NOT</strong> upload a package to the security upload queue
1921 (oldstable-security,
1922 stable-security, etc.) without prior authorization from the security
1923 team. If the package does not exactly meet the team's requirements, it
1924 will cause many problems and delays in dealing with the unwanted upload.
1925 For details, please see section <ref id="bug-security">.
1926
1927         <sect1>Other upload queues
1928           <p>
1929 The scp queues on ftp-master, and security are mostly unusable
1930 due to the login restrictions on those hosts.
1931           <p>
1932 The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are
1933 currently down. Work is underway to resurrect them. 
1934           <p>
1935 The queues on master.debian.org, samosa.debian.org, master.debian.or.jp,
1936 and ftp.chiark.greenend.org.uk are down permanently, and will not be
1937 resurrected. The queue in Japan will be replaced with a new queue on
1938 hp.debian.or.jp some day.
1939           <p>
1940 For the time being, the anonymous ftp queue on auric.debian.org (the
1941 former ftp-master) works, but it is deprecated and will be removed at
1942 some point in the future.
1943
1944       <sect1 id="upload-notification">
1945         <heading>Notification that a new package has been installed</heading>
1946         <p>
1947 The Debian archive maintainers are responsible for handling package
1948 uploads.  For the most part, uploads are automatically handled on a
1949 daily basis by the archive maintenance tools, <prgn>katie</prgn>.
1950 Specifically, updates to existing packages to
1951 the `unstable' distribution are handled automatically. In other cases,
1952 notably new packages, placing the uploaded package into the
1953 distribution is handled manually. When uploads are handled manually,
1954 the change to the archive may take up to a month to occur. Please be
1955 patient.
1956         <p>
1957 In any case, you will receive an email notification indicating that the
1958 package has been added to the archive, which also indicates which bugs will
1959 be closed by the upload.  Please examine this notification carefully,
1960 checking if any bugs you meant to close didn't get triggered.
1961         <p>
1962 The installation notification also includes information on what
1963 section the package was inserted into.  If there is a disparity, you
1964 will receive a separate email notifying you of that.  Read on below.
1965         <p>
1966 Note that if you upload via queues, the queue daemon software will
1967 also send you a notification by email.
1968
1969     <sect id="override-file">Specifying the package section, subsection and priority
1970         <p>
1971 The <file>debian/control</file> file's <tt>Section</tt> and
1972 <tt>Priority</tt> fields do not actually specify where the file will
1973 be placed in the archive, nor its priority.  In order to retain the
1974 overall integrity of the archive, it is the archive maintainers who
1975 have control over these fields.  The values in the
1976 <file>debian/control</file> file are actually just hints.
1977         <p>
1978 The archive maintainers keep track of the canonical sections and
1979 priorities for packages in the <em>override file</em>.  If there is a
1980 disparity between the <em>override file</em> and the package's fields
1981 as indicated in <file>debian/control</file>, then you will receive an
1982 email noting the divergence when the package is installed into the
1983 archive.  You can either correct your <file>debian/control</file> file
1984 for your next upload, or else you may wish to make a change in the
1985 <em>override file</em>.
1986         <p>
1987 To alter the actual section that a package is put in, you need to
1988 first make sure that the <file>debian/control</file> file in your package
1989 is accurate.  Next, send an email &email-override; or submit a bug
1990 against <package>ftp.debian.org</package> requesting that the section
1991 or priority for your package be changed from the old section or
1992 priority to the new one.  Be sure to explain your reasoning.
1993         <p>
1994 For more information about <em>override files</em>, see <manref
1995 name="dpkg-scanpackages" section="1"> and
1996 <url id="&url-bts-devel;#maintincorrect">.
1997         <p>
1998 Note that the <tt>Section</tt> field describes both the section as
1999 well as the subsection, which are described in <ref
2000 id="archive-sections">.  If the section is "main", it should be
2001 omitted.  The list of allowable subsections can be found in <url
2002 id="&url-debian-policy;ch-archive.html#s-subsections">.
2003
2004
2005     <sect id="bug-handling">Handling bugs
2006         <p>
2007 Every developer has to be able to work with the Debian <url name="bug
2008 tracking system" id="&url-bts;">. This includes knowing how to file bug
2009 reports properly (see <ref id="submit-bug">), how to update them and
2010 reorder them, and how to process and close them.
2011         <p>
2012 The bug tracking system's features are described
2013 in the <url id="&url-bts-devel;" name="BTS documentation for developers">.
2014 This includes closing bugs, sending followup messages, assigning severities
2015 and tags, marking bugs as forwarded, and other issues.
2016         <p>
2017 Operations such as reassigning bugs to other packages, merging separate
2018 bug reports about the same issue, or reopening bugs when they are
2019 prematurely closed, are handled using the so-called control mail server.
2020 All of the commands available on this server are described in the
2021 <url id="&url-bts-control;" name="BTS control server documentation">.
2022
2023       <sect1 id="bug-monitoring">Monitoring bugs
2024         <p>
2025 If you want to be a good maintainer, you should periodically check the
2026 <url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
2027 packages.  The BTS contains all the open bugs against your packages.
2028 You can check them by browsing this page:
2029 <tt>http://&bugs-host;/<var>yourlogin</var>@debian.org</tt>.
2030         <p>
2031 Maintainers interact with the BTS via email addresses at
2032 <tt>&bugs-host;</tt>.  Documentation on available commands can be
2033 found at <url id="&url-bts;">, or, if you have installed the
2034 <package>doc-debian</package> package, you can look at the local files
2035 &file-bts-docs;.
2036         <p>
2037 Some find it useful to get periodic reports on open bugs.  You can add
2038 a cron job such as the following if you want to get a weekly email
2039 outlining all the open bugs against your packages:
2040 <example>
2041 # ask for weekly reports of bugs in my packages
2042 &cron-bug-report;
2043 </example>
2044 Replace <var>address</var> with your official Debian
2045 maintainer address.
2046
2047       <sect1 id="bug-answering">Responding to bugs
2048         <p>
2049 When responding to bugs, make sure that any discussion you have about
2050 bugs is sent both to the original submitter of the bug, and to the bug
2051 itself (e.g., <email>123@&bugs-host;</email>). If you're writing a new
2052 mail and you don't remember the submitter email address, you can
2053 use the <email>123-submitter@&bugs-host;</email> email to
2054 contact the submitter <em>and</em> to record your mail within the
2055 bug log (that means you don't need to send a copy of the mail to
2056 <email>123@&bugs-host;</email>).
2057         <p>
2058 If you get a bug which mentions "FTBFS", this means "Fails to build
2059 from source".  Porters frequently use this acronym.
2060         <p>
2061 Once you've dealt with a bug report (e.g. fixed it), mark it as
2062 <em>done</em> (close it) by sending an explanation message to
2063 <email>123-done@&bugs-host;</email>. If you're fixing a bug by
2064 changing and uploading the package, you can automate bug closing as
2065 described in <ref id="upload-bugfix">.
2066         <p>
2067 You should <em>never</em> close bugs via the bug server <tt>close</tt>
2068 command sent to &email-bts-control;.  If you do so, the original
2069 submitter will not receive any information about why the bug was
2070 closed.
2071
2072       <sect1 id="bug-housekeeping">Bug housekeeping
2073         <p>
2074 As a package maintainer, you will often find bugs in other packages or
2075 have bugs reported against your packages which are actually bugs in
2076 other packages. The bug tracking system's features
2077 are described in the <url id="&url-bts-devel;" name="BTS documentation for
2078 Debian developers">. Operations such as reassigning, merging, and tagging
2079 bug reports are described in the <url id="&url-bts-control;" name="BTS
2080 control server documentation">. This section contains
2081 some guidelines for managing your own bugs, based on the collective
2082 Debian developer experience.
2083         <p>
2084 Filing bugs for problems that you find in other packages is one of
2085 the "civic obligations" of maintainership, see <ref id="submit-bug">
2086 for details. However, handling the bugs in your own packages is
2087 even more important.
2088         <p>
2089 Here's a list of steps that you may follow to handle a bug report:
2090 <enumlist>
2091     <item>
2092 Decide whether the report corresponds to a real bug or not. Sometimes
2093 users are just calling a program in the wrong way because they haven't
2094 read the documentation. If you diagnose this, just close the bug with
2095 enough information to let the user correct their problem (give pointers
2096 to the good documentation and so on). If the same report comes up
2097 again and again you may ask yourself if the documentation is good
2098 enough or if the program shouldn't detect its misuse in order to
2099 give an informative error message. This is an issue that may need
2100 to be brought up with the upstream author.
2101     <p>
2102 If the bug submitter disagrees with your decision to close the bug,
2103 they may reopen it until you find an agreement on how to handle it.
2104 If you don't find any, you may want to tag the bug <tt>wontfix</tt>
2105 to let people know that the bug exists but that it won't be corrected.
2106 If this situation is unacceptable, you (or the submitter) may want to
2107 require a decision of the technical committee by reassigning the bug
2108 to <package>tech-ctte</package> (you may use the clone command of
2109 the BTS if you wish to keep it reported against your package). Before
2110 doing so, please read the <url id="&url-tech-ctte;" name="recommended procedure">.
2111     <item>
2112 If the bug is real but it's caused by another package, just reassign
2113 the bug to the right package. If you don't know which package it should
2114 be reassigned to, you should ask for help on
2115 <qref id="irc-channels">IRC</qref> or on &email-debian-devel;.
2116 Please make sure that the maintainer(s) of the package
2117 the bug is reassigned to
2118 know why you reassigned it.
2119     <p>
2120 Sometimes you also have to adjust the severity of the bug so that it
2121 matches our definition of the severity. That's because people tend to
2122 inflate the severity of bugs to make sure their bugs are fixed quickly.
2123 Some bugs may even be dropped to wishlist severity when the requested
2124 change is just cosmetic.
2125     <item>
2126 If the bug is real but the same problem has already been reported by
2127 someone else, then the two relevant bug reports should be merged
2128 into one using the merge command of the BTS.
2129 In this way, when the
2130 bug is fixed, all of the submitters will be informed of this.
2131 (Note, however, that emails sent to one bug report's submitter won't
2132 automatically be sent to the other report's submitter.)
2133 For more
2134 details on the technicalities of the merge command and its relative,
2135 the unmerge command, see the BTS control server documentation.
2136     <item>
2137 The bug submitter may have forgotten to provide some information, in which
2138 case you have to ask them for the required information. You may use the
2139 <tt>moreinfo</tt> tag to mark the bug as such. Moreover if you can't
2140 reproduce the bug, you tag it <tt>unreproducible</tt>. Anyone who
2141 can reproduce the bug is then invited to provide more information
2142 on how to reproduce it. After a few months, if this information has not
2143 been sent by someone, the bug may be closed.
2144     <item>
2145 If the bug is related to the packaging, you just fix it. If you are not
2146 able to fix it yourself, then tag the bug as <tt>help</tt>. You can
2147 also ask for help on &email-debian-devel; or &email-debian-qa;. If it's an
2148 upstream problem, you have to forward it to the upstream author.
2149 Forwarding a bug is not enough, you have to check at each release if
2150 the bug has been fixed or not. If it has, you just close it, otherwise
2151 you have to remind the author about it. If you have the required skills
2152 you can prepare a patch that fixes the bug and
2153 send it to the author at the same time.
2154 Make sure to send the patch to the BTS and to
2155 tag the bug as <tt>patch</tt>.
2156     <item>
2157 If you have fixed a bug in your local copy, or if a fix has been
2158 committed to the CVS repository, you may tag the bug as
2159 <tt>pending</tt> to let people know that the bug is corrected and that
2160 it will be closed with the next upload (add the <tt>closes:</tt> in
2161 the <file>changelog</file>). This is particularly useful if you
2162 are several developers working on the same package.
2163     <item>
2164 Once a corrected package is available in the <em>unstable</em>
2165 distribution, you can close the bug. This can be done automatically,
2166 read <ref id="upload-bugfix">.
2167 </enumlist>
2168
2169       <sect1 id="upload-bugfix">When bugs are closed by new uploads
2170         <p>
2171 As bugs and problems are fixed in your packages, it is your
2172 responsibility as the package maintainer to close these bugs.  However,
2173 you should not close a bug until the package which fixes the bug has
2174 been accepted into the Debian archive.  Therefore, once you get
2175 notification that your updated package has been installed into the
2176 archive, you can and should close the bug in the BTS.
2177 Also, the bug should be closed with the correct version.
2178         <p>
2179 However, it's possible to avoid having to manually close bugs after the
2180 upload &mdash; just list the fixed bugs in your <file>debian/changelog</file>
2181 file, following a certain syntax, and the archive maintenance software
2182 will close the bugs for you. For example:
2183
2184 <example>
2185 acme-cannon (3.1415) unstable; urgency=low
2186
2187   * Frobbed with options (closes: Bug#98339)
2188   * Added safety to prevent operator dismemberment, closes: bug#98765,
2189     bug#98713, #98714.
2190   * Added man page. Closes: #98725.
2191 </example>
2192
2193 Technically speaking, the following Perl regular expression describes
2194 how bug closing changelogs are identified:
2195 <example>
2196   /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
2197 </example>
2198
2199 We prefer the <tt>closes: #<var>XXX</var></tt> syntax, as it is the
2200 most concise entry and the easiest to integrate with the text of the
2201 <file>changelog</file>.
2202 Unless specified different by the <var>-v</var>-switch to
2203 <prgn>dpkg-buildpackage</prgn>, only the bugs closed in the
2204 most recent changelog entry are closed (basically, exactly
2205 the bugs mentioned in the changelog-part
2206 in the <file>.changes</file> file are closed).
2207         <p>
2208 Historically, uploads identified as
2209 <qref id="nmu">Non-maintainer upload (NMU)</qref>
2210 were tagged <tt>fixed</tt> instead of being closed,
2211 but that practice was ceased with the advent of version-tracking.
2212 The same applied to the tag <tt>fixed-in-experimental</tt>.
2213         <p>
2214 If you happen to mistype a bug number or forget a bug in the changelog
2215 entries, don't hesitate to undo any damage the error caused. To reopen
2216 wrongly closed bugs, send a <tt>reopen <var>XXX</var></tt> command to
2217 the bug tracking system's control address, &email-bts-control;.  To
2218 close any remaining bugs that were fixed by your upload, email the
2219 <file>.changes</file> file to <email>XXX-done@&bugs-host;</email>,
2220 where <var>XXX</var> is the bug number, and
2221 put "Version: YYY" and an empty line as the first two lines
2222 of the body of the email,
2223 where <var>YYY</var> is the first version
2224 where the bug has been fixed.
2225
2226         <p>
2227 Bear in mind that it is not obligatory to close bugs using the
2228 changelog as described above.  If you simply want to close bugs that
2229 don't have anything to do with an upload you made, do it by emailing
2230 an explanation to <email>XXX-done@&bugs-host;</email>.  Do
2231 <strong>not</strong> close bugs in the changelog entry of a version if
2232 the changes in that version of the package don't have any bearing on
2233 the bug.
2234           <p>
2235 For general information on how to write your changelog entries, see
2236 <ref id="bpp-debian-changelog">.
2237
2238
2239       <sect1 id="bug-security">Handling security-related bugs
2240         <p>
2241 Due to their sensitive nature, security-related bugs must be handled
2242 carefully.  The Debian Security Team exists to coordinate this
2243 activity, keeping track of outstanding security problems, helping
2244 maintainers with security problems or fixing them themselves, sending
2245 security advisories, and maintaining security.debian.org.
2246
2247 <!-- information about the security database goes here once it's ready -->
2248 <!-- (mdz) -->
2249
2250 <p>
2251 When you become aware of a security-related bug in a Debian package,
2252 whether or not you are the maintainer, collect pertinent information
2253 about the problem, and promptly contact the security team at
2254 &email-security-team; as soon as possible.  <strong>DO NOT UPLOAD</strong> any
2255 packages for stable; the security team will do that.
2256
2257 Useful information includes, for example:
2258
2259 <list compact>
2260   <item>Which versions of the package are known to be affected by the
2261   bug.  Check each version that is present in a supported Debian
2262   release, as well as testing and unstable.
2263
2264   <item>The nature of the fix, if any is available (patches are
2265   especially helpful)
2266
2267   <item>Any fixed packages that you have prepared yourself (send only
2268   the <tt>.diff.gz</tt> and <tt>.dsc</tt> files and read <ref
2269   id="bug-security-building"> first)
2270
2271   <item>Any assistance you can provide to help with testing (exploits,
2272   regression testing, etc.)
2273
2274   <item>Any information needed for the advisory (see <ref
2275   id="bug-security-advisories">)
2276
2277 </list>
2278
2279         <sect2 id="bug-security-confidentiality">Confidentiality
2280           <p>
2281 Unlike most other activities within Debian, information about security
2282 issues must sometimes be kept private for a time.
2283 This allows software distributors to coordinate their disclosure in
2284 order to minimize their users' exposure.  Whether this is the
2285 case depends on the nature of the problem and corresponding fix, and
2286 whether it is already a matter of public knowledge.
2287
2288 <p>
2289 There are several ways developers can learn of a security problem:
2290
2291 <list compact>
2292     <item>they notice it on a public forum (mailing list, web site, etc.)
2293     <item>someone files a bug report
2294     <item>someone informs them via private email
2295 </list>
2296
2297  In the first two cases, the information is public and it is important
2298  to have a fix as soon as possible. In the last case, however, it
2299  might not be public information. In that case there are a few
2300  possible options for dealing with the problem:
2301
2302 <list>
2303   <item>If the security exposure is minor, there is sometimes no need
2304   to keep the problem a secret and a fix should be made and released.
2305
2306   <item>If the problem is severe, it is preferable to share the
2307   information with
2308   other vendors and coordinate a release. The security team keeps
2309   in contact with the various organizations and individuals and can take
2310   care of that.
2311 </list>
2312
2313 <p>
2314  In all cases if the person who reports the problem asks that it not
2315  be disclosed, such requests should be honored, with the obvious
2316  exception of informing the security team in order that a fix may be
2317  produced for a stable release of Debian.  When sending confidential
2318  information to the security team, be sure to mention this fact.
2319
2320 <p>
2321 Please note that if secrecy is needed you may not upload a fix to
2322 unstable (or anywhere else, such as a public CVS repository).  It is
2323 not sufficient to obfuscate the details of the change, as the code
2324 itself is public, and can (and will) be examined by the general public.
2325
2326 <p>
2327 There are two reasons for releasing information even though secrecy is
2328 requested: the problem has been known for a while, or the problem
2329 or exploit has become public.
2330
2331         <sect2 id="bug-security-advisories">Security Advisories
2332           <p>
2333 Security advisories are only issued for the current, released stable
2334 distribution, and <em>not</em> for testing or unstable.  When released,
2335 advisories
2336 are sent to the &email-debian-security-announce;
2337
2338 mailing list and posted on <url
2339 id="&url-debian-security-advisories;" name="the security web page">.
2340 Security advisories are written and posted by the security
2341 team. However they certainly do not mind if a
2342 maintainer can supply some of the information for them, or write part
2343 of the text. Information that should be in an advisory includes:
2344
2345 <list compact>
2346   <item>A description of the problem and its scope, including:
2347     <list>
2348        <item>The type of problem (privilege escalation, denial of
2349   service, etc.)
2350        <item>What privileges may be gained, and by whom (if any)
2351        <item>How it can be exploited
2352        <item>Whether it is remotely or locally exploitable
2353        <item>How the problem was fixed
2354     </list>
2355
2356   This information allows users to assess the threat to their systems.
2357
2358   <item>Version numbers of affected packages
2359   <item>Version numbers of fixed packages
2360   <item>Information on where to obtain the updated packages
2361   (usually from the Debian security archive)
2362   <item>References to upstream advisories, <url
2363   id="http://cve.mitre.org" name="CVE"> identifiers, and any other
2364   information useful in cross-referencing the vulnerability
2365 </list>
2366
2367          <sect2 id="bug-security-building">
2368             <heading>Preparing packages to address security issues</heading>
2369          <p>
2370 One way that you can assist the security team in their duties is to
2371 provide them with fixed packages suitable for a security advisory for
2372 the stable
2373 Debian release.
2374          <p>
2375  When an update is made to the stable release, care must be taken to
2376  avoid changing system behavior or introducing new bugs.  In order to
2377  do this, make as few changes as possible to fix the bug.  Users and
2378  administrators rely on the exact behavior of a release once it is
2379  made, so any change that is made might break someone's system.  This
2380  is especially true of libraries: make sure you never change the API or
2381  ABI, no matter how small the change.
2382 <p>
2383 This means that moving to a new upstream version is not a good
2384 solution.  Instead, the relevant changes should be back-ported to the
2385 version present in the current stable Debian release. Generally,
2386 upstream maintainers are willing to help if needed.  If not, the
2387 Debian security team may be able to help.
2388 <p>
2389 In some cases, it is not possible to back-port a security fix, for
2390 example when large amounts of source code need to be modified or
2391 rewritten.  If this happens, it may be necessary to move to a new
2392 upstream version.  However, this is only done in extreme situations,
2393 and you must always coordinate that with the security team beforehand.
2394 <p>
2395 Related to this is another important guideline: always test your
2396 changes.  If you have an exploit available, try it and see if it
2397 indeed succeeds on the unpatched package and fails on the fixed
2398 package.  Test other, normal actions as well, as sometimes a security
2399 fix can break seemingly unrelated features in subtle ways.
2400 <p>
2401 Do <strong>NOT</strong> include any changes in your package which are
2402 not directly related to fixing the vulnerability.  These will only
2403 need to be reverted, and this wastes time.  If there are other bugs in
2404 your package that you would like to fix, make an upload to
2405 proposed-updates in the usual way, after the security advisory is
2406 issued.  The security update mechanism is not a means for introducing
2407 changes to your package which would otherwise be rejected from the
2408 stable release, so please do not attempt to do this.
2409 <p>
2410 Review and test your changes as much as possible.  Check the
2411 differences from the previous version repeatedly
2412 (<prgn>interdiff</prgn> from the <package>patchutils</package> package
2413 and <prgn>debdiff</prgn> from <package>devscripts</package> are useful
2414 tools for this, see <ref id="debdiff">).
2415 <p>
2416 Be sure to verify the following items:
2417
2418 <list>
2419     <item>Target the right distribution in your
2420     <file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
2421     testing this is <tt>testing-security</tt>, and for the previous
2422     stable release, this is <tt>oldstable-security</tt>. Do not target
2423     <var>distribution</var>-proposed-updates or <tt>stable</tt>!
2424
2425     <item>The upload should have urgency=high.
2426
2427     <item>Make descriptive, meaningful changelog entries.  Others will
2428     rely on them to determine whether a particular bug was fixed.
2429     Always include an external reference, preferably a CVE
2430     identifier, so that it can be cross-referenced.  Include the same
2431     information in the changelog for unstable, so that it is clear that
2432     the same bug was fixed, as this is very helpful when verifying
2433     that the bug is fixed in the next stable release.  If a CVE
2434     identifier has not yet been assigned, the security team will
2435     request one so that it can be included in the package and in the advisory.
2436
2437     <item>Make sure the version number is proper. It must be greater
2438     than the current package, but less than package versions in later
2439     distributions.  If in doubt, test it with <tt>dpkg
2440     --compare-versions</tt>.  Be careful not to re-use a version
2441     number that you have already used for a previous upload.  For
2442     <em>testing</em>, there must be
2443     a higher version in <em>unstable</em>. If there is none yet (for example,
2444     if <em>testing</em> and <em>unstable</em> have the same version) you must upload a
2445     new version to unstable first.
2446
2447     <item>Do not make source-only uploads if your package has any
2448     binary-all packages (do not use the <tt>-S</tt> option to
2449     <prgn>dpkg-buildpackage</prgn>).  The <prgn>buildd</prgn> infrastructure will
2450     not build those. This point applies to normal package uploads as
2451     well.
2452
2453     <item>Unless the upstream source has been uploaded to
2454     security.debian.org before (by a previous security update), build
2455     the upload with full upstream source (<tt>dpkg-buildpackage
2456     -sa</tt>).  If there has been a previous upload to
2457     security.debian.org with the same upstream version, you may upload
2458     without upstream source (<tt>dpkg-buildpackage -sd</tt>).
2459
2460     <item>Be sure to use the exact same <file>*.orig.tar.gz</file> as used in the
2461     normal archive, otherwise it is not possible to move the security
2462     fix into the main archives later.
2463
2464     <item>Build the package on a clean
2465     system which only has packages installed from the distribution you
2466     are building for. If you do not have such a system yourself, you
2467     can use a debian.org machine (see <ref id="server-machines">)
2468     or setup a chroot (see <ref id="pbuilder"> and
2469     <ref id="debootstrap">).
2470 </list>
2471
2472       <sect2 id="bug-security-upload">Uploading the fixed package
2473 <p>
2474 Do <strong>NOT</strong> upload a package to the security upload queue
2475 (oldstable-security, stable-security, etc.) without
2476 prior authorization from the security team.  If the package does not
2477 exactly meet the team's requirements, it will cause many problems and
2478 delays in dealing with the unwanted upload.
2479 <p>
2480 Do <strong>NOT</strong> upload your fix to proposed-updates without
2481 coordinating with the security team.  Packages from
2482 security.debian.org will be copied into the proposed-updates directory
2483 automatically.  If a package with the same or a higher version number
2484 is already installed into the archive, the security update will be
2485 rejected by the archive system.  That way, the stable distribution
2486 will end up without a security update for this package instead.
2487 <p>
2488 Once you have created and tested the new package and it has been
2489 approved by the security team, it needs to be uploaded so that it can
2490 be installed in the archives. For security uploads, the place to
2491 upload to is
2492 <tt>ftp://security-master.debian.org/pub/SecurityUploadQueue/</tt> .
2493
2494 <p>
2495 Once an upload to the security queue has been accepted, the package
2496 will automatically be rebuilt for all architectures and stored for
2497 verification by the security team.
2498
2499 <p>
2500 Uploads which are waiting for acceptance or verification are only
2501 accessible by the security team. This is necessary since there might
2502 be fixes for security problems that cannot be disclosed yet.
2503
2504 <p>
2505 If a member of the security team accepts a package, it will be
2506 installed on security.debian.org as well as proposed for the proper
2507 <var>distribution</var>-proposed-updates on ftp-master.
2508
2509     <sect id="archive-manip">
2510       <heading>Moving, removing, renaming, adopting, and orphaning
2511       packages</heading>
2512       <p>
2513 Some archive manipulation operations are not automated in the Debian
2514 upload process.  These procedures should be manually followed by
2515 maintainers.  This chapter gives guidelines on what to do in these
2516 cases.
2517
2518       <sect1 id="moving-pkgs">Moving packages
2519         <p>
2520 Sometimes a package will change its section.  For instance, a
2521 package from the `non-free' section might be GPL'd in a later version,
2522 in which case the package should be moved to `main' or
2523 `contrib'.<footnote> See the <url id="&url-debian-policy;"
2524 name="Debian Policy Manual"> for guidelines on what section a package
2525 belongs in.
2526           </footnote>
2527         <p>
2528 If you need to change the section for one of your packages, change the
2529 package control information to place the package in the desired
2530 section, and re-upload the package (see the <url id="&url-debian-policy;"
2531 name="Debian Policy Manual"> for details). 
2532 You must ensure that you include the <file>.orig.tar.gz</file> in your upload
2533 (even if you are not uploading a new upstream version),
2534 or it will not appear in the new section together with the rest of the package.
2535 If your new section is
2536 valid, it will be moved automatically. If it does not, then contact
2537 the ftpmasters in order to understand what happened.
2538         <p>
2539 If, on the other hand, you need to change the <em>subsection</em> of
2540 one of your packages (e.g., ``devel'', ``admin''), the procedure is
2541 slightly different.  Correct the subsection as found in the control
2542 file of the package, and re-upload that.  Also, you'll need to get the
2543 override file updated, as described in <ref id="override-file">.
2544
2545
2546       <sect1 id="removing-pkgs">Removing packages
2547         <p>
2548 If for some reason you want to completely remove a package (say, if it
2549 is an old compatibility library which is no longer required), you
2550 need to file a bug against <tt>ftp.debian.org</tt> asking that the
2551 package be removed;
2552 as all bugs, this bug should normally have normal severity.
2553 Make sure you indicate which distribution the
2554 package should be removed from. Normally, you can only have packages
2555 removed from <em>unstable</em> and <em>experimental</em>.  Packages
2556 are not removed from <em>testing</em> directly. Rather, they will be
2557 removed automatically after the package has been removed from
2558 <em>unstable</em> and no package in <em>testing</em> depends on it.
2559         <p>
2560 If you are simply restructuring a source package so that it no longer
2561 produces one or more binary packages, there is no need to explicitly ask
2562 for the packages that are no longer created to be removed.  Such packages
2563 will be removed when the new package structure has been uploaded into 
2564 <em>unstable</em> and when no package in <em>testing</em> depends on it.
2565         <p>
2566 You also have to detail the reasons justifying the request. This is to
2567 avoid unwanted removals and to keep a trace of why a package has been
2568 removed. For example, you can provide the name of the package that
2569 supersedes the one to be removed.
2570         <p>
2571 Usually you only ask for the removal of a package maintained by yourself.
2572 If you want to remove another package, you have to get the approval
2573 of its maintainer.
2574         <p>
2575 If in doubt concerning whether a package is disposable, email
2576 &email-debian-devel; asking for opinions.  Also of interest is the
2577 <prgn>apt-cache</prgn> program from the <package>apt</package>
2578 package.  When invoked as <tt>apt-cache showpkg
2579 <var>package</var></tt>, the program will show details for
2580 <var>package</var>, including reverse depends.
2581 Other useful programs include
2582 <tt>apt-cache rdepends</tt>,
2583 <prgn>apt-rdepends</prgn> and
2584 <prgn>grep-dctrl>.
2585 Removal of orphaned packages is discussed on &email-debian-qa;.
2586         <p>
2587 Once the package has been removed, the package's bugs should be handled.
2588 They should either be reassigned to another package in the case where
2589 the actual code has evolved into another package (e.g. <tt>libfoo12</tt>
2590 was removed because <tt>libfoo13</tt> supersedes it) or closed if the
2591 software is simply no longer part of Debian.
2592
2593         <sect2>Removing packages from <file>Incoming</file>
2594           <p>
2595 In the past, it was possible to remove packages from <file>incoming</file>.
2596 However, with the introduction of the new incoming system, this is no longer
2597 possible.  Instead, you have to upload a new revision of your package with
2598 a higher version than the package you want to replace.  Both versions will be
2599 installed in the archive but only the higher version will actually be
2600 available in <em>unstable</em> since the previous version will immediately
2601 be replaced by the higher.  However, if you do proper testing of your
2602 packages, the need to replace a package should not occur too often anyway.
2603
2604       <sect1>Replacing or renaming packages
2605         <p>
2606 When you make a mistake naming your package, you should follow a two-step
2607 process to rename it. First, set
2608 your <file>debian/control</file> file to replace and conflict with the
2609 obsolete name of the package (see the <url id="&url-debian-policy;"
2610 name="Debian Policy Manual"> for details).  Once you've uploaded
2611 the package and the package has moved into the archive, file a bug
2612 against <tt>ftp.debian.org</tt> asking to remove the package with the
2613 obsolete name. Do not forget to properly reassign the package's bugs
2614 at the same time.
2615         <p>
2616 At other times, you may make a mistake in constructing your package and
2617 wish to replace it. The only way to do this is to increase the version
2618 number and upload a new version. The old version will be expired in
2619 the usual manner.  Note that this applies to each part of your package,
2620 including the sources: if you wish to replace the upstream source tarball
2621 of your package, you will need to upload it with a different version. An
2622 easy possibility is to replace <file>foo_1.00.orig.tar.gz</file> with
2623 <file>foo_1.00+0.orig.tar.gz</file>. This restriction gives each file
2624 on the ftp site a unique name, which helps to ensure consistency across the
2625 mirror network.
2626
2627       <sect1 id="orphaning">Orphaning a package
2628         <p>
2629 If you can no longer maintain a package, you need to inform others,
2630 and see that the package is marked as orphaned.
2631 You should set the package maintainer to <tt>Debian QA Group
2632 &orphan-address;</tt> and submit a bug report
2633 against the pseudo package <package>wnpp</package>.  The bug report should be
2634 titled <tt>O: <var>package</var> -- <var>short description</var></tt>
2635 indicating that the package is now orphaned.  The severity of the bug
2636 should be set to <em>normal</em>; if the package has a priority of standard
2637 or higher, it should be set to important.
2638 If you feel it's necessary, send a copy
2639 to &email-debian-devel; by putting the address in the X-Debbugs-CC: header
2640 of the message (no, don't use CC:, because that way the message's subject
2641 won't indicate the bug number).
2642         <p>
2643 If you just intend to give the package away, but you can keep maintainership
2644 for the moment, then you should instead submit
2645 a bug against <package>wnpp</package> and title it <tt>RFA: <var>package</var> --
2646 <var>short description</var></tt>.
2647 <tt>RFA</tt> stands for <em>Request For Adoption</em>.
2648         <p>
2649 More information is on the <url id="&url-wnpp;" name="WNPP web pages">.
2650
2651       <sect1 id="adopting">Adopting a package
2652         <p>
2653 A list of packages in need of a new maintainer is available in the
2654 <url name="Work-Needing and Prospective Packages list (WNPP)"
2655 id="&url-wnpp;">. If you wish to take over maintenance of any of the
2656 packages listed in the WNPP, please take a look at the aforementioned
2657 page for information and procedures.
2658         <p>
2659 It is not OK to simply take over a package that you feel is neglected
2660 &mdash; that would be package hijacking.  You can, of course, contact the
2661 current maintainer and ask them if you may take over the package.
2662 If you have reason to believe a maintainer has gone AWOL
2663 (absent without leave), see <ref id="mia-qa">.
2664         <p>
2665 Generally, you may not take over the package without the assent of the
2666 current maintainer. Even if they ignore you, that is still not grounds to
2667 take over a package. Complaints about maintainers should be brought up on
2668 the developers' mailing list. If the discussion doesn't end with a positive
2669 conclusion, and the issue is of a technical nature, consider bringing it to
2670 the attention of the technical committee (see the <url name="technical
2671 committee web page" id="&url-tech-ctte;"> for more information).
2672         <p>
2673 If you take over an old package, you probably want to be listed as the
2674 package's official maintainer in the bug system. This will happen
2675 automatically once you upload a new version with an updated
2676 <tt>Maintainer:</tt> field, although it can take a few hours after the
2677 upload is done. If you do not expect to upload a new version for a while,
2678 you can use <ref id="pkg-tracking-system"> to get the bug reports. However,
2679 make sure that the old maintainer has no problem with the fact that
2680 they will continue to receive the bugs during that time.
2681
2682
2683     <sect id="porting">Porting and being ported
2684       <p>
2685 Debian supports an ever-increasing number of architectures.  Even if
2686 you are not a porter, and you don't use any architecture but one, it
2687 is part of your duty as a maintainer to be aware of issues of
2688 portability.  Therefore, even if you are not a porter, you should read
2689 most of this chapter.
2690       <p>
2691 Porting is the act of building Debian packages for architectures that
2692 are different from the original architecture of the package
2693 maintainer's binary package.  It is a unique and essential activity.
2694 In fact, porters do most of the actual compiling of Debian packages.
2695 For instance, for a single <em>i386</em> binary package, there must be
2696 a recompile for each architecture, which amounts to
2697 &number-of-arches; more builds.
2698
2699
2700       <sect1 id="kind-to-porters">Being kind to porters
2701         <p>
2702 Porters have a difficult and unique task, since they are required to
2703 deal with a large volume of packages.  Ideally, every source package
2704 should build right out of the box.  Unfortunately, this is often not
2705 the case.  This section contains a checklist of ``gotchas'' often
2706 committed by Debian maintainers &mdash; common problems which often stymie
2707 porters, and make their jobs unnecessarily difficult.
2708         <p>
2709 The first and most important thing is to respond quickly to bug or
2710 issues raised by porters.  Please treat porters with courtesy, as if
2711 they were in fact co-maintainers of your package (which, in a way, they
2712 are).  Please be tolerant of succinct or even unclear bug reports;
2713 do your best to hunt down whatever the problem is.
2714         <p>
2715 By far, most of the problems encountered by porters are caused by
2716 <em>packaging bugs</em> in the source packages.  Here is a checklist
2717 of things you should check or be aware of.
2718
2719 <enumlist>
2720             <item>
2721 Make sure that your <tt>Build-Depends</tt> and
2722 <tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
2723 are set properly.  The best way to validate this is to use the
2724 <package>debootstrap</package> package to create an unstable chroot
2725 environment (see <ref id="debootstrap">).
2726 Within that chrooted environment, install the
2727 <package>build-essential</package> package and any package
2728 dependencies mentioned in <tt>Build-Depends</tt> and/or
2729 <tt>Build-Depends-Indep</tt>.  Finally, try building your package
2730 within that chrooted environment.  These steps can be automated
2731 by the use of the <prgn>pbuilder</prgn> program which is provided by
2732 the package of the same name (see <ref id="pbuilder">).
2733                 <p>
2734 If you can't set up a proper chroot, <prgn>dpkg-depcheck</prgn> may be
2735 of assistance (see <ref id="dpkg-depcheck">).
2736                 <p>
2737 See the <url id="&url-debian-policy;" name="Debian Policy
2738 Manual"> for instructions on setting build dependencies.
2739             <item>
2740 Don't set architecture to a value other than ``all'' or ``any'' unless
2741 you really mean it.  In too many cases, maintainers don't follow the
2742 instructions in the <url id="&url-debian-policy;" name="Debian Policy
2743 Manual">.  Setting your architecture to ``i386'' is usually incorrect.
2744             <item>
2745 Make sure your source package is correct.  Do <tt>dpkg-source -x
2746 <var>package</var>.dsc</tt> to make sure your source package unpacks
2747 properly.  Then, in there, try building your package from scratch with
2748 <prgn>dpkg-buildpackage</prgn>.
2749             <item>
2750 Make sure you don't ship your source package with the
2751 <file>debian/files</file> or <file>debian/substvars</file> files.
2752 They should be removed by the `clean' target of
2753 <file>debian/rules</file>.
2754             <item>
2755 Make sure you don't rely on locally installed or hacked configurations
2756 or programs.  For instance, you should never be calling programs in
2757 <file>/usr/local/bin</file> or the like.  Try not to rely on programs
2758 being setup in a special way.  Try building your package on another
2759 machine, even if it's the same architecture.
2760             <item>
2761 Don't depend on the package you're building being installed already (a
2762 sub-case of the above issue).
2763             <item>
2764 Don't rely on the compiler being a certain version, if possible.  If
2765 not, then make sure your build dependencies reflect the restrictions,
2766 although you are probably asking for trouble, since different
2767 architectures sometimes standardize on different compilers.
2768             <item>
2769 Make sure your debian/rules contains separate ``binary-arch'' and
2770 ``binary-indep'' targets, as the Debian Policy Manual requires.
2771 Make sure that both targets work independently, that is, that you can
2772 call the target without having called the other before. To test this,
2773 try to run <tt>dpkg-buildpackage -B</tt>.
2774           </enumlist>
2775
2776
2777       <sect1 id="porter-guidelines">Guidelines for porter uploads
2778         <p>
2779 If the package builds out of the box for the architecture to be ported
2780 to, you are in luck and your job is easy.  This section applies to
2781 that case; it describes how to build and upload your binary package so
2782 that it is properly installed into the archive.  If you do have to
2783 patch the package in order to get it to compile for the other
2784 architecture, you are actually doing a source NMU, so consult <ref
2785 id="nmu-guidelines"> instead.
2786         <p>
2787 For a porter upload, no changes are being made to the source.  You do
2788 not need to touch any of the files in the source package.  This
2789 includes <file>debian/changelog</file>.
2790         <p>
2791 The way to invoke <prgn>dpkg-buildpackage</prgn> is as
2792 <tt>dpkg-buildpackage -B -m<var>porter-email</var></tt>.  Of course,
2793 set <var>porter-email</var> to your email address.  This will do a
2794 binary-only build of only the architecture-dependent portions of the
2795 package, using the `binary-arch' target in <file>debian/rules</file>.
2796         <p>
2797 If you are working on a Debian machine for your porting efforts and you
2798 need to sign your upload locally for its acceptance in the archive, you
2799 can run <prgn>debsign</prgn> on your <file>.changes</file> file to have
2800 it signed conveniently, or use the remote signing mode of <prgn>dpkg-sig</prgn>.
2801
2802
2803         <sect2 id="binary-only-nmu">
2804           <heading>Recompilation or binary-only NMU</heading>
2805         <p>
2806 Sometimes the initial porter upload is problematic because the environment
2807 in which the package was built was not good enough (outdated or obsolete
2808 library, bad compiler, ...). Then you may just need to recompile it in
2809 an updated environment. However, you have to bump the version number in
2810 this case, so that the old bad package can be replaced in the Debian archive
2811 (<prgn>katie</prgn> refuses to install new packages if they don't have a
2812 version number greater than the currently available one).
2813         <p>
2814 You have to make sure that your binary-only NMU doesn't render the package
2815 uninstallable. This could happen when a source package generates
2816 arch-dependent and arch-independent packages that depend on each other via
2817 $(Source-Version).
2818         <p>
2819 Despite the
2820 required modification of the changelog, these are called binary-only NMUs
2821 &mdash; there is no need in this case to trigger all other architectures
2822 to consider themselves out of date or requiring recompilation.
2823         <p>
2824 Such recompilations require special ``magic'' version numbering, so that
2825 the archive maintenance tools recognize that, even though there is a
2826 new Debian version, there is no corresponding source update.  If you
2827 get this wrong, the archive maintainers will reject your upload (due
2828 to lack of corresponding source code).
2829         <p>
2830 The ``magic'' for a recompilation-only NMU is triggered by using a
2831 suffix appended to the package version number,
2832 following the form b&lt;number&gt;.
2833 For instance, if the latest version you are
2834 recompiling against was version ``2.9-3'', your NMU should carry a
2835 version of ``2.9-3+b1''.  If the latest version was ``3.4+b1'' (i.e, a
2836 native package with a previous recompilation NMU), your NMU should have
2837 a version number of ``3.4+b2''.
2838
2839 <footnote>
2840 In the past, such NMUs used the third-level number on the Debian part of
2841 the revision to denote their recompilation-only status; however, this
2842 syntax was ambiguous with native packages and did not allow proper
2843 ordering of recompile-only NMUs, source NMUs, and security NMUs on the
2844 same package, and has therefore been abandoned in favor of this new
2845 syntax.</footnote>
2846         <p>
2847 Similar to initial porter uploads, the correct way of invoking
2848 <prgn>dpkg-buildpackage</prgn> is <tt>dpkg-buildpackage -B</tt> to only
2849 build the architecture-dependent parts of the package.
2850
2851
2852         <sect2 id="source-nmu-when-porter">
2853           <heading>When to do a source NMU if you are a porter</heading>
2854           <p>
2855 Porters doing a source NMU generally follow the guidelines found in
2856 <ref id="nmu">, just like non-porters.  However, it is expected that
2857 the wait cycle for a porter's source NMU is smaller than for a
2858 non-porter, since porters have to cope with a large quantity of
2859 packages.
2860 Again, the situation varies depending on the distribution they are
2861 uploading to. It also varies whether the architecture is a candidate
2862 for inclusion into the next stable release; the release managers
2863 decide and announce which architectures are candidates.
2864           <p>
2865 If you are a porter doing an NMU for `unstable', the above
2866 guidelines for porting should be followed, with two variations.
2867 Firstly, the acceptable waiting period &mdash; the time between when the
2868 bug is submitted to the BTS and when it is OK to do an NMU &mdash; is seven
2869 days for porters working on the unstable distribution.  This period
2870 can be shortened if the problem is critical and imposes hardship on
2871 the porting effort, at the discretion of the porter group.  (Remember,
2872 none of this is Policy, just mutually agreed upon guidelines.)
2873 For uploads to stable or testing, please coordinate with the appropriate
2874 release team first.
2875           <p>
2876 Secondly, porters doing source NMUs should make sure that the bug they
2877 submit to the BTS should be of severity `serious' or greater.  This
2878 ensures that a single source package can be used to compile every
2879 supported Debian architecture by release time.  It is very important
2880 that we have one version of the binary and source package for all
2881 architecture in order to comply with many licenses.
2882           <p>
2883 Porters should try to avoid patches which simply kludge around bugs in
2884 the current version of the compile environment, kernel, or libc.
2885 Sometimes such kludges can't be helped.  If you have to kludge around
2886 compiler bugs and the like, make sure you <tt>#ifdef</tt> your work
2887 properly; also, document your kludge so that people know to remove it
2888 once the external problems have been fixed.
2889           <p>
2890 Porters may also have an unofficial location where they can put the
2891 results of their work during the waiting period.  This helps others
2892 running the port have the benefit of the porter's work, even during
2893 the waiting period.  Of course, such locations have no official
2894 blessing or status, so buyer beware.
2895
2896
2897       <sect1 id="porter-automation">
2898           <heading>Porting infrastructure and automation</heading>
2899           <p>
2900 There is infrastructure and several tools to help automate package
2901 porting. This section contains a brief overview of this automation and
2902 porting to these tools; see the package documentation or references for
2903 full information.</p>
2904
2905           <sect2>
2906             <heading>Mailing lists and web pages</heading>
2907             <p>
2908 Web pages containing the status of each port can be found at <url
2909 id="&url-debian-ports;">.
2910             <p>
2911 Each port of Debian has a mailing list.  The list of porting mailing
2912 lists can be found at <url id="&url-debian-port-lists;">.  These lists
2913 are used to coordinate porters, and to connect the users of a given
2914 port with the porters.</p>
2915           </sect2>
2916
2917           <sect2>
2918             <heading>Porter tools</heading>
2919             <p>
2920 Descriptions of several porting tools can be found in <ref
2921 id="tools-porting">.</p>
2922           </sect2>
2923
2924           <sect2 id="buildd">
2925             <heading><package>buildd</package></heading>
2926             <p>
2927 The <package>buildd</package> system is used as a distributed,
2928 client-server build distribution system.  It is usually used in
2929 conjunction with <em>auto-builders</em>, which are ``slave'' hosts
2930 which simply check out and attempt to auto-build packages which need
2931 to be ported.  There is also an email interface to the system, which
2932 allows porters to ``check out'' a source package (usually one which
2933 cannot yet be auto-built) and work on it.
2934           <p>
2935 <package>buildd</package> is not yet available as a package; however,
2936 most porting efforts are either using it currently or planning to use
2937 it in the near future.  The actual automated builder is packaged as
2938 <package>sbuild</package>, see its description in <ref id="sbuild">.
2939 The complete <package>buildd</package> system also collects a number of as yet unpackaged
2940 components which are currently very useful and in use continually,
2941 such as <prgn>andrea</prgn> and
2942 <prgn>wanna-build</prgn>.
2943           <p>
2944 Some of the data produced by <package>buildd</package> which is
2945 generally useful to porters is available on the web at <url
2946 id="&url-buildd;">.  This data includes nightly updated information
2947 from <prgn>andrea</prgn> (source dependencies) and
2948 <package>quinn-diff</package> (packages needing recompilation).
2949           <p>
2950 We are quite proud of this system, since it has so
2951 many possible uses.  Independent development groups can use the system for
2952 different sub-flavors of Debian, which may or may not really be of
2953 general interest (for instance, a flavor of Debian built with <prgn>gcc</prgn>
2954 bounds checking).  It will also enable Debian to recompile entire
2955 distributions quickly.
2956           <p>
2957 The buildds admins of each arch can be contacted at the mail address
2958 $arch@buildd.debian.org.
2959
2960        <sect1 id="packages-arch-specific">When your package is <em>not</em> portable
2961        <p>
2962 Some packages still have issues with building and/or working on some
2963 of the architectures supported by Debian, and cannot be ported at all,
2964 or not within a reasonable amount of time. An example is a package that
2965 is SVGA-specific (only i386), or uses other hardware-specific features
2966 not supported on all architectures.
2967        <p>
2968 In order to prevent broken packages from being uploaded to the archive, and
2969 wasting buildd time, you need to do a few things:
2970        <p>
2971       <list>
2972       <item>
2973        <p>
2974 First, make sure your package <em>does</em> fail to build on
2975 architectures that it cannot support.
2976 There are a few ways to achieve this.
2977 The preferred way is to have a small testsuite during build time
2978 that will test the functionality, and fail if it doesn't work.
2979 This is a good idea anyway,
2980 as this will prevent (some) broken uploads on all architectures,
2981 and also will allow the package to build
2982 as soon as the required functionality is available.
2983        <p>
2984 Additionally, if you believe the list of supported architectures is
2985 pretty constant, you should change 'any' to a list of supported
2986 architectures in debian/control.  This way, the build will fail also,
2987 and indicate this to a human reader without actually trying.
2988       <item>
2989        <p>
2990 In order to prevent autobuilders from needlessly trying to build your
2991 package, it must be included in <file>packages-arch-specific</file>, a
2992 list used by the <prgn>wanna-build</prgn> script.
2993 The current version is available as
2994 <url id="http://cvs.debian.org/srcdep/Packages-arch-specific?cvsroot=dak">;
2995 please see the top of the file for whom to contact for changes.
2996       </list>
2997        <p>
2998 Please note that it is insufficient to only add your package to
2999 Packages-arch-specific
3000 without making it fail to build on unsupported architectures:
3001 A porter or any other person trying to build your package might
3002 accidently upload it without noticing it doesn't work.
3003 If in the past some binary packages were uploaded on unsupported architectures,
3004 request their removal by filing a bug against
3005 <package>ftp.debian.org</package>
3006
3007
3008     <sect id="nmu">Non-Maintainer Uploads (NMUs)
3009       <p>
3010 Under certain circumstances it is necessary for someone other than the
3011 official package maintainer to make a release of a package. This is
3012 called a non-maintainer upload, or NMU.
3013        <p>
3014 This section handles only source NMUs, i.e. NMUs which upload a new
3015 version of the package. For binary-only NMUs by porters or QA members,
3016 please see <ref id="binary-only-nmu">.
3017 If a buildd builds and uploads a package,
3018 that too is strictly speaking a binary NMU.
3019 See <ref id="buildd"> for some more information.
3020         <p>
3021 The main reason why NMUs are done is when a
3022 developer needs to fix another developer's package in order to
3023 address serious problems or crippling bugs
3024 or when the package maintainer is unable to release a fix
3025 in a timely fashion.
3026         <p>
3027 First and foremost, it is critical that NMU patches to source should
3028 be as non-disruptive as possible.  Do not do housekeeping tasks, do
3029 not change the name of modules or files, do not move directories; in
3030 general, do not fix things which are not broken.  Keep the patch as
3031 small as possible.  If things bother you aesthetically, talk to the
3032 Debian maintainer, talk to the upstream maintainer, or submit a bug.
3033 However, aesthetic changes must <em>not</em> be made in a non-maintainer
3034 upload.
3035         <p>
3036 And please remember the Hippocratic Oath: "Above all, do no harm."  It
3037 is better to leave a package with an open grave bug than applying a
3038 non-functional patch, or one that hides the bug instead of resolving
3039 it.
3040
3041
3042       <sect1 id="nmu-guidelines">How to do a NMU
3043         <p>
3044 NMUs which fix important, serious or higher severity bugs are encouraged
3045 and accepted.
3046 You should endeavor to reach the current maintainer of the package; they
3047 might be just about to upload a fix for the problem, or have a better
3048 solution.
3049         <p>
3050 NMUs should be made to assist a package's maintainer in resolving bugs.
3051 Maintainers should be thankful for that help, and NMUers should respect
3052 the decisions of maintainers, and try to personally help the maintainer by
3053 their work.
3054         <p>
3055 A NMU should follow all conventions, written down in this section.
3056 For an upload to testing or unstable, this order of steps is recommended:
3057         <p>
3058 <list>
3059             <item>
3060 Make sure that the package's bugs that the NMU is meant to address are all
3061 filed in the Debian Bug Tracking System (BTS).
3062 If they are not, submit them immediately.
3063             <item>
3064 Wait a few days for the response from the maintainer. If you don't get
3065 any response, you may want to help them by sending the patch that fixes
3066 the bug. Don't forget to tag the bug with the "patch" keyword.
3067             <item>
3068 Wait a few more days. If you still haven't got an answer from the
3069 maintainer, send them a mail announcing your intent to NMU the package.
3070 Prepare an NMU as described in this section, and test it
3071 carefully on your machine (cf. <ref id="sanitycheck">).
3072 Double check that your patch doesn't have any unexpected side effects.
3073 Make sure your patch is as small and as non-disruptive as it can be.  
3074             <item>
3075 Upload your package to incoming in <file>DELAYED/7-day</file> (cf.
3076 <ref id="delayed-incoming">), send the final patch to the maintainer via
3077 the BTS, and explain to them that they have 7 days to react if they want
3078 to cancel the NMU.
3079             <item>
3080 Follow what happens, you're responsible for any bug that you introduced
3081 with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS)
3082 to stay informed of the state of the package after your NMU.
3083 </list>
3084         <p>
3085 At times, the release manager or an organized group of developers can
3086 announce a certain period of time in which the NMU rules are relaxed.
3087 This usually involves shortening the period during which one is to wait
3088 before uploading the fixes, and shortening the DELAYED period. It is
3089 important to notice that even in these so-called "bug squashing party"
3090 times, the NMU'er has to file bugs and contact the developer first,
3091 and act later.
3092 Please see <ref id="qa-bsp"> for details.
3093         <p>
3094 For the testing distribution, the rules may be changed by the release
3095 managers. Please take additional care, and acknowledge that the usual way
3096 for a package to enter testing is through unstable.
3097         <p>
3098 For the stable distribution, please take extra care. Of course, the release
3099 managers may also change the rules here. Please verify before you upload that
3100 all your changes are OK for inclusion into the next stable release by the
3101 release manager.
3102         <p>
3103 When a security bug is detected, the security team may do an NMU, using
3104 their own rules. Please refer to <ref id="bug-security"> for more
3105 information.
3106         <p>
3107 For the differences for Porters NMUs, please see 
3108 <ref id="source-nmu-when-porter">.
3109         <p>
3110 Of course, it is always possible to agree on special rules with a maintainer
3111 (like the maintainer asking "please upload this fix directly for me, and no
3112 diff required").
3113
3114
3115         <sect1 id="nmu-version">NMU version numbering
3116           <p>
3117 Whenever you have made a change to a package, no matter how trivial,
3118 the version number needs to change.  This enables our packing system
3119 to function.
3120           <p>
3121 If you are doing a non-maintainer upload (NMU), you should add a new
3122 minor version number to the <var>debian-revision</var> part of the
3123 version number (the portion after the last hyphen).  This extra minor
3124 number will start at `1'.  For example, consider the package `foo',
3125 which is at version 1.1-3.  In the archive, the source package control
3126 file would be <file>foo_1.1-3.dsc</file>.  The upstream version is
3127 `1.1' and the Debian revision is `3'.  The next NMU would add a new
3128 minor number `.1' to the Debian revision; the new source control file
3129 would be <file>foo_1.1-3.1.dsc</file>.
3130           <p>
3131 The Debian revision minor number is needed to avoid stealing one of
3132 the package maintainer's version numbers, which might disrupt their
3133 work.  It also has the benefit of making it visually clear that a
3134 package in the archive was not made by the official maintainer.
3135           <p>
3136 If there is no <var>debian-revision</var> component in the version
3137 number then one should be created, starting at `0.1'.  If it is
3138 absolutely necessary for someone other than the usual maintainer to
3139 make a release based on a new upstream version then the person making
3140 the release should start with the <var>debian-revision</var> value
3141 `0.1'.  The usual maintainer of a package should start their
3142 <var>debian-revision</var> numbering at `1'. 
3143         <p>
3144 If you upload a package to testing or stable, sometimes, you need to
3145 "fork" the version number tree. For this, version numbers like
3146 1.1-3sarge0.1 could be used.
3147
3148
3149         <sect1 id="nmu-changelog">
3150           <heading>Source NMUs must have a new changelog entry</heading>
3151           <p>
3152 Anyone who is doing a source NMU must create a changelog entry,
3153 describing which bugs are fixed by the NMU, and generally why the NMU
3154 was required and what it fixed.  The changelog entry will have the
3155 email address of the person who uploaded it in the log entry
3156 and the NMU version number in it.
3157           <p>
3158 By convention, source NMU changelog entries start with the line
3159 <example>
3160   * Non-maintainer upload
3161 </example>
3162
3163
3164         <sect1 id="nmu-patch">Source NMUs and the Bug Tracking System
3165           <p>
3166 Maintainers other than the official package maintainer should make as
3167 few changes to the package as possible, and they should always send a
3168 patch as a unified context diff (<tt>diff -u</tt>) detailing their
3169 changes to the Bug Tracking System.
3170           <p>
3171 What if you are simply recompiling the package? If you just need to
3172 recompile it for a single architecture, then you may do a binary-only
3173 NMU as described in <ref id="binary-only-nmu"> which doesn't require any
3174 patch to be sent. If you want the package to be recompiled for all
3175 architectures, then you do a source NMU as usual and you will have to
3176 send a patch.
3177           <p>
3178 If the source NMU (non-maintainer upload) fixes some existing bugs,
3179 these bugs should be tagged <em>fixed</em> in the Bug Tracking
3180 System rather than closed.  By convention, only the official package
3181 maintainer or the original bug submitter close bugs.
3182 Fortunately, Debian's archive system recognizes NMUs and thus marks
3183 the bugs fixed in the NMU appropriately if the person doing the NMU
3184 has listed all bugs in the changelog with the <tt>Closes:
3185 bug#<var>nnnnn</var></tt> syntax (see <ref id="upload-bugfix"> for
3186 more information describing how to close bugs via the changelog).
3187 Tagging the bugs <em>fixed</em> ensures that everyone knows that the
3188 bug was fixed in an NMU; however the bug is left open until the
3189 changes in the NMU are incorporated officially into the package by
3190 the official package maintainer.
3191           <p>
3192 Also, after doing an NMU, you have to send
3193 the information to the existing bugs that are fixed by your NMU,
3194 including the unified diff.
3195 Alternatively you can open a new bug and include a
3196 patch showing all the changes you have made.
3197 The normal maintainer will either apply the patch or employ an alternate
3198 method of fixing the problem.  Sometimes bugs are fixed independently
3199 upstream, which is another good reason to back out an NMU's patch.
3200 If the maintainer decides not to apply the NMU's patch but to release a
3201 new version, the maintainer needs to ensure that the new upstream version
3202 really fixes each problem that was fixed in the non-maintainer release.
3203           <p>
3204 In addition, the normal maintainer should <em>always</em> retain the
3205 entry in the changelog file documenting the non-maintainer upload --
3206 and of course, also keep the changes.
3207 If you revert some of the changes,
3208 please reopen the relevant bug reports.
3209
3210
3211         <sect1 id="nmu-build">Building source NMUs
3212           <p>
3213 Source NMU packages are built normally.  Pick a distribution using the
3214 same rules as found in <ref id="distribution">, follow the other
3215 instructions in <ref id="upload">.
3216           <p>
3217 Make sure you do <em>not</em> change the value of the maintainer in
3218 the <file>debian/control</file> file.  Your name as given in the NMU entry of
3219 the <file>debian/changelog</file> file will be used for signing the
3220 changes file.
3221
3222       <sect1 id="ack-nmu">Acknowledging an NMU
3223         <p>
3224 If one of your packages has been NMU'ed, you have to incorporate the
3225 changes in your copy of the sources. This is easy, you just have
3226 to apply the patch that has been sent to you. Once this is done, you
3227 have to close the bugs that have been tagged fixed by the NMU. The easiest
3228 way is to use the <tt>-v</tt> option of <prgn>dpkg-buildpackage</prgn>,
3229 as this allows you to include just all changes since your last maintainer
3230 upload. Alternatively, you
3231 can close them manually by sending the required mails to the
3232 BTS or by adding the required <tt>closes: #nnnn</tt> in the changelog
3233 entry of your next upload.
3234         <p>
3235 In any case, you should not be upset by the NMU. An NMU is not a
3236 personal attack against the maintainer. It is a proof that
3237 someone cares enough about the package that they were willing to help
3238 you in your work, so you should be thankful. You may also want to
3239 ask them if they would be interested in helping you on a more frequent
3240 basis as co-maintainer or backup maintainer
3241 (see <ref id="collaborative-maint">).
3242
3243       <sect1 id="nmu-vs-qa">NMU vs QA uploads
3244         <p>
3245 Unless you know the maintainer is still active, it is wise to check the
3246 package to see if it has been orphaned.  The current list of orphaned
3247 packages which haven't had their maintainer set correctly is available at
3248 <url id="&url-debian-qa-orphaned;">.  If you perform an NMU on an
3249 improperly orphaned package, please set the maintainer to ``Debian QA Group
3250 &lt;packages@qa.debian.org&gt;''.
3251
3252       <sect1 id="nmu-who">Who can do an NMU
3253         <p>
3254 Only official, registered Debian Developers can do binary or source
3255 NMUs.  A Debian Developer is someone who has their key in the
3256 Debian key ring.  Non-developers, however, are encouraged to download
3257 the source package and start hacking on it to fix problems; however,
3258 rather than doing an NMU, they should just submit worthwhile patches
3259 to the Bug Tracking System.  Maintainers almost always appreciate
3260 quality patches and bug reports.
3261
3262       <sect1 id="nmu-terms">Terminology
3263         <p>
3264 There are two new terms used throughout this section: ``binary-only NMU''
3265 and ``source NMU''.  These terms are used with specific technical
3266 meaning throughout this document.  Both binary-only and source NMUs are
3267 similar, since they involve an upload of a package by a developer who
3268 is not the official maintainer of that package.  That is why it's a
3269 <em>non-maintainer</em> upload.
3270         <p>
3271 A source NMU is an upload of a package by a developer who is not the
3272 official maintainer, for the purposes of fixing a bug in the package.
3273 Source NMUs always involves changes to the source (even if it is just
3274 a change to <file>debian/changelog</file>).  This can be either a
3275 change to the upstream source, or a change to the Debian bits of the
3276 source.  Note, however, that source NMUs may also include
3277 architecture-dependent packages, as well as an updated Debian diff.
3278         <p>
3279 A binary-only NMU is a recompilation and upload of a binary package
3280 for a given architecture.  As such, it is usually part of a porting
3281 effort.  A binary-only NMU is a non-maintainer uploaded binary version
3282 of a package, with no source changes required.  There are many cases
3283 where porters must fix problems in the source in order to get them to
3284 compile for their target architecture; that would be considered a
3285 source NMU rather than a binary-only NMU.  As you can see, we don't
3286 distinguish in terminology between porter NMUs and non-porter NMUs.
3287         <p>
3288 Both classes of NMUs, source and binary-only, can be lumped under the
3289 term ``NMU''.  However, this often leads to confusion, since most
3290 people think ``source NMU'' when they think ``NMU''.  So it's best to
3291 be careful: always use ``binary NMU'' or ``binNMU'' for binary-only
3292 NMUs.
3293
3294
3295     <sect id="collaborative-maint">
3296         <heading>Collaborative maintenance</heading>
3297         <p>
3298 "Collaborative maintenance" is a term describing the sharing of Debian
3299 package maintenance duties by several people.  This collaboration is
3300 almost always a good idea, since it generally results in higher quality and
3301 faster bug fix turnaround times.  It is strongly recommended that
3302 packages with a priority of <tt>Standard</tt> or which are part of
3303 the base set have co-maintainers.</p>
3304         <p>
3305 Generally there is a primary maintainer and one or more
3306 co-maintainers.  The primary maintainer is the person whose name is listed in
3307 the <tt>Maintainer</tt> field of the <file>debian/control</file> file.
3308 Co-maintainers are all the other maintainers.</p>
3309         <p>
3310 In its most basic form, the process of adding a new co-maintainer is
3311 quite easy:
3312 <list>
3313             <item>
3314               <p>
3315 Setup the co-maintainer with access to the sources you build the
3316 package from.  Generally this implies you are using a network-capable
3317 version control system, such as <prgn>CVS</prgn> or
3318 <prgn>Subversion</prgn>.</p>
3319             </item>
3320             <item>
3321               <p>
3322 Add the co-maintainer's correct maintainer name and address to the
3323 <tt>Uploaders</tt> field in the global part of the
3324 <file>debian/control</file> file.
3325 <example>
3326 Uploaders: John Buzz &lt;jbuzz@debian.org&gt;, Adam Rex &lt;arex@debian.org&gt;
3327 </example>
3328 </p>
3329             </item>
3330             <item>
3331               <p>
3332 Using the PTS (<ref id="pkg-tracking-system">), the co-maintainers
3333 should subscribe themselves to the appropriate source package.</p>
3334             </item>
3335           </list></p>
3336         <p>
3337 Collaborative maintenance can often be further eased by the use of
3338 tools on Alioth (see <ref id="alioth">).
3339       </sect>
3340
3341     <sect id="testing">
3342         <heading>The testing distribution</heading>
3343         <p>
3344         <sect1 id="testing-basics">
3345         <heading>Basics</heading>
3346         <p>
3347 Packages are usually installed into the `testing' distribution after they
3348 have undergone some degree of testing in unstable.
3349         <p>
3350 They must be in sync on all architectures and
3351 mustn't have dependencies that make them uninstallable; they also have to
3352 have generally no known release-critical bugs at the time they're
3353 installed into testing.
3354 This way, `testing' should always be close to being a release candidate.
3355 Please see below for details.
3356         <sect1 id="testing-unstable">
3357         <heading>Updates from unstable</heading>
3358         <p>
3359 The scripts that update the <em>testing</em> distribution are run each
3360 day after the installation of the updated packages;
3361 these scripts are called <em>britney</em>.
3362 They generate the
3363 <file>Packages</file> files for the <em>testing</em> distribution, but
3364 they do so in an intelligent manner; they try to avoid any inconsistency
3365 and to use only non-buggy packages.
3366         <p>
3367 The inclusion of a package from <em>unstable</em> is conditional on
3368 the following:
3369 <list>
3370     <item>
3371 The package must have been available in <em>unstable</em> for 2, 5 or 10
3372 days, depending on the urgency (high, medium or low).
3373 Please note that the urgency is sticky, meaning that the highest
3374 urgency uploaded since the previous testing transition is taken into account.
3375 Those delays may be doubled during a freeze, or testing transitions may be
3376 switched off altogether;
3377     <item>
3378 It must have the same number or fewer release-critical bugs than the version currently available
3379 in <em>testing</em>;
3380     <item>
3381 It must be available on all architectures on which it has previously
3382 been built in unstable. <ref id="madison"> may be of interest to
3383 check that information;
3384     <item>
3385 It must not break any dependency of a package which is already available
3386 in <em>testing</em>;
3387     <item>
3388 The packages on which it depends must either be available in <em>testing</em>
3389 or they must be accepted into <em>testing</em> at the same time (and they will
3390 be if they fulfill all the necessary criteria);
3391 </list>
3392         <p>
3393 To find out whether a package is progressing into testing or not, see the
3394 testing script output on the <url name="web page of the testing distribution"
3395 id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn>
3396 which is in the <package>devscripts</package> package. This utility can
3397 easily be used in a <manref name="crontab" section="5"> to keep yourself
3398 informed of the progression of your packages into <em>testing</em>.
3399         <p>
3400 The <file>update_excuses</file> file does not always give the precise reason
3401 why the package is refused; you may have to find it on your own by looking
3402 for what would break with the inclusion of the package. The
3403 <url id="&url-testing-maint;" name="testing web page"> gives some more
3404 information about the usual problems which may be causing such troubles.
3405         <p>
3406 Sometimes, some packages never enter <em>testing</em> because the set of
3407 inter-relationship is too complicated and cannot be sorted out
3408 by the scripts. See below for details.
3409         <p>
3410 Some further dependency analysis is shown on
3411 <url id="http://bjorn.haxx.se/debian/"> &mdash; but be warned,
3412 this page also shows build dependencies which
3413 are not considered by britney.
3414
3415         <sect2 id="outdated">
3416         <heading>out-of-date</heading>
3417         <p>
3418 <!-- FIXME: better rename this file than document rampant professionalism? -->
3419 For the testing migration script, "outdated" means: There are different
3420 versions in unstable for the release architectures (except for the
3421 architectures in fuckedarches; fuckedarches is a list of architectures
3422 that don't keep up (in update_out.py), but currently, it's empty).
3423 "outdated" has nothing whatsoever to do with the architectures this package
3424 has in testing.
3425         <p>
3426 Consider this example:
3427         <p>
3428         <example>
3429 foo      | alpha | arm 
3430 ---------+-------+----
3431 testing  |   1   |  -
3432 unstable |   1   |  2
3433 </example>
3434         <p>
3435 The package is out of date on alpha in unstable, and will not go to
3436 testing. And removing foo from testing would not help at all, the package
3437 is still out of date on alpha, and will not propagate to testing.
3438         <p>
3439 However, if ftp-master removes a package in unstable (here on arm):
3440         <p>
3441         <example>
3442 foo      | alpha | arm | hurd-i386
3443 ---------+-------+-----+----------
3444 testing  |   1   |  1  |    -
3445 unstable |   2   |  -  |    1
3446         </example>
3447         <p>
3448 In this case, the package is up to date on all release architectures in
3449 unstable (and the extra hurd-i386 doesn't matter, as it's not a release
3450 architecture).
3451         <p>
3452 Sometimes, the question is raised if it is possible to allow packages in
3453 that are not yet built on all architectures: No. Just plainly no. (Except
3454 if you maintain glibc or so.)
3455
3456         <sect2 id="removals">
3457         <heading>Removals from testing</heading>
3458         <p>
3459 Sometimes, a package is removed to allow another package in: This happens
3460 only to allow <em>another</em> package to go in if it's ready in every other
3461 sense. Suppose e.g. that <em>a</em> cannot be installed with the new version of
3462 <em>b</em>; then <em>a</em> may be removed to allow <em>b</em> in.
3463         <p>
3464 Of course, there is another reason to remove a package from testing: It's
3465 just too buggy (and having a single RC-bug is enough to be in this state).
3466         <p>
3467 Furthermore, if a package has been removed from unstable,
3468 and no package in testing depends on it any more,
3469 then it will automatically be removed.
3470
3471
3472         <sect2 id="circular">
3473         <heading>circular dependencies</heading>
3474         <p>
3475 A situation which is not handled very well by britney is if package <em>a</em>
3476 depends on the new version of package <em>b</em>, and vice versa.
3477         <p>
3478 An example of this is:
3479         <p>
3480         <example>
3481   | testing         |  unstable
3482 --+-----------------+------------
3483 a | 1; depends: b=1 |  2; depends: b=2
3484 b | 1; depends: a=1 |  2; depends: a=2
3485         </example>
3486         <p>
3487 Neither package <em>a</em> nor package <em>b</em> is considered for update.
3488         <p>
3489 Currently, this requires some manual hinting from the release team.
3490 Please contact them by sending mail to &email-debian-release; if this
3491 happens to one of your packages.
3492
3493
3494         <sect2>
3495         <heading>influence of package in testing</heading>
3496         <p>
3497 Generally, there is nothing that the status of a package in testing means
3498 for transition of the next version from unstable to testing, with two
3499 exceptions: If the RC-bugginess of the package goes down, it may go in
3500 even if it is still RC-buggy. The second exception is if the version
3501 of the package in testing is out of sync on the different arches: Then
3502 any arch might just upgrade to the version of the source package;
3503 however, this can happen only if the package was previously forced
3504 through, the arch is in fuckedarches, or there was no binary package of that
3505 arch present in unstable at all during the testing migration.
3506         <p>
3507 In summary this means: The only influence that a package being in testing
3508 has on a new version of the same package is that the new version might
3509 go in easier.
3510
3511         <sect2 id="details">
3512         <heading>details</heading>
3513         <p>
3514 If you are interested in details, this is how britney works:
3515         <p>
3516 The packages are looked at to determine whether they are valid
3517 candidates. This gives the "update excuses". The most common reasons
3518 why a package is not considered are too young, RC-bugginess, and out of
3519 date on some arches. For this part of britney,
3520 the release managers have hammers
3521 of various sizes to force britney to consider a package. (Also, the base
3522 freeze is coded in that part of britney.) (There is a similar thing
3523 for binary-only updates, but this is not described here. If you're
3524 interested in that, please peruse the code.)
3525         <p>
3526 Now, the more complex part happens: Britney tries to update testing with
3527 the valid candidates; first, each package alone, and then larger and even
3528 larger sets of packages together. Each try is accepted if testing is not
3529 more uninstallable after the update than before. (Before and after this part,
3530 some hints are processed; but as only release masters can hint, this is
3531 probably not so important for you.)
3532         <p>
3533 If you want to see more details, you can look it up on
3534 merkel:/org/ftp.debian.org/testing/update_out/ (or there in
3535 ~aba/testing/update_out to see a setup with a smaller packages file). Via
3536 web, it's at <url
3537 id="http://ftp-master.debian.org/testing/update_out_code/">
3538         <p>
3539 The hints are available via <url
3540 id="http://ftp-master.debian.org/testing/hints/">.
3541
3542
3543         <sect1 id="t-p-u">
3544           <heading>Direct updates to testing</heading>
3545           <p>
3546 The testing distribution is fed with packages from unstable according to the rules
3547 explained above. However, in some cases, it is necessary to upload
3548 packages built only for testing. For that, you may want to
3549 upload to <em>testing-proposed-updates</em>.
3550           <p>
3551 Keep in mind that packages uploaded there are not automatically processed, they
3552 have to go through the hands of the release manager. So you'd better have a good
3553 reason to upload there. In order to know what a good reason is in the
3554 release managers' eyes, you should read the instructions that they regularly
3555 give on &email-debian-devel-announce;.
3556           <p>
3557 You should not upload to <em>testing-proposed-updates</em> when you can update your
3558 packages through <em>unstable</em>. If you can't (for example because you have a
3559 newer development version in unstable), you may use this facility,
3560 but it is recommended that you ask for authorization from
3561 the release manager first.
3562 Even if a package is
3563 frozen, updates through unstable are possible, if the upload via unstable
3564 does not pull in any new dependencies.
3565           <p>
3566 Version numbers are usually selected by adding the codename of the testing
3567 distribution and a running number, like 1.2sarge1 for the first upload
3568 through testing-proposed-updates of package version 1.2.
3569         <p>
3570 Please make sure you didn't miss any of these items in your upload:
3571 <list>
3572 <item> Make sure that your package really needs to go through
3573 <em>testing-proposed-updates</em>, and can't go through unstable;
3574 <item> Make sure that you included only the minimal amount of changes;
3575 <item> Make sure that you included an appropriate explanation in the
3576 changelog;
3577 <item> Make sure that you've written <em>testing</em> or
3578 <em>testing-proposed-updates</em> into your target distribution;
3579 <item> Make sure that you've built and tested your package in
3580 <em>testing</em>, not in <em>unstable</em>;
3581 <item> Make sure that your version number is higher than the version in
3582 <em>testing</em> and <em>testing-proposed-updates</em>, and lower than in
3583 <em>unstable</em>;
3584 <item> After uploading and successful build on all platforms, contact the
3585 release team at &email-debian-release; and ask them to approve your upload.
3586 </list>
3587
3588
3589         <sect1 id="faq">
3590         <heading>Frequently asked questions</heading>
3591           <p>
3592
3593         <sect2 id="rc">
3594         <heading>What are release-critical bugs, and how do they get counted?</heading>
3595           <p>
3596 All bugs of some higher severities are by default considered release-critical; currently, these are critical, grave, and serious bugs.
3597           <p>
3598 Such bugs are presumed to have an impact on the chances that the package will be released with the stable release of Debian: in general, if a package has open release-critical bugs filed on it, it won't get into "testing", and consequently won't be released in "stable".
3599           <p>
3600 The unstable bug count are all release-critical bugs
3601 without either any release-tag (such as potato, woody) or with release-tag sid;
3602 also, only if they are neither fixed nor set to sarge-ignore.
3603 The "testing" bug count for a package is considered to be roughly
3604 the bug count of unstable count at the last point
3605 when the "testing" version equalled the "unstable" version.
3606         <p>
3607 This will change post-sarge, as soon as we have versions in the bug tracking system.
3608
3609
3610         <sect2>
3611         <heading>How could installing a package into "testing" possibly break other packages?</heading>
3612           <p>
3613 The structure of the distribution archives is such that they can only contain one version of a package; a package is defined by its name. So when the source package acmefoo is installed into "testing", along with its binary packages acme-foo-bin, acme-bar-bin, libacme-foo1 and libacme-foo-dev, the old version is removed.
3614           <p>
3615 However, the old version may have provided a binary package with an old soname of a library, such as libacme-foo0. Removing the old acmefoo will remove libacme-foo0, which will break any packages which depend on it.
3616           <p>
3617 Evidently, this mainly affects packages which provide changing sets of binary packages in different versions (in turn, mainly libraries). However, it will also affect packages upon which versioned dependencies have been declared of the ==, <=, or << varieties.
3618           <p>
3619 When the set of binary packages provided by a source package change in this way, all the packages that depended on the old binaries will have to be updated to depend on the new binaries instead. Because installing such a source package into "testing" breaks all the packages that depended on it in "testing", some care has to be taken now: all the depending packages must be updated and ready to be installed themselves so that they won't be broken, and, once everything is ready, manual intervention by the release manager or an assistant is normally required.
3620           <p>
3621 If you are having problems with complicated groups of packages like this, contact debian-devel or debian-release for help.
3622       </sect>
3623
3624   <chapt id="best-pkging-practices">
3625     <heading>Best Packaging Practices</heading>
3626     <p>
3627 Debian's quality is largely due to the <url id="&url-debian-policy;"
3628 name="Debian Policy">, which defines explicit baseline requirements
3629 which all Debian packages must fulfill.  Yet there is also a shared
3630 history of experience which goes beyond the Debian Policy, an
3631 accumulation of years of experience in packaging.  Many very
3632 talented people have created great tools, tools which help you, the
3633 Debian maintainer, create and maintain excellent packages.
3634     <p>
3635 This chapter provides some best practices for Debian developers.  All
3636 recommendations are merely that, and are not requirements or policy.
3637 These are just some subjective hints, advice and pointers collected
3638 from Debian developers.  Feel free to pick and choose whatever works
3639 best for you.
3640
3641     <sect id="bpp-debian-rules">
3642         <heading>Best practices for <file>debian/rules</file></heading>
3643         <p>
3644 The following recommendations apply to the <file>debian/rules</file>
3645 file.  Since <file>debian/rules</file> controls the build process and
3646 selects the files which go into the package (directly or indirectly),
3647 it's usually the file maintainers spend the most time on.
3648
3649         <sect1 id="helper-scripts">Helper scripts
3650         <p>
3651 The rationale for using helper scripts in <file>debian/rules</file> is
3652 that they let maintainers use and share common logic among many packages.
3653 Take for instance the question of installing menu entries: you need to
3654 put the file into <file>/usr/lib/menu</file> (or
3655 <file>/usr/lib/menu</file> for executable binary menufiles, if this is needed),
3656 and add commands to the
3657 maintainer scripts to register and unregister the menu entries.  Since
3658 this is a very common thing for packages to do, why should each
3659 maintainer rewrite all this on their own, sometimes with bugs?  Also,
3660 supposing the menu directory changed, every package would have to be
3661 changed.
3662         <p>
3663 Helper scripts take care of these issues.  Assuming you comply with
3664 the conventions expected by the helper script, the helper takes care
3665 of all the details.  Changes in policy can be made in the helper
3666 script; then packages just need to be rebuilt with the new version of
3667 the helper and no other changes.
3668         <p>
3669 <ref id="tools"> contains a couple of different helpers. The most
3670 common and best (in our opinion) helper system is
3671 <package>debhelper</package>.  Previous helper systems, such as
3672 <package>debmake</package>, were "monolithic": you couldn't pick and
3673 choose which part of the helper you found useful, but had to use the
3674 helper to do everything.  <package>debhelper</package>, however, is a
3675 number of separate little <prgn>dh_*</prgn> programs.  For instance,
3676 <prgn>dh_installman</prgn> installs and compresses man pages,
3677 <prgn>dh_installmenu</prgn> installs menu files, and so on.  Thus, it
3678 offers enough flexibility to be able to use the little helper scripts,
3679 where useful, in conjunction with hand-crafted commands in
3680 <file>debian/rules</file>.
3681         <p>
3682 You can get started with <package>debhelper</package> by reading
3683 <manref name="debhelper" section="1">, and looking at the examples
3684 that come with the package.  <prgn>dh_make</prgn>, from the
3685 <package>dh-make</package> package (see <ref id="dh-make">), can be
3686 used to convert a "vanilla" source package to a
3687 <package>debhelper</package>ized package.  This shortcut, though,
3688 should not convince you that you do not need to bother understanding
3689 the individual <prgn>dh_*</prgn> helpers.  If you are going to use a
3690 helper, you do need to take the time to learn to use that helper, to
3691 learn its expectations and behavior.
3692         <p>
3693 Some people feel that vanilla <file>debian/rules</file> files are
3694 better, since you don't have to learn the intricacies of any helper
3695 system.  This decision is completely up to you.  Use what works for
3696 you.  Many examples of vanilla <file>debian/rules</file> files are
3697 available at <url id="&url-rules-files;">.
3698
3699
3700         <sect1 id="multiple-patches">
3701           <heading>Separating your patches into multiple files</heading>
3702           <p>
3703 Big, complex packages may have many bugs that you need to deal with.
3704 If you correct a number of bugs directly in the source, and you're not
3705 careful, it can get hard to differentiate the various patches that you
3706 applied.  It can get quite messy when you have to update the package
3707 to a new upstream version which integrates some of the fixes (but not
3708 all).  You can't take the total set of diffs (e.g., from
3709 <file>.diff.gz</file>) and work out which patch sets to back out as a
3710 unit as bugs are fixed upstream.
3711         <p>
3712 Unfortunately, the packaging system as such currently doesn't provide for
3713 separating the patches into several files. Nevertheless, there are ways to
3714 separate patches: the patch files are shipped within the Debian patch file
3715 (<file>.diff.gz</file>), usually within the <file>debian/</file> directory.
3716 The only difference is that they aren't applied immediately by dpkg-source,
3717 but by the <tt>build</tt> rule of <file>debian/rules</file>. Conversely,
3718 they are reverted in the <tt>clean</tt> rule.
3719         <p>
3720 <prgn>dbs</prgn> is one of the more popular approaches to this. It does all
3721 of the above, and provides a facility for creating new and updating old
3722 patches. See the package <package>dbs</package> for more information and
3723 <package>hello-dbs</package> for an example.
3724         <p>
3725 <prgn>dpatch</prgn> also provides these facilities, but it's intended to be
3726 even easier to use. See the package <package>dpatch</package> for
3727 documentation and examples (in <file>/usr/share/doc/dpatch</file>).
3728
3729
3730         <sect1 id="multiple-binary">Multiple binary packages
3731         <p>
3732 A single source package will often build several binary packages,
3733 either to provide several flavors of the same software (e.g.,
3734 the <package>vim</package> source package) or to make several small
3735 packages instead of a big one (e.g., so the user can install only the
3736 subset needed, and thus save some disk space).
3737         <p>
3738 The second case can be easily managed in <file>debian/rules</file>.
3739 You just need to move the appropriate files from the build directory
3740 into the package's temporary trees.  You can do this using
3741 <prgn>install</prgn> or <prgn>dh_install</prgn>
3742 from <package>debhelper</package>.  Be sure to check the different
3743 permutations of the various packages, ensuring that you have the
3744 inter-package dependencies set right in <file>debian/control</file>.
3745         <p>
3746 The first case is a bit more difficult since it involves multiple
3747 recompiles of the same software but with different configuration
3748 options. The <package>vim</package> source package is an example of how to manage
3749 this using an hand-crafted <file>debian/rules</file> file.
3750
3751 <!-- &FIXME; Find a good debhelper example with multiple configure/make
3752      cycles -->
3753         </sect1>
3754       </sect>
3755
3756
3757       <sect id="bpp-debian-control">
3758         <heading>Best practices for <file>debian/control</file></heading>
3759         <p>
3760 The following practices are relevant to the
3761 <file>debian/control</file> file.  They supplement the <url
3762 id="&url-debian-policy;ch-binary.html#s-descriptions"
3763 name="Policy on package descriptions">.
3764         <p>
3765 The description of the package, as defined by the corresponding field
3766 in the <file>control</file> file, contains both the package synopsis
3767 and the long description for the package.  <ref id="bpp-desc-basics">
3768 describes common guidelines for both parts of the package description.
3769 Following that, <ref id="bpp-pkg-synopsis"> provides guidelines
3770 specific to the synopsis, and <ref id="bpp-pkg-desc"> contains
3771 guidelines specific to the description.
3772
3773         <sect1 id="bpp-desc-basics">
3774           <heading>General guidelines for package descriptions</heading>
3775           <p>
3776 The package description should be written for the average likely user,
3777 the average person who will use and benefit from the package.  For
3778 instance, development packages are for developers, and can be
3779 technical in their language.  More general-purpose applications, such
3780 as editors, should be written for a less technical user.
3781           <p>
3782 Our review of package descriptions lead us to conclude that most
3783 package descriptions are technical, that is, are not written to make
3784 sense for non-technical users.  Unless your package really is only for
3785 technical users, this is a problem.
3786           <p>
3787 How do you write for non-technical users?  Avoid jargon.  Avoid
3788 referring to other applications or frameworks that the user might not
3789 be familiar with &mdash; "GNOME" or "KDE" is fine, since users are
3790 probably familiar with these terms, but "GTK+" is
3791 probably not.  Try not to assume any knowledge at all.  If you must
3792 use technical terms, introduce them.
3793             <p>
3794 Be objective.  Package descriptions are not the place for advocating
3795 your package, no matter how much you love it.  Remember that the
3796 reader may not care about the same things you care about.
3797           <p>
3798 References to the names of any other software packages, protocol names,
3799 standards, or specifications should use their canonical forms, if one
3800 exists.  For example, use "X Window System", "X11", or "X"; not "X
3801 Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk".
3802 Use "GNOME", not "Gnome".  Use "PostScript", not "Postscript" or
3803 "postscript".
3804           <p>
3805 If you are having problems writing your description, you may wish to
3806 send it along to &email-debian-l10n-english; and request feedback.
3807         </sect1>
3808
3809
3810         <sect1 id="bpp-pkg-synopsis">
3811           <heading>The package synopsis, or short description</heading>
3812             <p>
3813 The synopsis line (the short description) should be concise.  It
3814 must not repeat the package's name (this is policy).
3815             <p>
3816 It's a good idea to think of the synopsis as an appositive clause, not
3817 a full sentence.  An appositive clause is defined in WordNet as a
3818 grammatical relation between a word and a noun phrase that follows,
3819 e.g., "Rudolph the red-nosed reindeer".  The appositive clause here is
3820 "red-nosed reindeer".  Since the synopsis is a clause, rather than a
3821 full sentence, we recommend that it neither start with a capital nor
3822 end with a full stop (period).  It should also not begin with an
3823 article, either definite ("the") or indefinite ("a" or "an").
3824             <p>
3825 It might help to imagine that the synopsis is combined with the
3826 package name in the following way:
3827
3828 <example><var>package-name</var> is a <var>synopsis</var>.</example>
3829
3830 Alternatively, it might make sense to think of it as
3831
3832 <example><var>package-name</var> is <var>synopsis</var>.</example>
3833
3834 or, if the package name itself is a plural (such as
3835 "developers-tools")
3836
3837 <example><var>package-name</var> are <var>synopsis</var>.</example>
3838
3839 This way of forming a sentence from the package name and synopsis
3840 should be considered as a heuristic and not a strict rule.  There are
3841 some cases where it doesn't make sense to try to form a sentence.
3842         </sect1>
3843
3844         <sect1 id="bpp-pkg-desc">
3845           <heading>The long description</heading>
3846             <p>
3847 The long description is the primary information available to the user
3848 about a package before they install it.  It should provide all the
3849 information needed to let the user decide whether to install the
3850 package.  Assume that the user has already read the package synopsis.
3851             <p>
3852 The long description should consist of full and complete sentences.
3853             <p>
3854 The first paragraph of the long description should answer the
3855 following questions: what does the package do?  what task does it help
3856 the user accomplish?  It is important to describe this in a
3857 non-technical way, unless of course the audience for the package is
3858 necessarily technical.
3859             <p>
3860 The following paragraphs should answer the following questions: Why do
3861 I as a user need this package?  What other features does the package
3862 have?  What outstanding features and deficiencies are there compared
3863 to other packages (e.g., "if you need X, use Y instead")?  Is this
3864 package related to other packages in some way that is not handled by
3865 the package manager (e.g., "this is the client for the foo server")?
3866             <p>
3867 Be careful to avoid spelling and grammar mistakes. Ensure that you
3868 spell-check it.  Both <prgn>ispell</prgn> and <prgn>aspell</prgn>
3869 have special modes for checking <file>debian/control</file> files:
3870
3871 <example>ispell -d american -g debian/control</example>
3872 <example>aspell -d en -D -c debian/control</example>
3873             <p>
3874 Users usually expect these questions to be answered in the package
3875 description:
3876         <list>
3877         <item>
3878 What does the package do? If it is an add-on to another package,
3879 then the short description of the package we are an add-on to
3880 should be put in here.
3881         <item>
3882 Why should I want this package?  This is related to the above,
3883 but not the same (this is a mail user agent; this is cool, fast,
3884 interfaces with PGP and LDAP and IMAP, has features X, Y, and Z).
3885         <item>
3886 If this package should not be installed directly, but is pulled in
3887 by another package, this should be mentioned.
3888         <item>
3889 If the package is experimental, or there are other reasons it
3890 should not be used, if there are other packages that should be
3891 used instead, it should be here as well.
3892         <item>
3893 How is this package different from the competition? Is it a better
3894 implementation? more features? different features? Why should I
3895 choose this package.
3896 <!-- FIXME: what's this?
3897 (the second questions is about the class of packages, and
3898 this about this particular package, if you have information related to both).
3899 -->
3900         </list>
3901
3902         </sect1>
3903
3904
3905         <sect1 id="bpp-upstream-info">
3906           <heading>Upstream home page</heading>
3907           <p>
3908 We recommend that you add the URL for the package's home page to the
3909 package description in <file>debian/control</file>.  This information
3910 should be added at the
3911 end of description, using the following format:
3912
3913 <example> .
3914   Homepage: http://some-project.some-place.org/</example>
3915
3916 Note the spaces prepending the line, which serves to break the lines
3917 correctly.  To see an example of how this displays, see <url
3918 id="&url-eg-desc-upstream-info;">.
3919           <p>
3920 If there is no home page for the software, this should naturally be
3921 left out.
3922           <p>
3923 Note that we expect this field will eventually be replaced by a proper
3924 <file>debian/control</file> field understood by <prgn>dpkg</prgn> and
3925 <tt>&packages-host;</tt>.  If you don't want to bother migrating the
3926 home page from the description to this field, you should probably wait
3927 until that is available.
3928  Please make sure that this line matches the regular expression
3929  <tt>/^  Homepage: [^ ]*$/</tt>,
3930  as this allows <file>packages.debian.org</file> to parse it correctly.</p>
3931         </sect1>
3932       </sect>
3933
3934
3935       <sect id="bpp-debian-changelog">
3936         <heading>Best practices for <file>debian/changelog</file></heading>
3937         <p>
3938 The following practices supplement the <url name="Policy on changelog
3939 files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
3940
3941         <sect1 id="bpp-changelog-do">
3942           <heading>Writing useful changelog entries</heading>
3943           <p>
3944 The changelog entry for a package revision documents changes in that
3945 revision, and only them. Concentrate on describing significant and
3946 user-visible changes that were made since the last version.
3947           <p>
3948 Focus on <em>what</em> was changed &mdash; who, how and when are
3949 usually less important.  Having said that, remember to politely
3950 attribute people who have provided notable help in making the package
3951 (e.g., those who have sent in patches).
3952           <p>
3953 There's no need to elaborate the trivial and obvious changes. You can
3954 also aggregate several changes in one entry.  On the other hand, don't
3955 be overly terse if you have undertaken a major change.  Be especially
3956 clear if there are changes that affect the behaviour of the program.
3957 For further explanations, use the <file>README.Debian</file> file.
3958           <p>
3959 Use common English so that the majority of readers can comprehend it.
3960 Avoid abbreviations, "tech-speak" and jargon when explaining changes
3961 that close bugs, especially for bugs filed by users that did not
3962 strike you as particularly technically savvy.  Be polite, don't swear.
3963           <p>
3964 It is sometimes desirable to prefix changelog entries with the names
3965 of the files that were changed.  However, there's no need to
3966 explicitly list each and every last one of the changed files,
3967 especially if the change was small or repetitive.  You may use
3968 wildcards.
3969           <p>
3970 When referring to bugs, don't assume anything.  Say what the problem
3971 was, how it was fixed, and append the "closes: #nnnnn" string.  See
3972 <ref id="upload-bugfix"> for more information.
3973
3974
3975         <sect1 id="bpp-changelog-misconceptions">
3976           <heading>Common misconceptions about changelog entries</heading>
3977           <p>
3978 The changelog entries should <strong>not</strong> document generic
3979 packaging issues ("Hey, if you're looking for foo.conf, it's in
3980 /etc/blah/."), since administrators and users are supposed to be at
3981 least remotely acquainted with how such things are generally arranged
3982 on Debian systems.  Do, however, mention if you change the location of
3983 a configuration file.
3984           <p>
3985 The only bugs closed with a changelog entry should be those that are
3986 actually fixed in the same package revision.  Closing unrelated bugs
3987 in the changelog is bad practice. See <ref id="upload-bugfix">.
3988           <p>
3989 The changelog entries should <strong>not</strong> be used for random
3990 discussion with bug reporters ("I don't see segfaults when starting
3991 foo with option bar; send in more info"), general statements on life,
3992 the universe and everything ("sorry this upload took me so long, but I
3993 caught the flu"), or pleas for help ("the bug list on this package is
3994 huge, please lend me a hand").  Such things usually won't be noticed
3995 by their target audience, but may annoy people who wish to read
3996 information about actual changes in the package.  See <ref
3997 id="bug-answering"> for more information on how to use the bug
3998 tracking system.
3999           <p>
4000 It is an old tradition to acknowledge bugs fixed in non-maintainer
4001 uploads in the first changelog entry of the proper maintainer upload.
4002 As we have version tracking now,
4003 it is enough to keep the NMUed changelog entries and
4004 just mention this fact in your own changelog entry.
4005         </sect1>
4006
4007         <sect1 id="bpp-changelog-errors">
4008           <heading>Common errors in changelog entries</heading>
4009           <p>
4010 The following examples demonstrate some common errors or examples of
4011 bad style in changelog entries.
4012
4013           <p>
4014 <example>
4015   * Fixed all outstanding bugs.
4016 </example>
4017 This doesn't tell readers anything too useful, obviously.
4018
4019           <p>
4020 <example>
4021   * Applied patch from Jane Random.
4022 </example>
4023 What was the patch about?
4024
4025             <p>
4026 <example>
4027   * Late night install target overhaul.
4028 </example>
4029 Overhaul which accomplished what?  Is the mention of late night
4030 supposed to remind us that we shouldn't trust that code?
4031
4032             <p>
4033 <example>
4034   * Fix vsync FU w/ ancient CRTs.
4035 </example>
4036 Too many acronyms, and it's not overly clear what the, uh, fsckup (oops,
4037 a curse word!) was actually about, or how it was fixed.
4038
4039             <p>
4040 <example>
4041   * This is not a bug, closes: #nnnnnn.
4042 </example>
4043 First of all, there's absolutely no need to upload the package to
4044 convey this information; instead, use the bug tracking system.
4045 Secondly, there's no explanation as to why the report is not a bug.
4046
4047             <p>
4048 <example>
4049   * Has been fixed for ages, but I forgot to close; closes: #54321.
4050 </example>
4051 If for some reason you didn't mention the bug number in a previous changelog
4052 entry, there's no problem, just close the bug normally in the BTS. There's
4053 no need to touch the changelog file, presuming the description of the fix is
4054 already in (this applies to the fixes by the upstream authors/maintainers as
4055 well, you don't have to track bugs that they fixed ages ago in your
4056 changelog).
4057
4058             <p>
4059 <example>
4060   * Closes: #12345, #12346, #15432
4061 </example>
4062 Where's the description?  If you can't think of a descriptive message,
4063 start by inserting the title of each different bug.
4064         </sect1>
4065         
4066         <sect1 id="bpp-news-debian">
4067           <heading>Supplementing changelogs with NEWS.Debian files</heading>
4068           <p>
4069 Important news about changes in a package can also be put in NEWS.Debian
4070 files. The news will be displayed by tools like apt-listchanges, before
4071 all the rest of the changelogs. This is the preferred means to let the user
4072 know about significant changes in a package. It is better than using
4073 debconf notes since it is less annoying and the user can go back and refer
4074 to the NEWS.Debian file after the install. And it's better than listing
4075 major changes in README.Debian, since the user can easily miss such notes.
4076           <p>
4077 The file format is the same as a debian changelog file, but leave off
4078 the asterisks and describe each news item with a full paragraph when
4079 necessary rather than the more concise summaries that would go in a
4080 changelog. It's a good idea to run your file through dpkg-parsechangelog to
4081 check its formatting as it will not be automatically checked during build
4082 as the changelog is. Here is an example of a real NEWS.Debian file:
4083 <example>
4084 cron (3.0pl1-74) unstable; urgency=low
4085
4086     The checksecurity script is no longer included with the cron package:
4087     it now has its own package, "checksecurity". If you liked the
4088     functionality provided with that script, please install the new
4089     package.
4090
4091  -- Steve Greenland &lt;stevegr@debian.org&gt;  Sat,  6 Sep 2003 17:15:03 -0500
4092 </example>
4093           <p>
4094 The NEWS.Debian file is installed as
4095 /usr/share/doc/&lt;package&gt;/NEWS.Debian.gz. It is compressed, and
4096 always has that name even in Debian native packages. If you use debhelper,
4097 dh_installchangelogs will install debian/NEWS files for you.
4098           <p>
4099 Unlike changelog files, you need not update NEWS.Debian files with every
4100 release. Only update them if you have something particularly newsworthy
4101 that user should know about. If you have no news at all, there's no need
4102 to ship a NEWS.Debian file in your package. No news is good news!
4103       </sect>
4104
4105 <!--
4106         <sect1 id="pkg-mgmt-cvs">Managing a package with CVS
4107         <p>
4108         &FIXME; presentation of cvs-buildpackage, updating sources
4109         via CVS (debian/rules refresh).
4110         <url id="http://www.debian.org/devel/cvs_packages">
4111 -->
4112
4113
4114       <sect id="bpp-debian-maint-scripts">
4115         <heading>Best practices for maintainer scripts</heading>
4116         <p>
4117 Maintainer scripts include the files <file>debian/postinst</file>,
4118 <file>debian/preinst</file>, <file>debian/prerm</file> and
4119 <file>debian/postrm</file>.  These scripts take care of any package
4120 installation or deinstallation setup which isn't handled merely by the
4121 creation or removal of files and directories.  The following
4122 instructions supplement the <url id="&url-debian-policy;" name="Debian
4123 Policy">.
4124         <p>
4125 Maintainer scripts must be idempotent.  That means that you need to
4126 make sure nothing bad will happen if the script is called twice where
4127 it would usually be called once.
4128         <p>
4129 Standard input and output may be redirected (e.g. into pipes) for
4130 logging purposes, so don't rely on them being a tty.
4131         <p>
4132 All prompting or interactive configuration should be kept to a
4133 minimum.  When it is necessary, you should use the
4134 <package>debconf</package> package for the interface.  Remember that
4135 prompting in any case can only be in the <tt>configure</tt> stage of
4136 the <file>postinst</file> script.
4137         <p>
4138 Keep the maintainer scripts as simple as possible.  We suggest you use
4139 pure POSIX shell scripts.  Remember, if you do need any bash features,
4140 the maintainer script must have a bash shebang line.  POSIX shell or
4141 Bash are preferred to Perl, since they enable
4142 <package>debhelper</package> to easily add bits to the scripts.
4143         <p>
4144 If you change your maintainer scripts, be sure to test package
4145 removal, double installation, and purging.  Be sure that a purged
4146 package is completely gone, that is, it must remove any files created,
4147 directly or indirectly, in any maintainer script.
4148         <p>
4149 If you need to check for the existence of a command, you should use
4150 something like
4151 <example>if [ -x /usr/sbin/install-docs ]; then ...</example>
4152
4153 If you don't wish to hard-code the path of a command in your
4154 maintainer script, the following POSIX-compliant shell function may
4155 help:
4156
4157 &example-pathfind;
4158
4159 You can use this function to search <tt>$PATH</tt> for a command name,
4160 passed as an argument.  It returns true (zero) if the command was
4161 found, and false if not.  This is really the most portable way, since
4162 <tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
4163 POSIX.
4164         <p>
4165 While <prgn>which</prgn> is an acceptable alternative, since
4166 it is from the required <package>debianutils</package> package, it's
4167 not on the root partition. That is, it's in <file>/usr/bin</file> rather
4168 than <file>/bin</file>, so one can't use it in scripts which are run
4169 before the <file>/usr</file> partition is mounted. Most scripts won't have
4170 this problem, though.
4171       </sect>
4172
4173
4174       <sect id="bpp-config-mgmt">
4175         <heading>Configuration management with <package>debconf</package></heading>
4176         <p>
4177 <package>Debconf</package> is a configuration management system which
4178 can be used by all the various packaging scripts
4179 (<file>postinst</file> mainly) to request feedback from the user
4180 concerning how to configure the package. Direct user interactions must
4181 now be avoided in favor of <package>debconf</package>
4182 interaction. This will enable non-interactive installations in the
4183 future.
4184         <p>
4185 Debconf is a great tool but it is often poorly used.   Many common mistakes
4186 are listed in the <manref name="debconf-devel" section="7"> man page. 
4187 It is something that you must read if you decide to use debconf.
4188 Also, we document some best practices here.
4189         <p>
4190 These guidelines include some writing style and typography
4191 recommendations, general considerations about debconf usage as well as
4192 more specific recommendations for some parts of the distribution (the
4193 installation system for instance).
4194
4195         <sect1>Do not abuse debconf
4196         <p>
4197 Since debconf appeared in Debian, it has been widely abused and
4198 several criticisms received by the Debian distribution come from
4199 debconf abuse with the need of answering a wide bunch of questions
4200 before getting any little thing installed.
4201         <p>
4202 Keep usage notes to what they belong: the NEWS.Debian, or
4203 README.Debian file. Only use notes for important notes which may
4204 directly affect the package usability. Remember that notes will always
4205 block the install until confirmed or bother the user by email.
4206         <p>
4207 Carefully choose the questions priorities in maintainer scripts. See
4208 <manref name="debconf-devel" section="7"> for details about priorities.
4209 Most questions should use medium and low priorities.
4210
4211         <sect1>General recommendations for authors and translators
4212         <p>
4213         <sect2>Write correct English
4214         <p>
4215 Most Debian package maintainers are not native English speakers. So,
4216 writing properly phrased templates may not be easy for them.
4217         <p>
4218 Please use (and abuse) &email-debian-l10n-english; mailing
4219 list. Have your templates proofread.
4220         <p>
4221 Badly written templates give a poor image of your package, of your
4222 work...or even of Debian itself.
4223         <p>
4224 Avoid technical jargon as much as possible. If some terms sound common
4225 to you, they may be impossible to understand for others. If you cannot
4226 avoid them, try to explain them (use the extended description). When
4227 doing so, try to balance between verbosity and simplicity.
4228
4229         <sect2>Be kind to translators
4230         <p>
4231 Debconf templates may be translated. Debconf, along with its sister
4232 package <prgn>po-debconf</prgn> offers a simple framework for getting
4233 templates translated by translation teams or even individuals.
4234         <p>
4235 Please use gettext-based templates. Install <package>po-debconf</package> on your
4236 development system and read its documentation ("man po-debconf" is a
4237 good start).
4238         <p>
4239 Avoid changing templates too often. Changing templates text induces
4240 more work to translators which will get their translation "fuzzied". If
4241 you plan changes to your original templates, please contact
4242 translators. Most active translators are very responsive and getting
4243 their work included along with your modified templates will save you
4244 additional uploads. If you use gettext-based templates, the
4245 translator's name and e-mail addresses are mentioned in the po files
4246 headers.
4247         <p>
4248 The use of the <prgn>podebconf-report-po</prgn> from the
4249 po-debconf package is highly recommended to warn translators which
4250 have incomplete translations and request them for updates.
4251         <p>
4252 If in doubt, you may also contact the translation team for a given
4253 language (debian-l10n-xxxxx@lists.debian.org), or the
4254 &email-debian-i18n; mailing list.
4255         <p>
4256 Calls for translations posted to
4257 &email-debian-i18n; with the <file>debian/po/templates.pot</file> file
4258 attached or referenced in a URL are encouraged. Be sure to mentions in
4259 these calls for new translations which languages you have existing
4260 translations for, in order to avoid duplicate work.
4261         <sect2>Unfuzzy complete translations when correcting typos and spelling
4262         <p>
4263
4264 When the text of a debconf template is corrected and you are
4265 <strong>sure</strong> that the change does <strong>not</strong> affect
4266 translations, please be kind to translators and unfuzzy their
4267 translations.
4268         <p>
4269 If you don't do so, the whole template will not be translated as long
4270 as a translator will send you an update.
4271         <p>
4272 To <strong>unfuzzy</strong> translations, you can proceed the following way:
4273         <enumlist>
4274         <item>
4275 Put all incomplete PO files out of the way. You can check the
4276 completeness by using (needs the <package>gettext</package> package installed):
4277 <example>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
4278 --statistics $i; done</example>
4279         <item>
4280 move all files which report either fuzzy strings to a temporary
4281 place. Files which report no fuzzy strings (only translated and
4282 untranslated) will be kept in place.
4283         <item>
4284 now <strong>and now only</strong>, modify the template for the typos
4285 and check again that translation are not impacted (typos, spelling
4286 errors, sometimes typographical corrections are usually OK)
4287         <item>
4288 run <prgn>debconf-updatepo</prgn>. This will fuzzy all strings
4289 you modified in translations. You can see this by running the above
4290 again
4291         <item>
4292 use the following command:
4293 <example>for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done</example>
4294         <item>
4295 move back to debian/po the files which showed fuzzy strings in the first step
4296         <item>
4297 run <prgn>debconf-updatepo</prgn> again
4298         </enumlist>
4299         <sect2>Do not make assumptions about interfaces
4300         <p>
4301 Templates text should not make reference to widgets belonging to some
4302 debconf interfaces. Sentences like "If you answer Yes..." have no
4303 meaning for users of graphical interfaces which use checkboxes for
4304 boolean questions.
4305         <p>
4306 String templates should also avoid mentioning the default values in
4307 their description. First, because this is redundant with the values
4308 seen by the users. Also, because these default values may be different
4309 from the maintainer choices (for instance, when the debconf database
4310 was preseeded).
4311         <p>
4312 More generally speaking, try to avoid referring to user actions.
4313 Just give facts.
4314
4315         <sect2>Do not use first person
4316         <p>
4317 You should avoid the use of first person ("I will do this..." or "We
4318 recommend..."). The computer is not a person and the Debconf templates
4319 do not speak for the Debian developers. You should use neutral
4320 construction and often the passive form. Those of you who already
4321 wrote scientific publications, just write your templates like you
4322 would write a scientific paper.
4323
4324         <sect2>Be gender neutral
4325         <p>
4326 The world is made of men and women. Please use gender-neutral
4327 constructions in your writing. This is not Political Correctness, this
4328 is showing respect to all humanity.
4329
4330
4331         <sect1>Templates fields definition
4332         <p>
4333 This part gives some information which is mostly taken from the
4334 <manref name="debconf-devel" section="7"> manual page.
4335
4336         <sect2>Type
4337         <p>
4338
4339         <sect3>string:
4340         <p>
4341 Results in a free-form input field that the user can type  any string into.
4342
4343         <sect3>password:
4344         <p>
4345 Prompts the user for a password. Use this with caution; be aware that
4346 the password the user enters will be written to debconf's
4347 database. You should probably clean that value out of the database as
4348 soon as is possible.
4349
4350         <sect3>boolean:
4351         <p>
4352 A true/false choice. Remember: true/false, <strong>not yes/no</strong>...
4353
4354         <sect3>select:
4355         <p>
4356 A choice between one of a number of values. The choices must be
4357 specified in a field named 'Choices'.  Separate the possible values
4358 with commas and spaces, like this: Choices: yes, no, maybe
4359
4360         <sect3>multiselect:
4361         <p>
4362 Like the select data type, except the user can choose any number of
4363
4364         items from the choices list (or chose none of them).
4365
4366         <sect3>note:
4367         <p>
4368 Rather than being a question per se, this datatype indicates a note
4369 that can be displayed to the user. It should be used only for
4370 important notes that the user really should see, since debconf will go
4371 to great pains to make sure the user sees it; halting the install for
4372 them to press a key, and even mailing the note to them in some
4373 cases.
4374
4375         <sect3>text:
4376         <p>
4377 This type is now considered obsolete: don't use it.
4378
4379         <sect3>error:
4380         <p>
4381 <strong>THIS TEMPLATE TYPE IS NOT HANDLED BY DEBCONF YET.</strong>
4382         <p>
4383 It has been added to cdebconf, the C version of debconf, first used in
4384 the Debian Installer.
4385         <p>
4386 Please do not use it unless debconf supports it.
4387         <p>
4388 This type is designed to handle error message. It is mostly similar to
4389 the "note" type. Frontends may present it differently (for instance,
4390 the dialog frontend of cdebconf draws a red screen instead of the
4391 usual blue one).
4392
4393
4394         <sect2>Description: short and extended description
4395         <p>
4396 Template descriptions have two parts: short and extended. The short 
4397 description is in the "Description:" line of the template.
4398         <p>
4399 The short description should be kept short (50 characters or so) so
4400 that it may be accomodated by most debconf interfaces. Keeping it
4401 short also helps translators, as usually translations tend to end up
4402 being longer than the original.
4403         <p>
4404 The short description should be able to stand on its own. Some
4405 interfaces do not show the long description by default, or only if the
4406 user explicitely asks for it or even do not show it at all. Avoid
4407 things like "What do you want to do?"
4408         <p>
4409 The short description does not necessarily have to be a full
4410 sentence. This is part of the "keep it short and efficient"
4411 recommendation.
4412         <p>
4413 The extended description should not repeat the short description word
4414 for word. If you can't think up a long description, then first, think
4415 some more.  Post to debian-devel. Ask for help. Take a writing class!
4416 That extended description is important. If after all that you still
4417 can't come up with anything, leave it blank.
4418         <p>
4419 The extended description should use complete sentences. Paragraphs
4420 should be kept short for improved readability. Do not mix two ideas
4421 in the same paragraph but rather use another paragraph.
4422         <p>
4423 Don't be too verbose. User tend to ignore too long screens.
4424 20 lines are by experience a border you shouldn't cross,
4425 because that means that in the classical dialog interface,
4426 people will need to scroll, and lot of people just don't do that.
4427         <p>
4428 For specific rules depending on templates type (string, boolean,
4429 etc.), please read below.
4430
4431         <sect2>Choices
4432         <p>
4433 This field should be used for Select and Multiselect types. It
4434 contains the possible choices which will be presented to users. These
4435 choices should be separated by commas.
4436
4437
4438         <sect2>Default
4439         <p>
4440 This field is optional. It contains the default answer for string,
4441 select and multiselect templates. For multiselect templates, it may
4442 contain a comma-separated list of choices.
4443
4444         <sect1>Templates fields specific style guide
4445         <p>
4446
4447         <sect2>Type field
4448         <p>
4449 No specific indication except: use the appropriate type by referring
4450 to the previous section.
4451
4452         <sect2>Description field
4453         <p>
4454 Below are specific instructions for properly writing the Description
4455 (short and extended) depending on the template type.
4456
4457         <sect3>String/password templates
4458         <p>
4459 <list>
4460 <item> The short description is a prompt and <strong>not</strong> a title. Avoid
4461     question style prompts ("IP Address?") in favour of
4462     "opened" prompts ("IP address:").
4463     The use of colons is recommended.
4464
4465 <item> The extended description is a complement to the short description.
4466     In the extended part, explain what is being asked, rather than ask
4467     the same question again using longer words. Use complete sentences.
4468     Terse writing style is strongly discouraged.
4469 </list>
4470
4471         <sect3>Boolean templates
4472         <p>
4473 <list>
4474 <item> The short description should be phrased in the form of a question
4475     which should be kept short and should generally end with a question
4476     mark. Terse writing style is permitted and even encouraged if the
4477     question is rather long (remember that translations are often longer
4478     than original versions)
4479
4480 <item> The extended description should <strong>not</strong> include a question. 
4481
4482 <item> Again, please avoid referring to specific interface widgets. A common
4483     mistake for such templates is "if you answer Yes"-type
4484     constructions.
4485 </list>
4486
4487         <sect3>Select/Multiselect
4488         <p>
4489 <list>
4490 <item> The short description is a prompt and <strong>not</strong> a title.
4491     Do <strong>not</strong> use useless
4492     "Please choose..." constructions. Users are clever enough to figure
4493     out they have to choose something...:)
4494
4495 <item> The extended description will complete the short description. It may
4496     refer to the available choices. It may also mention that the user
4497     may choose more than one of the available choices, if the template
4498     is a multiselect one (although the interface often makes this
4499     clear).
4500 </list>
4501
4502         <sect3>Notes
4503         <p>
4504 <list>
4505 <item> The short description should be considered to be a *title*. 
4506
4507 <item> The extended description is what will be displayed as a more detailed
4508     explanation of the note. Phrases, no terse writing style.
4509
4510 <item> <strong>Do not abuse debconf.</strong>
4511     Notes are the most common way to abuse
4512     debconf. As written in debconf-devel manual page: it's best to use them
4513     only for warning about very serious problems. The NEWS.Debian or
4514     README.Debian files are the appropriate location for a lot of notes.
4515     If, by reading this, you consider converting your Note type templates
4516     to entries in NEWS/Debian or README.Debian, plus consider keeping existing
4517     translations for the future.
4518 </list>
4519
4520
4521         <sect2>Choices field
4522         <p>
4523 If the Choices are likely to change often, please consider using the
4524 "__Choices" trick. This will split each individual choice into a
4525 single string, which will considerably help translators for doing
4526 their work.
4527
4528         <sect2>Default field
4529         <p>
4530 If the default value, for a "select" template, is likely to vary
4531 depending on the user language (for instance, if the choice is a
4532 language choice), please use the "_DefaultChoice" trick.
4533         <p>
4534 This special field allow translators to put the most appropriate
4535 choice according to their own language. It will become the default
4536 choice when their language is used while your own mentioned Default
4537 Choice will be used chan using English.
4538         <p>
4539 Example, taken from the geneweb package templates:
4540 <example>
4541 Template: geneweb/lang
4542 Type: select
4543 __Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)
4544 # This is the default choice. Translators may put their own language here
4545 # instead of the default.
4546 # WARNING : you MUST use the ENGLISH FORM of your language
4547 # For instance, the french translator will need to put "French (fr)" here.
4548 _DefaultChoice: English (en)[ translators, please see comment in PO files]
4549 _Description: Geneweb default language:
4550 </example>
4551         <p>
4552 Note the use of brackets which allow internal comments in debconf
4553 fields.  Also note the use of comments which will show up in files the
4554 translators will work with.
4555         <p>
4556 The comments are needed as the DefaultChoice trick is a bit
4557 confusing: the translators may put their own choice
4558
4559         <sect2>Default field
4560         <p>
4561 Do NOT use empty default field. If you don't want to use default
4562 values, do not use Default at all.
4563         <p>
4564 If you use po-debconf (and you <strong>should</strong>, see 2.2), consider making this
4565 field translatable, if you think it may be translated.
4566         <p>
4567 If the default value may vary depending on language/country (for
4568 instance the default value for a language choice), consider using the
4569 special "_DefaultChoice" type documented in <manref name="po-debconf" section="7">).
4570       </sect>
4571
4572
4573       <sect id="bpp-i18n">
4574         <heading>Internationalization</heading>
4575
4576         <sect1 id="bpp-i18n-debconf">
4577           <heading>Handling debconf translations</heading>
4578           <p>
4579 Like porters, translators have a difficult task.  They work on many
4580 packages and must collaborate with many different
4581 maintainers. Moreover, most of the time, they are not native English
4582 speakers, so you may need to be particularly patient with them.
4583         <p>
4584 The goal of <package>debconf</package> was to make packages
4585 configuration easier for maintainers and for users.  Originally,
4586 translation of debconf templates was handled with
4587 <prgn>debconf-mergetemplate</prgn>.  However, that technique is now
4588 deprecated; the best way to accomplish <package>debconf</package>
4589 internationalization is by using the <package>po-debconf</package>
4590 package.  This method is easier both for maintainer and translators;
4591 transition scripts are provided.
4592         <p>
4593 Using <package>po-debconf</package>, the translation is stored in
4594 <file>po</file> files (drawing from <prgn>gettext</prgn> translation
4595 techniques).  Special template files contain the original messages and
4596 mark which fields are translatable.  When you change the value of a
4597 translatable field, by calling <prgn>debconf-updatepo</prgn>, the
4598 translation is marked as needing attention from the translators. Then,
4599 at build time, the <prgn>dh_installdebconf</prgn> program takes care
4600 of all the needed magic to add the template along with the up-to-date
4601 translations into the binary packages.  Refer to the <manref
4602 name="po-debconf" section="7"> manual page for details.
4603         </sect1>
4604
4605         <sect1 id="bpp-i18n-docs">
4606           <heading>Internationalized documentation</heading>
4607           <p>
4608 Internationalizing documentation is crucial for users, but a lot of
4609 labor.  There's no way to eliminate all that work, but you can make things
4610 easier for translators.
4611           <p>
4612 If you maintain documentation of any size, its easier for translators
4613 if they have access to a source control system.  That lets translators
4614 see the differences between two versions of the documentation, so, for
4615 instance, they can see what needs to be retranslated.  It is
4616 recommended that the translated documentation maintain a note about
4617 what source control revision the translation is based on.  An
4618 interesting system is provided by <url id="&url-i18n-doc-check;"
4619 name="doc-check"> in the <package>boot-floppies</package> package,
4620 which shows an overview of the translation status for any given
4621 language, using structured comments for the current revision of the
4622 file to be translated and, for a translated file, the revision of the
4623 original file the translation is based on.  You might wish to adapt
4624 and provide that in your CVS area.
4625           <p>
4626 If you maintain XML or SGML documentation, we suggest that you isolate
4627 any language-independent information and define those as entities in a
4628 separate file which is included by all the different
4629 translations. This makes it much easier, for instance, to keep URLs
4630 up to date across multiple files.
4631         </sect1>
4632       </sect>
4633
4634       <sect id="bpp-common-situations">
4635         <heading>Common packaging situations</heading>
4636
4637 <!--
4638         <sect1 id="bpp-kernel">Kernel modules/patches
4639         <p>
4640         &FIXME; Heavy use of kernel-package. provide files in
4641         /etc/modutils/ for module configuration.
4642 -->
4643
4644         <sect1 id="bpp-autotools">
4645           <heading>Packages using
4646           <prgn>autoconf</prgn>/<prgn>automake</prgn></heading>
4647           <p>
4648 Keeping <prgn>autoconf</prgn>'s <file>config.sub</file> and
4649 <file>config.guess</file> files up to date is critical for porters,
4650 especially on more volatile architectures.  Some very good packaging
4651 practices for any package using <prgn>autoconf</prgn> and/or
4652 <prgn>automake</prgn> have been synthesized in
4653 &file-bpp-autotools; from the <package>autotools-dev</package>
4654 package. You're strongly encouraged to read this file and
4655 to follow the given recommendations.
4656
4657
4658         <sect1 id="bpp-libraries">Libraries
4659         <p>
4660 Libraries are always difficult to package for various reasons. The policy
4661 imposes many constraints to ease their maintenance and to make sure
4662 upgrades are as simple as possible when a new upstream version comes out.
4663 Breakage in a library can result in dozens of dependent packages
4664 breaking.
4665         <p>
4666 Good practices for library packaging have been grouped in
4667 <url id="&url-libpkg-guide;" name="the library packaging guide">.
4668         
4669
4670         <sect1 id="bpp-docs">Documentation
4671            <p>
4672 Be sure to follow the <url id="&url-debian-policy;ch-docs.html"
4673             name="Policy on documentation">.</p>
4674           <p>
4675 If your package contains documentation built from XML or SGML, we
4676 recommend you not ship the XML or SGML source in the binary
4677 package(s).  If users want the source of the documentation, they
4678 should retrieve the source package.</p>
4679           <p>
4680 Policy specifies that documentation should be shipped in HTML format.
4681 We also recommend shipping documentation in PDF and plain text format if
4682 convenient and if output of reasonable quality is possible.  However, it is generally
4683 not appropriate to ship plain text versions of documentation whose source
4684 format is HTML.</p>
4685           <p>
4686 Major shipped manuals should register themselves with
4687 <package>doc-base</package> on installation.  See the
4688 <package>doc-base</package> package documentation for more
4689 information.</p>
4690
4691
4692         <sect1 id="bpp-other">Specific types of packages
4693         <p>
4694 Several specific types of packages have special sub-policies and
4695 corresponding packaging rules and practices:
4696 <list>
4697     <item>
4698 Perl related packages have a <url name="Perl policy"
4699 id="&url-perl-policy;">, some examples of packages following that
4700 policy are <package>libdbd-pg-perl</package> (binary perl module) or
4701 <package>libmldbm-perl</package> (arch independent perl module).
4702     <item>
4703 Python related packages have their python policy; see
4704 &file-python-policy; in the <package>python</package> package.
4705     <item>
4706 Emacs related packages have the <url id="&url-emacs-policy;"
4707 name="emacs policy">.
4708     <item>
4709 Java related packages have their <url id="&url-java-policy;"
4710 name="java policy">.
4711     <item>
4712 Ocaml related packages have their own policy, found in
4713 &file-ocaml-policy; from the <package>ocaml</package> package. A good
4714 example is the <package>camlzip</package> source package.
4715     <item>
4716 Packages providing XML or SGML DTDs should conform to the
4717 recommendations found in the <package>sgml-base-doc</package>
4718 package.
4719     <item>
4720 Lisp packages should register themselves with
4721 <package>common-lisp-controller</package>, about which see
4722 &file-lisp-controller;.
4723 <!-- TODO: mozilla extension policy, once that becomes available -->
4724 </list>
4725         </sect1>
4726
4727 <!--
4728         <sect1 id="custom-config-files">Custom configuration files
4729         <p>
4730         &FIXME; speak of "ucf", explain solution with a template,
4731         explain conf.d directories
4732
4733         <sect1 id="config-with-db">Use of an external database
4734         <p>
4735         &FIXME; The software may require a database that you need to setup.
4736         But the database may be local or distant. Thus you can't depend
4737         on a database server but just on the corresponding library.
4738
4739         sympa may be an example package
4740 -->     
4741
4742         <sect1 id="bpp-archindepdata">
4743           <heading>Architecture-independent data</heading>
4744           <p>
4745 It is not uncommon to have a large amount of architecture-independent
4746 data packaged with a program.  For example, audio files, a collection
4747 of icons, wallpaper patterns, or other graphic files.  If the size of
4748 this data is negligible compared to the size of the rest of the
4749 package, it's probably best to keep it all in a single package.
4750           <p>
4751 However, if the size of the data is considerable, consider splitting
4752 it out into a separate, architecture-independent package ("_all.deb").
4753 By doing this, you avoid needless duplication of the same data into
4754 eleven or more .debs, one per each architecture.  While this
4755 adds some extra overhead into the <file>Packages</file> files, it
4756 saves a lot of disk space on Debian mirrors.  Separating out
4757 architecture-independent data also reduces processing time of
4758 <prgn>lintian</prgn> or <prgn>linda</prgn> (see <ref id="tools-lint">)
4759 when run over the entire Debian archive.
4760         </sect1>
4761
4762
4763         <sect1 id="bpp-locale">
4764           <heading>Needing a certain locale during build</heading>
4765           <p>
4766 If you need a certain locale during build, you can create a temporary
4767 file via this trick:
4768         <p>
4769 If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to
4770 the name of the locale you generate, you should get what you want
4771 without being root.  Something like this:
4772
4773 <example>
4774 LOCALE_PATH=debian/tmpdir/usr/lib/locale
4775 LOCALE_NAME=en_IN
4776 LOCALE_CHARSET=UTF-8
4777
4778 mkdir -p $LOCALE_PATH
4779 localedef -i "$LOCALE_NAME.$LOCALE_CHARSET" -f "$LOCALE_CHARSET" "$LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET"
4780
4781 # Using the locale
4782 LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date
4783 </example>
4784         </sect1>
4785
4786         <sect1 id="bpp-transition">
4787           <heading>Make transition packages deborphan compliant</heading>
4788           <p>
4789 Deborphan is a program for helping users to detect which packages can safely be
4790 removed from the system, i.e. the ones that have no packages depending on
4791 them. The default operation is to search only within the libs and oldlibs
4792 sections, to hunt down unused libraries. But when passed the right argument,
4793 it tries to catch other useless packages. 
4794           <p>
4795 For example, with --guess-dummy, deborphan tries to search all transitional packages
4796 which were needed for upgrade but which can now safely be removed. For that,
4797 it looks for the string "dummy" or "transitional" in their short
4798 description.
4799           <p>
4800 So, when you are creating such a package, please make sure to add this text
4801 to your short description. If you are looking for examples, just run: 
4802   <example>apt-cache search .|grep dummy</example> or
4803   <example>apt-cache search .|grep transitional</example>.
4804         </sect1>
4805
4806
4807     <sect1 id="bpp-origtargz">
4808         <heading>Best practices for <file>orig.tar.gz</file> files</heading>
4809        <p>
4810    There are two kinds of original source tarballs: Pristine source
4811    and repackaged upstream source.
4812        </p>
4813        <sect2 id="pristinesource">
4814           <heading>Pristine source</heading>
4815           <p>
4816 The defining characteristic of a pristine source tarball is that the
4817 .orig.tar.gz file is byte-for-byte identical to a tarball officially
4818 distributed by the upstream author.
4819 <footnote>
4820 We cannot prevent upstream authors from changing the tarball
4821 they distribute without also incrementing the version number, so
4822 there can be no guarantee that a pristine tarball is identical
4823 to what upstream <em>currently</em> distributing at any point in
4824 time. All that can be expected is that it is identical to
4825 something that upstream once <em>did</em> distribute.
4826
4827 If a difference arises later (say, if upstream notices that he wasn't
4828 using maximal comression in his original distribution and then
4829 re-<tt>gzip</tt>s it), that's just too bad. Since there is no good way
4830 to upload a new .orig.tar.gz for the same version, there is not even
4831 any point in treating this situation as a bug.
4832 </footnote>
4833 This makes it possible to use checksums to easily verify that all
4834 changes between Debian's version and upstream's are contained in the
4835 Debian diff. Also, if the original source is huge, upstream authors
4836 and others who already have the upstream tarball can save download
4837 time if they want to inspect your packaging in detail.
4838            </p>
4839           <p>
4840 There is no universally accepted guidelines that upstream authors
4841 follow regarding to the directory structure inside their tarball, but
4842 <prgn>dpkg-source</prgn> is nevertheless able to deal with most
4843 upstream tarballs as pristine source. Its strategy is equivalent to
4844 the following:
4845          </p>
4846          <p>
4847          <enumlist>
4848             <item>
4849 It unpacks the tarball in an empty temporary directory by doing
4850
4851 <example>
4852 zcat path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar xf -
4853 </example>
4854              </item>
4855              <item>
4856 If, after this, the temporary directory contains nothing but one
4857 directory and no other files, <prgn>dpkg-source</prgn> renames that
4858 directory to
4859 <tt>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</tt>. The name
4860 of the top-level directory in the tarball does not matter, and is
4861 forgotten.
4862              </item>
4863             <item>
4864 Otherwise, the upstream tarball must have been packaged without a
4865 common top-level directory (shame on the upstream author!).  In this
4866 case, <prgn>dpkg-source</prgn> renames the temporary directory
4867 <em>itself</em> to
4868 <tt>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</tt>.
4869              </item>
4870           </enumlist>
4871          </p>
4872          </sect2>
4873          <sect2 id="repackagedorigtargz">
4874             <heading>Repackaged upstream source</heading>
4875             <p>
4876 You <strong>should</strong> upload packages with a pristine source
4877 tarball if possible, but there are various reasons why it might not be
4878 possible. This is the case if upstream does not distribute the source
4879 as gzipped tar at all, or if upstream's tarball contains non-DFSG-free
4880 material that you must remove before uploading.
4881              </p>
4882             <p>
4883 In these cases the developer must construct a suitable .orig.tar.gz
4884 file himself. We refer to such a tarball as a "repackaged upstream
4885 source". Note that a "repackaged upstream source" is different from a
4886 Debian-native package. A repackaged source still comes with
4887 Debian-specific changes in a separate <tt>.diff.gz</tt> and still has
4888 a version number composed of <tt>&lt;upstream-version&gt;</tt> and
4889 <tt>&lt;debian-revision&gt;</tt>.
4890              </p>
4891             <p>
4892 There may be cases where it is desirable to repackage the source even
4893 though upstream distributes a <tt>.tar.gz</tt> that could in principle
4894 be used in its pristine form. The most obvious is if
4895 <em>significant</em> space savings can be achieved by recompressing
4896 the tar archive or by removing genuinely useless cruft from the
4897 upstream archive. Use your own discretion here, but be prepared to
4898 defend your decision if you repackage source that could have been
4899 pristine.
4900              </p>
4901             <p>
4902 A repackaged .orig.tar.gz
4903              </p>
4904             <p>
4905             <enumlist>
4906             <item>
4907 <p>
4908 <strong>must</strong> contain detailed information how
4909 the repackaged source was obtained, and how this can be reproduced, in
4910 <file>README.Debian-source</file> or a similar file. This file should
4911 be in the <file>diff.gz</file> part of the Debian source package,
4912 usually in the <file>debian</file> directory, <em>not</em> in the
4913 repackaged <file>orig.tar.gz</file>. It is also a good idea to provide a
4914 <tt>get-orig-source</tt> target in your <file>debian/rules</file> file
4915 that repeats the process, as described in the Policy Manual, <url
4916 id="&url-debian-policy;ch-source.html#s-debianrules" name="Main
4917 building script: debian/rules">.
4918 </p>
4919             </item>
4920             <item>
4921 <strong>should not</strong> contain any file that does not come from the
4922 upstream author(s), or whose contents has been changed by you.
4923 <footnote>
4924 As a special exception, if the omission of non-free files would lead
4925 to the source failing to build without assistance from the Debian
4926 diff, it might be appropriate to instead edit the files, omitting only
4927 the non-free parts of them, and/or explain the situation in a
4928 README.Debian-source <!-- or similarly named --> file in the root of the source
4929 tree. But in that case please also urge the upstream author to make
4930 the non-free components easier seperable from the rest of the source.
4931 </footnote>
4932              </item>
4933             <item>
4934 <p>
4935 <strong>should</strong>, except where impossible for legal reasons,
4936 preserve the entire building and portablility infrastructure provided
4937 by the upstream author. For example, it is not a sufficient reason for
4938 omitting a file that it is used only when building on
4939 MS-DOS. Similarly, a Makefile provided by upstream should not be
4940 omitted even if the first thing your <file>debian/rules</file> does is
4941 to overwrite it by running a configure script.
4942 </p>
4943 <p>
4944 (<em>Rationale:</em> It is common for Debian users who need to build
4945 software for non-Debian platforms to fetch the source from a Debian
4946 mirror rather than trying to locate a canonical upstream distribution
4947 point).
4948 </p>             </item>
4949             <item>
4950 <strong>should</strong> use
4951 <tt>&lt;packagename&gt;-&lt;upstream-version&gt;.orig</tt> as the name
4952 of the top-level directory in its tarball. This makes it possible to
4953 distinguish pristine tarballs from repackaged ones.
4954             </item>
4955             <item>
4956 <strong>should</strong> be gzipped with maximal compression.
4957              </item>
4958             </enumlist>
4959             </p>
4960             <p>
4961 The canonical way to meet the latter two points is to let
4962 <tt>dpkg-source -b</tt> construct the repackaged tarball from an
4963 unpacked directory.
4964             </p>
4965        </sect2>
4966        <sect2 id="changed-binfiles">
4967        <heading>Changing binary files in <tt>diff.gz</tt></heading>
4968        <p>
4969 Sometimes it is necessary to change binary files contained in the
4970 original tarball, or to add binary files that are not in it.
4971 If this is done by simply copying the files into the debianized source
4972 tree, <prgn>dpkg-source</prgn> will not be able to handle this. On the
4973 other hand, according to the guidelines given above, you cannot
4974 include such a changed binary file in a repackaged
4975 <file>orig.tar.gz</file>. Instead, include the file in the
4976 <file>debian</file> directory in <prgn>uuencode</prgn>d (or similar)
4977 form
4978 <footnote>
4979 The file should have a name that makes it clear which binary file it
4980 encodes. Usually, some postfix indicating the encoding should be
4981 appended to the original filename.
4982 Note that you don't need to depend on <package>sharutils</package> to get
4983 the <prgn>uudecode</prgn> program if you use <prgn>perl</prgn>'s
4984 <tt>pack</tt> function.
4985 The code could look like
4986 <example>
4987 uuencode-file:
4988     perl -ne 'print(pack "u", $$_);' $(file) > $(file).uuencoded
4989
4990 uudecode-file:
4991     perl -ne 'print(unpack "u", $$_);' $(file).uuencoded > $(file)
4992 </example>
4993 </footnote>.
4994 The file would then be decoded and copied to its place during the
4995 build process. Thus the change will be visible quite easy.
4996 </p>
4997 <p>
4998 Some packages use <prgn>dbs</prgn> to manage patches to their upstream
4999 source, and always create a new <tt>orig.tar.gz</tt> file that
5000 contains the real <tt>orig.tar.gz</tt> in its toplevel directory. This
5001 is questionable with respect to the preference for pristine source. On
5002 the other hand, it is easy to modify or add binary files in this case:
5003 Just put them into the newly created <tt>orig.tar.gz</tt> file,
5004 besides the real one, and copy them to the right place during the
5005 build process.
5006        </p>
5007        </sect2>
5008     </sect1>
5009
5010
5011       </sect>
5012     </chapt>
5013
5014
5015   <chapt id="beyond-pkging">
5016     <heading>Beyond Packaging</heading>
5017     <p>
5018 Debian is about a lot more than just packaging software and
5019 maintaining those packages.  This chapter contains information about 
5020 ways, often really critical ways, to contribute to Debian beyond
5021 simply creating and maintaining packages.
5022     <p>
5023 As a volunteer organization, Debian relies on the discretion of its
5024 members in choosing what they want to work on and in choosing
5025 the most critical thing to spend their time on.
5026
5027     <sect id="submit-bug">
5028       <heading>Bug reporting</heading>
5029         <p>
5030 We encourage you to file bugs as you find them in Debian packages.  In
5031 fact, Debian developers are often the first line testers.  Finding and
5032 reporting bugs in other developers' packages improves the quality of
5033 Debian.
5034         <p>
5035 Read the <url name="instructions for reporting bugs"
5036 id="&url-bts-report;"> in the Debian <url name="bug tracking system"
5037 id="&url-bts;">.
5038         <p>
5039 Try to submit the bug from a normal user account at which you are
5040 likely to receive mail, so that people can reach you if they need
5041 further information about the bug.  Do not submit bugs as root.
5042         <p>
5043 You can use a tool like <manref name="reportbug" section="1"> to
5044 submit bugs. It can automate and generally ease the process.
5045         <p>
5046 Make sure the bug is not already filed against a package.
5047 Each package has a bug list easily reachable at
5048 <tt>http://&bugs-host;/<var>packagename</var></tt>
5049 Utilities like <manref name="querybts" section="1"> can also
5050 provide you with this information (and <prgn>reportbug</prgn>
5051 will usually invoke <prgn>querybts</prgn> before sending, too).
5052         <p>
5053 Try to direct your bugs to the proper location. When for example
5054 your bug is about a package which overwrites files from another package,
5055 check the bug lists for <em>both</em> of those packages in order to
5056 avoid filing duplicate bug reports.
5057         <p>
5058 For extra credit, you can go through other packages, merging bugs
5059 which are reported more than once, or tagging bugs `fixed'
5060 when they have already been fixed.  Note that when you are
5061 neither the bug submitter nor the package maintainer, you should
5062 not actually close the bug (unless you secure permission from the
5063 maintainer).
5064         <p>
5065 From time to time you may want to check what has been going on
5066 with the bug reports that you submitted. Take this opportunity to
5067 close those that you can't reproduce anymore. To find
5068 out all the bugs you submitted, you just have to visit
5069 <tt>http://&bugs-host;/from:<var>&lt;your-email-addr&gt;</var></tt>.
5070
5071       <sect1 id="submit-many-bugs">Reporting lots of bugs at once (mass bug filing)
5072         <p>
5073 Reporting a great number of bugs for the same problem on a great
5074 number of different packages &mdash; i.e., more than 10 &mdash; is a deprecated
5075 practice.  Take all possible steps to avoid submitting bulk bugs at
5076 all.  For instance, if checking for the problem can be automated, add
5077 a new check to <package>lintian</package> so that an error or warning
5078 is emitted.
5079         <p>
5080 If you report more than 10 bugs on the same topic at once, it is
5081 recommended that you send a message to &email-debian-devel; describing
5082 your intention before submitting the report, and mentioning the
5083 fact in the subject of your mail. This will allow other
5084 developers to verify that the bug is a real problem. In addition, it
5085 will help prevent a situation in which several maintainers start
5086 filing the same bug report simultaneously.
5087         <p>
5088 Please use the programms <prgn>dd-list</prgn> and
5089 if appropriate <prgn>whodepends</prgn>
5090 (from the package devscripts)
5091 to generate a list of all affected packages, and include the
5092 output in your mail to &email-debian-devel;.
5093         <p>
5094 Note that when sending lots of bugs on the same subject, you should
5095 send the bug report to <email>maintonly@&bugs-host;</email> so
5096 that the bug report is not forwarded to the bug distribution mailing
5097 list.
5098
5099
5100       <sect id="qa-effort">Quality Assurance effort
5101         
5102         <sect1 id="qa-daily-work">Daily work
5103         <p>
5104 Even though there is a dedicated group of people for Quality
5105 Assurance, QA duties are not reserved solely for them. You can
5106 participate in this effort by keeping your packages as bug-free as
5107 possible, and as lintian-clean (see <ref id="lintian">) as
5108 possible. If you do not find that possible, then you should consider
5109 orphaning some of your packages (see <ref
5110 id="orphaning">). Alternatively, you may ask the help of other people
5111 in order to catch up with the backlog of bugs that you have (you can ask
5112 for help on &email-debian-qa; or &email-debian-devel;). At the same
5113 time, you can look for co-maintainers (see <ref id="collaborative-maint">).
5114         
5115         <sect1 id="qa-bsp">Bug squashing parties
5116         <p>
5117 From time to time the QA group organizes bug squashing parties to get rid of
5118 as many problems as possible. They are announced on &email-debian-devel-announce;
5119 and the announcement explains which area will be the focus of the party:
5120 usually they focus on release critical bugs but it may happen that they
5121 decide to help finish a major upgrade (like a new perl version
5122 which requires recompilation of all the binary modules).
5123         <p>
5124 The rules for non-maintainer uploads differ during the parties because
5125 the announcement of the party is considered prior notice for NMU. If
5126 you have packages that may be affected by the party (because they have
5127 release critical bugs for example), you should send an update to each of
5128 the corresponding bug to explain their current status and what you expect
5129 from the party. If you don't want an NMU, or if you're only interested in a
5130 patch, or if you will deal yourself with the bug, please explain that in
5131 the BTS.
5132         <p>
5133 People participating in the party have special rules for NMU, they can
5134 NMU without prior notice if they upload their NMU to
5135 DELAYED/3-day at least. All other NMU rules apply as usually; they
5136 should send the patch of the NMU to the BTS (to one of the open bugs
5137 fixed by the NMU, or to a new bug, tagged fixed). They should
5138 also respect any particular wishes of the maintainer.
5139         <p>
5140 If you don't feel confident about doing an NMU, just send a patch
5141 to the BTS. It's far better than a broken NMU.
5142
5143
5144     <sect id="contacting-maintainers">Contacting other maintainers
5145       <p>
5146 During your lifetime within Debian, you will have to contact other
5147 maintainers for various reasons. You may want to discuss a new
5148 way of cooperating between a set of related packages, or you may
5149 simply remind someone that a new upstream version is available
5150 and that you need it.
5151       <p>
5152 Looking up the email address of the maintainer for the package can be
5153 distracting. Fortunately, there is a simple email alias,
5154 <tt>&lt;package&gt;@&packages-host;</tt>, which provides a way to
5155 email the maintainer, whatever their individual email address (or
5156 addresses) may be.  Replace <tt>&lt;package&gt;</tt> with the name of
5157 a source or a binary package.
5158       <p>
5159 You may also be interested in contacting the persons who are
5160 subscribed to a given source package via <ref id="pkg-tracking-system">.
5161 You can do so by using the <tt>&lt;package&gt;@&pts-host;</tt>
5162 email address.
5163 <!-- FIXME: moo@packages.d.o is easily confused with moo@packages.qa.d.o -->
5164
5165     <sect id="mia-qa">Dealing with inactive and/or unreachable maintainers
5166       <p>
5167 If you notice that a package is lacking maintenance, you should
5168 make sure that the maintainer is active and will continue to work on
5169 their packages. It is possible that they are not active any more, but
5170 haven't registered out of the system, so to speak. On the other hand,
5171 it is also possible that they just need a reminder.
5172       <p>
5173 There is a simple system (the MIA database) in which information about
5174 maintainers who are deemed Missing In Action is recorded.
5175 When a member of the
5176 QA group contacts an inactive maintainer or finds more information about
5177 one, this is recorded in the MIA database.  This system is available
5178 in /org/qa.debian.org/mia on the host qa.debian.org, and can be queried
5179 with a tool known as <prgn>mia-query</prgn>.
5180 Use <example>mia-query --help</example> to see how to query the database.
5181 If you find that no information has been recorded
5182 about an inactive maintainer yet, or that you can add more information,
5183 you should generally proceed as follows.
5184       <p>
5185 The first step is to politely contact the maintainer,
5186 and wait a reasonable time for a response.
5187 It is quite hard to define "reasonable
5188 time", but it is important to take into account that real life is sometimes
5189 very hectic. One way to handle this would be to send a reminder after two
5190 weeks.
5191       <p>
5192 If the maintainer doesn't reply within four weeks (a month), one can
5193 assume that a response will probably not happen. If that happens, you
5194 should investigate further, and try to gather as much useful information
5195 about the maintainer in question as possible. This includes:
5196       <p>
5197       <list>
5198         <item>The "echelon" information available through the 
5199               <url id="&url-debian-db;" name="developers' LDAP database">,
5200               which indicates when the developer last posted to
5201               a Debian mailing list. (This includes uploads via
5202               debian-*-changes lists.) Also, remember to check whether the
5203               maintainer is marked as "on vacation" in the database.
5204
5205         <item>The number of packages this maintainer is responsible for,
5206               and the condition of those packages. In particular, are there
5207               any RC bugs that have been open for ages? Furthermore, how
5208               many bugs are there in general? Another important piece of
5209               information is whether the packages have been NMUed, and if
5210               so, by whom.
5211
5212         <item>Is there any activity of the maintainer outside of Debian? 
5213               For example, they might have posted something recently to
5214               non-Debian mailing lists or news groups.
5215       </list>
5216       <p>
5217 A bit of a problem are packages which were sponsored &mdash; the maintainer is not
5218 an official Debian developer. The echelon information is not available for
5219 sponsored people, for example, so you need to find and contact the Debian
5220 developer who has actually uploaded the package. Given that they signed the
5221 package, they're responsible for the upload anyhow, and are likely to know what
5222 happened to the person they sponsored.
5223       <p>
5224 It is also allowed to post a query to &email-debian-devel;, asking if anyone
5225 is aware of the whereabouts of the missing maintainer.
5226 Please Cc: the person in question.
5227       <p>
5228 Once you have gathered all of this, you can contact &email-mia;.
5229 People on this alias will use the information you provide in order to
5230 decide how to proceed. For example, they might orphan one or all of the
5231 packages of the maintainer. If a package has been NMUed, they might prefer
5232 to contact the NMUer before orphaning the package &mdash; perhaps the person who
5233 has done the NMU is interested in the package.
5234       <p>
5235 One last word: please remember to be polite. We are all volunteers and
5236 cannot dedicate all of our time to Debian. Also, you are not aware of the
5237 circumstances of the person who is involved. Perhaps they might be
5238 seriously ill or might even have died &mdash; you do not know who may be on the
5239 receiving side. Imagine how a relative will feel if they read the e-mail
5240 of the deceased and find a very impolite, angry and accusing message!
5241       <p>
5242 On the other hand, although we are volunteers, we do have a responsibility. 
5243 So you can stress the importance of the greater good &mdash; if a maintainer does
5244 not have the time or interest anymore, they should "let go" and give the
5245 package to someone with more time.
5246       <p>
5247 If you are interested in working in the MIA team, please have a look at the
5248 README file in /org/qa.debian.org/mia on qa.debian.org where the technical
5249 details and the MIA procedures are documented and contact &email-mia;.
5250
5251
5252     <sect id="newmaint">
5253       <heading>Interacting with prospective Debian developers</heading>
5254       <p>
5255 Debian's success depends on its ability to attract and retain new and
5256 talented volunteers.  If you are an experienced developer, we
5257 recommend that you get involved with the process of bringing in new
5258 developers.  This section describes how to help new prospective
5259 developers.
5260
5261
5262       <sect1 id="sponsoring">Sponsoring packages
5263         <p>
5264 Sponsoring a package means uploading a package for a maintainer who is not
5265 able to do it on their own, a new maintainer applicant. Sponsoring a package
5266 also means accepting responsibility for it.
5267         <p>
5268         <!-- FIXME: service down
5269 If you wish to volunteer as a sponsor, you can sign up at <url
5270 id="&url-sponsors;">.
5271         <p>
5272         -->
5273 New maintainers usually have certain difficulties creating Debian packages
5274 &mdash; this is quite understandable. That is why the sponsor is there, to check
5275 the package and verify that it is good enough for inclusion in Debian.
5276 (Note that if the sponsored package is new, the ftpmasters will also have to
5277 inspect it before letting it in.)
5278         <p>
5279 Sponsoring merely by signing the upload or just recompiling is
5280 <strong>definitely not recommended</strong>. You need to build the source
5281 package just like you would build a package of your own. Remember that it
5282 doesn't matter that you left the prospective developer's name both in the
5283 changelog and the control file, the upload can still be traced to you.
5284         <p>
5285 If you are an application manager for a prospective developer, you can also
5286 be their sponsor. That way you can also verify how the applicant is
5287 handling the 'Tasks and Skills' part of their application.
5288
5289       <sect1>Managing sponsored packages
5290         <p>
5291 By uploading a sponsored package to Debian, you are certifying that
5292 the package meets minimum Debian standards.  That implies that you
5293 must build and test the package on your own system before uploading.
5294         <p>
5295 You cannot simply upload a binary <file>.deb</file> from the sponsoree. In
5296 theory, you should only ask for the diff file and the location of the
5297 original source tarball, and then you should download the source and apply
5298 the diff yourself. In practice, you may want to use the source package
5299 built by your sponsoree. In that case, you have to check that they haven't
5300 altered the upstream files in the <file>.orig.tar.gz</file> file that
5301 they're providing.
5302         <p>
5303 Do not be afraid to write the sponsoree back and point out changes
5304 that need to be made.  It often takes several rounds of back-and-forth
5305 email before the package is in acceptable shape.  Being a sponsor
5306 means being a mentor.
5307         <p>
5308 Once the package meets Debian standards, build and sign it with                           
5309 <example>dpkg-buildpackage -k<var>KEY-ID</var></example>                                  
5310 before uploading it to the incoming directory. Of course, you can also
5311 use any part of your <var>KEY-ID</var>, as long as it's unique in your
5312 secret keyring.
5313         <p>
5314 The Maintainer field of the <file>control</file> file and the
5315 <file>changelog</file> should list the person who did the packaging, i.e., the
5316 sponsoree. The sponsoree will therefore get all the BTS mail about the
5317 package. 
5318         <p>
5319 If you prefer to leave a more evident trace of your sponsorship job, you
5320 can add a line stating it in the most recent changelog entry.
5321        <p>
5322 You are encouraged to keep tabs on the package you sponsor using 
5323 <ref id="pkg-tracking-system">.
5324
5325       <sect1>Advocating new developers
5326         <p>
5327 See the page about <url id="&url-newmaint-advocate;"
5328 name="advocating a prospective developer"> at the Debian web site.
5329
5330       <sect1>Handling new maintainer applications
5331         <p>
5332 Please see <url id="&url-newmaint-amchecklist;" name="Checklist for
5333 Application Managers"> at the Debian web site.
5334
5335
5336     <chapt id="l10n">Internationalizing, translating, being internationalized
5337     and being translated
5338       <p>
5339 Debian supports an ever-increasing number of natural languages. Even if you are
5340 a native English speaker and do not speak any other language, it is part of your
5341 duty as a maintainer to be aware of issues of internationalization (abbreviated
5342 i18n because there are 18 letters between the 'i' and the 'n' in
5343 internationalization). Therefore, even if you are ok with English-only
5344 programs, you should read most of this chapter.
5345       <p>
5346 According to <url id="http://www.debian.org/doc/manuals/intro-i18n/"
5347 name="Introduction to i18n"> from Tomohiro KUBOTA, "I18N (internationalization)
5348 means modification of a software or related technologies so that a software can
5349 potentially handle multiple languages, customs, and so on in the world." while
5350 "L10N (localization) means implementation of a specific language for an already
5351 internationalized software."
5352       <p>
5353 l10n and i18n are interconnected, but the difficulties related to each of them are very
5354 different. It's not really difficult to allow a program to change the language
5355 in which texts are displayed based on user settings, but it is very time
5356 consuming to actually translate these messages. On the other hand, setting the
5357 character encoding is trivial, but adapting the code to use several character
5358 encodings is a really hard problem.
5359       <p>
5360 Setting aside the i18n problems, where no general guideline can be given, there is
5361 actually no central infrastructure for l10n within Debian which could be
5362 compared to the dbuild mechanism for porting. So most of the work has to be
5363 done manually.
5364
5365
5366         <sect id="l10n-handling">How translations are handled within Debian
5367           <p>
5368 Handling translation of the texts contained in a package is still a manual
5369 task, and the process depends on the kind of text you want to see translated.
5370           <p>
5371 For program messages, the gettext infrastructure is used most of the time.
5372 Most of the time, the translation is handled upstream within projects like the
5373 <url id="http://www.iro.umontreal.ca/contrib/po/HTML/" name="Free Translation
5374 Project">, the <url id="http://developer.gnome.org/projects/gtp/" name="Gnome
5375 translation Project"> or the <url id="http://i18n.kde.org/" name="KDE one">.
5376 The only centralized resource within Debian is the <url
5377 id="http://www.debian.org/intl/l10n/" name="Central Debian translation
5378 statistics">, where you can find some statistics about the translation files
5379 found in the actual packages, but no real infrastructure to ease the translation
5380 process.
5381           <p>
5382 An effort to translate the package descriptions started long ago, even if very
5383 little support is offered by the tools to actually use them (i.e., only APT can use
5384 them, when configured correctly). Maintainers don't need to do
5385 anything special to support translated package descriptions;
5386 translators should use the <url id="http://ddtp.debian.org/"
5387 name="DDTP">.
5388           <p>
5389 For debconf templates, maintainers should use the po-debconf package to ease the
5390 work of translators, who could use the DDTP to do their work (but the French and
5391 Brazilian teams don't). Some statistics can be found both on the DDTP site
5392 (about what is actually translated), and on the <url
5393 id="http://www.debian.org/intl/l10n/" name="Central Debian translation
5394 statistics"> site (about what is integrated in the packages). 
5395           <p>
5396 For web pages, each l10n team has access to the relevant CVS, and the statistics
5397 are available from the Central Debian translation statistics site.
5398           <p>
5399 For general documentation about Debian, the process is more or less the same
5400 as for the web pages (the translators have access to the CVS), but there are
5401 no statistics pages.
5402           <p>
5403 For package-specific documentation (man pages, info documents, other formats),
5404 almost everything remains to be done.
5405         <p>
5406 Most notably, the KDE project handles
5407 translation of its documentation in the same way as its program messages.
5408         <p>
5409 There is an effort to handle Debian-specific man pages
5410 within a <url
5411 id="http://cvs.debian.org/manpages/?cvsroot=debian-doc" name="specific CVS
5412 repository">.
5413
5414
5415         <sect id="l10n-faqm">I18N &amp; L10N FAQ for maintainers
5416           <p>
5417 This is a list of problems that maintainers may face concerning i18n and l10n.
5418 While reading this, keep in mind that there is no real consensus on these
5419 points within Debian, and that this is only advice. If you have a better idea
5420 for a given problem, or if you disagree on some points, feel free to provide
5421 your feedback, so that this document can be enhanced.
5422
5423           <sect1 id="l10n-faqm-tr">How to get a given text translated
5424             <p>
5425 To translate package descriptions or debconf templates, you have nothing to do;
5426 the DDTP infrastructure will dispatch the material to translate to volunteers
5427 with no need for interaction from your part.
5428             <p>
5429 For all other material (gettext files, man pages, or other documentation), the
5430 best solution is to put your text somewhere on the Internet, and ask on debian-i18n
5431 for a translation in different languages. Some translation team members are
5432 subscribed to this list, and they will take care of the translation and of the
5433 reviewing process. Once they are done, you will get your translated document from them
5434 in your mailbox.
5435
5436           <sect1 id="l10n-faqm-rev">How to get a given translation reviewed
5437             <p>
5438 From time to time, individuals translate some texts in your package
5439 and will ask you for inclusion of the translation in the package. This can become problematic if
5440 you are not fluent in the given language. It is a good idea to send the
5441 document to the corresponding l10n mailing list, asking for a review. Once it
5442 has been done, you should feel more confident in the quality of the
5443 translation, and feel safe to include it in your package.
5444
5445           <sect1 id="l10n-faqm-update">How to get a given translation updated
5446             <p>
5447 If you have some translations of a given text lying around, each time you
5448 update the original, you should ask the previous translator to update
5449 the translation with your new changes.
5450 Keep in mind that this task takes time; at least one week to get
5451 the update reviewed and all. 
5452             <p>
5453 If the translator is unresponsive, you may ask for help on the corresponding
5454 l10n mailing list. If everything fails, don't forget to put a warning in the
5455 translated document, stating that the translation is somehow outdated, and that
5456 the reader should refer to the original document if possible. 
5457             <p>
5458 Avoid removing a translation completely because it is outdated. Old
5459 documentation is often better than no documentation at all for non-English
5460 speakers.
5461
5462           <sect1 id="l10n-faqm-bug">How to handle a bug report concerning a translation
5463             <p>
5464 The best solution may be to mark the bug as "forwarded to upstream", and
5465 forward it to both the previous translator and his/her team (using the
5466 corresponding debian-l10n-XXX mailing list).
5467 <!-- TODO: add the i18n tag to the bug? -->
5468
5469         <sect id="l10n-faqtr">I18N &amp; L10N FAQ for translators
5470           <p>
5471 While reading this, please keep in mind that there is no general procedure
5472 within Debian concerning these points, and that in any case, you should
5473 collaborate with your team and the package maintainer.
5474
5475           <sect1 id="l10n-faqtr-help">How to help the translation effort
5476             <p>
5477 Choose what you want to translate, make sure that nobody is already working on
5478 it (using your debian-l10n-XXX mailing list), translate it, get it reviewed by
5479 other native speakers on your l10n mailing list, and provide it to the
5480 maintainer of the package (see next point).
5481
5482           <sect1 id="l10n-faqtr-inc">How to provide a translation for inclusion in a package
5483             <p>
5484 Make sure your translation is correct (asking for review on your l10n mailing
5485 list) before providing it for inclusion. It will save time for everyone, and
5486 avoid the chaos resulting in having several versions of the same document in
5487 bug reports.
5488             <p>
5489 The best solution is to file a regular bug containing the translation against
5490 the package. Make sure to use the 'PATCH' tag, and to not use a severity higher
5491 than 'wishlist', since the lack of translation never prevented a program from
5492 running.
5493
5494         <sect id="l10n-best">Best current practice concerning l10n
5495           <p>
5496 <list>
5497     <item>
5498 As a maintainer, never edit the translations in any way (even to reformat the
5499 layout) without asking on the corresponding l10n mailing list. You risk for
5500 example breaksing the encoding of the file by doing so. Moreover, what you
5501 consider an error can be right (or even needed) in the given language.
5502     <item>
5503 As a translator, if you find an error in the original text, make sure to report
5504 it. Translators are often the most attentive readers of a given text, and if
5505 they don't report the errors they find, nobody will.
5506     <item>
5507 In any case, remember that the major issue with l10n is that it requires
5508 several people to cooperate, and that it is very easy to start a flamewar about
5509 small problems because of misunderstandings. So if you have problems with your
5510 interlocutor, ask for help on the corresponding l10n mailing list, on
5511 debian-i18n, or even on debian-devel (but beware, l10n discussions very often
5512 become flamewars on that list :)
5513     <item>
5514 In any case, cooperation can only be achieved with <strong>mutual respect</strong>.
5515 </list>
5516
5517
5518     <appendix id="tools">Overview of Debian Maintainer Tools
5519       <p>
5520 This section contains a rough overview of the tools available to
5521 maintainers.  The following is by no means complete or definitive, but
5522 just a guide to some of the more popular tools.
5523       <p>
5524 Debian maintainer tools are meant to aid developers and 
5525 free their time for critical tasks.  As Larry Wall says, there's more
5526 than one way to do it.
5527       <p>
5528 Some people prefer to use high-level package maintenance tools and
5529 some do not.  Debian is officially agnostic on this issue; any tool
5530 which gets the job done is fine.  Therefore, this section is not meant
5531 to stipulate to anyone which tools they should use or how they should
5532 go about their duties of maintainership.  Nor is it meant to
5533 endorse any particular tool to the exclusion of a competing tool.
5534       <p>
5535 Most of the descriptions of these packages come from the actual
5536 package descriptions themselves.  Further information can be found in
5537 the package documentation itself.  You can also see more info with the
5538 command <tt>apt-cache show &lt;package-name&gt;</tt>.</p>
5539
5540       <sect id="tools-core">
5541         <heading>Core tools</heading>
5542         <p>
5543 The following tools are pretty much required for any maintainer.</p>
5544
5545       <sect1 id="dpkg-dev">
5546         <heading><package>dpkg-dev</package>
5547         <p>
5548 <package>dpkg-dev</package> contains the tools (including
5549 <prgn>dpkg-source</prgn>) required to unpack, build, and upload Debian
5550 source packages.  These utilities contain the fundamental, low-level
5551 functionality required to create and manipulate packages; as such,
5552 they are essential for any Debian maintainer.
5553
5554       <sect1 id="debconf">
5555         <heading><package>debconf</package></heading>
5556         <p>
5557 <package>debconf</package> provides a consistent interface to
5558 configuring packages interactively.  It is user interface
5559 independent, allowing end-users to configure packages with a
5560 text-only interface, an HTML interface, or a dialog interface.  New
5561 interfaces can be added as modules.
5562         <p>
5563 You can find documentation for this package in the
5564 <package>debconf-doc</package> package.
5565         <p>
5566 Many feel that this system should be used for all packages which require
5567 interactive configuration; see <ref id="bpp-config-mgmt">.
5568 <package>debconf</package> is not currently required by Debian Policy,
5569 but that may change in the future.
5570         </sect1>
5571
5572       <sect1 id="fakeroot">
5573         <heading><package>fakeroot</package>
5574         <p>
5575 <package>fakeroot</package> simulates root privileges.  This enables
5576 you to build packages without being root (packages usually want to
5577 install files with root ownership).  If you have
5578 <package>fakeroot</package> installed, you can build packages as a
5579 regular user: <tt>dpkg-buildpackage -rfakeroot</tt>.
5580         </sect1>
5581       </sect>
5582
5583       <sect id="tools-lint">
5584         <heading>Package lint tools</heading>
5585         <p>
5586 According to the Free On-line Dictionary of Computing (FOLDOC), `lint'
5587 is "a Unix C language processor which carries out more thorough checks
5588 on the code than is usual with C compilers."  Package lint tools help
5589 package maintainers by automatically finding common problems and
5590 policy violations in their packages.</p>
5591
5592         <sect1 id="lintian">
5593           <heading><package>lintian</package></heading>
5594           <p>
5595 <package>lintian</package> dissects Debian packages and emits
5596 information about bugs
5597 and policy violations. It contains automated checks for many aspects
5598 of Debian policy as well as some checks for common errors.
5599         <p>
5600 You should periodically get the newest <package>lintian</package> from
5601 `unstable' and check over all your packages. Notice that the <tt>-i</tt>
5602 option provides detailed explanations of what each error or warning means,
5603 what its basis in Policy is, and commonly how you can fix the problem.
5604         <p>
5605 Refer to <ref id="sanitycheck"> for more information on how and when
5606 to use Lintian.
5607         <p>
5608 You can also see a summary of all problems reported by Lintian on your
5609 packages at <url id="&url-lintian;">. These reports contain the latest
5610 <prgn>lintian</prgn> output for the whole development distribution
5611 ("unstable").
5612         </sect1>
5613
5614         <sect1 id="linda">
5615           <heading><package>linda</package></heading>
5616           <p>
5617 <package>linda</package> is another package linter.  It is similar to
5618 <package>lintian</package> but has a different set of checks.  Its
5619 written in Python rather than Perl.</p>
5620         </sect1>
5621
5622         <sect1 id="debdiff">
5623           <heading><package>debdiff</package></heading>
5624           <p>
5625 <prgn>debdiff</prgn> (from the <package>devscripts</package> package, <ref id="devscripts">)
5626 compares file lists and control files of two packages. It is a simple
5627 regression test, as it will help you notice if the number of binary
5628 packages has changed since the last upload, or if something has changed
5629 in the control file. Of course, some of the changes it reports will be
5630 all right, but it can help you prevent various accidents.
5631           <p>
5632 You can run it over a pair of binary packages:
5633 <example>
5634 debdiff package_1-1_arch.deb package_2-1_arch.deb
5635 </example>
5636           <p>
5637 Or even a pair of changes files:
5638 <example>
5639 debdiff package_1-1_arch.changes package_2-1_arch.changes
5640 </example>
5641           <p>
5642 For more information please see <manref name="debdiff" section="1">.
5643         </sect1>
5644
5645       </sect>
5646
5647
5648       <sect id="tools-helpers">
5649         <heading>Helpers for <file>debian/rules</file></heading>
5650         <p>
5651 Package building tools make the process of writing
5652 <file>debian/rules</file> files easier.  See <ref id="helper-scripts">
5653 for more information about why these might or might not be desired.
5654
5655         <sect1 id="debhelper">
5656           <heading><package>debhelper</package></heading>
5657         <p>
5658 <package>debhelper</package> is a collection of programs which can be
5659 used in <file>debian/rules</file> to automate common tasks related to
5660 building binary Debian packages. <package>debhelper</package> includes
5661 programs to install
5662 various files into your package, compress files, fix file permissions,
5663 and integrate your package with the Debian menu system.
5664         <p>
5665 Unlike some approaches, <package>debhelper</package> is broken into
5666 several small, simple commands which act in a consistent manner.  As
5667 such, it allows more fine-grained control than some of the
5668 other "debian/rules tools".
5669         <p>
5670 There are a number of little <package>debhelper</package> add-on
5671 packages, too transient to document.  You can see the list of most of
5672 them by doing <tt>apt-cache search ^dh-</tt>.
5673         </sect1>
5674
5675         <sect1 id="debmake">
5676           <heading><package>debmake</package>
5677         <p>
5678 <package>debmake</package>, a precursor to
5679 <package>debhelper</package>, is a more coarse-grained
5680 <file>debian/rules</file> assistant. It includes two main programs:
5681 <prgn>deb-make</prgn>, which can be used to help a maintainer convert
5682 a regular (non-Debian) source archive into a Debian source package;
5683 and <prgn>debstd</prgn>, which incorporates in one big shot the same
5684 sort of automated functions that one finds in
5685 <package>debhelper</package>.
5686         <p>
5687 The consensus is that <package>debmake</package> is now deprecated in
5688 favor of <package>debhelper</package>.  It is a bug to use
5689 <package>debmake</package> in new packages. New packages using 
5690 <package>debmake</package> will be rejected from the archive.
5691         </sect1>
5692
5693         <sect1 id="dh-make">
5694           <heading><package>dh-make</package>
5695         <p>
5696 The <package/dh-make/ package contains <prgn/dh_make/, a program that
5697 creates a skeleton of files necessary to build a Debian package out of
5698 a source tree. As the name suggests, <prgn/dh_make/ is a rewrite of
5699 <package/debmake/ and its template files use dh_* programs from
5700 <package/debhelper/.
5701         <p>
5702 While the rules files generated by <prgn/dh_make/ are in general a
5703 sufficient basis for a working package, they are still just the groundwork:
5704 the burden still lies on the maintainer to finely tune the generated files
5705 and make the package entirely functional and Policy-compliant.
5706         </sect1>
5707
5708         <sect1 id="yada">
5709           <heading><package>yada</package>
5710         <p>
5711 <package>yada</package> is another packaging helper tool.  It uses a
5712 <file>debian/packages</file> file to auto-generate
5713 <file>debian/rules</file> and other necessary files in the
5714 <file>debian/</file> subdirectory. The <file>debian/packages</file> file
5715 contains instruction to build packages and there is no need to create any
5716 <file>Makefile</file> files.  There is possibility to
5717 use macro engine similar to the one used in SPECS files from RPM
5718 source packages.</p>
5719         <p>
5720 For more informations see
5721 <tt><url id="http://yada.alioth.debian.org/" name="YADA site"></tt>.</p>
5722         </sect1>
5723
5724         <sect1 id="equivs">
5725           <heading><package>equivs</package>
5726         <p>
5727 <package>equivs</package> is another package for making packages.  It
5728 is often suggested for local use if you need to make a package simply
5729 to fulfill dependencies.  It is also sometimes used when making
5730 ``meta-packages'', which are packages whose only purpose is to depend
5731 on other packages.</p>
5732         </sect1>
5733       </sect>
5734
5735
5736
5737       <sect id="tools-builders">
5738         <heading>Package builders</heading>
5739         <p>
5740 The following packages help with the package building process, general
5741 driving <prgn>dpkg-buildpackage</prgn> as well as handling supporting
5742 tasks.</p>
5743
5744         <sect1 id="cvs-buildpackage">
5745           <heading><package>cvs-buildpackage</package>
5746         <p>
5747 <package>cvs-buildpackage</package> provides the capability to inject
5748 or import Debian source packages into a CVS repository, build a Debian
5749 package from the CVS repository, and helps in integrating upstream
5750 changes into the repository.
5751         <p>
5752 These utilities provide an infrastructure to facilitate the use of CVS
5753 by Debian maintainers. This allows one to keep separate CVS branches
5754 of a package for <em>stable</em>, <em>unstable</em> and possibly
5755 <em>experimental</em> distributions, along with the other benefits of
5756 a version control system.
5757         </sect1>
5758
5759         <sect1 id="debootstrap">
5760           <heading><package>debootstrap</package></heading>
5761           <p>
5762 The <package>debootstrap</package> package and script allows you to
5763 "bootstrap" a Debian base system into any part of your filesystem.
5764 By "base system", we mean the bare minimum of packages required to
5765 operate and install the rest of the system.
5766         <p>
5767 Having a system like this can be useful in many ways. For instance,
5768 you can <prgn>chroot</prgn> into it if you want to test your build
5769 dependencies.  Or you can test how your package behaves when installed
5770 into a bare base system.  Chroot builders use this package; see below.
5771         </sect1>
5772
5773         <sect1 id="pbuilder">
5774           <heading><package>pbuilder</package></heading>
5775           <p>
5776 <package>pbuilder</package> constructs a chrooted system, and builds a
5777 package inside the chroot. It is very useful to check that a package's
5778 build-dependencies are correct, and to be sure that unnecessary and
5779 wrong build dependencies will not exist in the resulting package.</p>
5780           <p>
5781 A related package is <package>pbuilder-uml</package>, which goes even
5782 further by doing the build within a User Mode Linux environment.</p>
5783         </sect1>
5784
5785       <sect1 id="sbuild">
5786         <heading><package>sbuild</package></heading>
5787           <p>
5788 <package>sbuild</package> is another automated builder.  It can use
5789 chrooted environments as well.  It can be used stand-alone, or as part
5790 of a networked, distributed build environment.  As the latter, it is
5791 part of the system used by porters to build binary packages for all
5792 the available architectures.  See <ref id="buildd"> for more
5793 information, and <url id="&url-buildd;"> to see the system in
5794 action.</p>
5795         </sect1>
5796       </sect>
5797
5798       <sect id="uploaders">
5799         <heading>Package uploaders</heading>
5800         <p>
5801 The following packages help automate or simplify the process of
5802 uploading packages into the official archive.</p>
5803
5804         <sect1 id="dupload">
5805           <heading><package>dupload</package></heading>
5806           <p>
5807 <package>dupload</package> is a package and a script to automatically
5808 upload Debian packages to the Debian archive, to log the upload, and
5809 to send mail about the upload of a package.  You can configure it for
5810 new upload locations or methods.
5811         </sect1>
5812
5813         <sect1 id="dput">
5814           <heading><package>dput</package></heading>
5815           <p>
5816 The <package>dput</package> package and script does much the same
5817 thing as <package>dupload</package>, but in a different way.  It has
5818 some features over <package>dupload</package>, such as the ability to
5819 check the GnuPG signature and checksums before uploading, and the
5820 possibility of running <prgn>dinstall</prgn> in dry-run mode after the
5821 upload.
5822         </sect1>
5823         <sect1 id="dcut">
5824           <heading><package>dcut</package></heading>
5825           <p>
5826 The <package>dcut</package> script (part of the package <ref id="dput">)
5827 helps in removing files from the ftp upload directory.
5828         </sect1>
5829       </sect>
5830
5831       <sect id="tools-maint-automate">
5832         <heading>Maintenance automation</heading>
5833         <p>
5834 The following tools help automate different maintenance tasks, from
5835 adding changelog entries or signature lines and looking up bugs in Emacs
5836 to making use of the newest and official
5837 <file>config.sub</file>.</p>
5838
5839         <sect1 id="devscripts">
5840           <heading><package>devscripts</package></heading>
5841           <p>
5842 <package>devscripts</package> is a package containing wrappers
5843 and tools which are very helpful for maintaining your Debian
5844 packages.  Example scripts include <prgn>debchange</prgn> and
5845 <prgn>dch</prgn>, which manipulate your <file>debian/changelog</file>
5846 file from the command-line, and <prgn>debuild</prgn>, which is a
5847 wrapper around <prgn>dpkg-buildpackage</prgn>. The <prgn>bts</prgn>
5848 utility is also very helpful to update the state of bug reports on the
5849 command line.  <prgn>uscan</prgn> can be used to watch for new upstream
5850 versions of your packages.  <prgn>debrsign</prgn> can be used to
5851 remotely sign a package prior to upload, which is nice when the
5852 machine you build the package on is different from where your GPG keys
5853 are.</p>
5854           <p>
5855 See the <manref name="devscripts" section="1"> manual page for a
5856 complete list of available scripts.</p>
5857         </sect1>
5858
5859         <sect1 id="autotools-dev">
5860           <heading><package>autotools-dev</package></heading>
5861           <p>
5862 <package>autotools-dev</package>
5863 contains best practices for people who maintain packages which use
5864 <prgn>autoconf</prgn> and/or <prgn>automake</prgn>.  Also contains
5865 canonical <file>config.sub</file> and <file>config.guess</file> files
5866 which are known to work on all Debian ports.</p>
5867         </sect1>
5868
5869         <sect1 id="dpkg-repack">
5870           <heading><package>dpkg-repack</package></heading>
5871           <p>
5872 <prgn>dpkg-repack</prgn> creates Debian package file out of a package
5873 that has already been installed. If any changes have been made to the
5874 package while it was unpacked (e.g., files in <file>/etc</file> were
5875 modified), the new package will inherit the changes.</p>
5876           <p>
5877 This utility can make it easy to copy packages from one computer to
5878 another, or to recreate packages which are installed on your system
5879 but no longer available elsewhere, or to save the current state of a
5880 package before you upgrade it.</p>
5881         </sect1>
5882
5883         <sect1 id="alien">
5884           <heading><package>alien</package></heading>
5885           <p>
5886 <prgn>alien</prgn> converts binary packages between various packaging
5887 formats, including Debian, RPM (RedHat), LSB (Linux Standard Base),
5888 Solaris, and Slackware packages.</p>
5889         </sect1>
5890
5891         <sect1 id="debsums">
5892           <heading><package>debsums</package></heading>
5893           <p>
5894 <prgn>debsums</prgn> checks installed packages against their MD5 sums.
5895 Note that not all packages have MD5 sums, since they aren't required
5896 by Policy.</p>
5897         </sect1>
5898
5899         <sect1 id="dpkg-dev-el">
5900           <heading><package>dpkg-dev-el</package></heading>
5901           <p>
5902 <package>dpkg-dev-el</package> is an Emacs lisp package which provides
5903 assistance when editing some of the files in the <file>debian</file>
5904 directory of your package.  For instance,
5905 there are handy functions for
5906 listing a package's current bugs,
5907 and for finalizing the latest entry in a
5908 <file>debian/changelog</file> file.
5909         </sect1>
5910
5911         <sect1 id="dpkg-depcheck">
5912           <heading><package>dpkg-depcheck</package></heading>
5913           <p>
5914 <prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package> 
5915 package, <ref id="devscripts">)
5916 runs a command under <prgn>strace</prgn> to determine all the packages that
5917 were used by the said command.
5918           <p>
5919 For Debian packages, this is useful when you have to compose a
5920 <tt>Build-Depends</tt> line for your new package: running the build
5921 process through <prgn>dpkg-depcheck</prgn> will provide you with a
5922 good first approximation of the build-dependencies. For example:
5923 <example>
5924 dpkg-depcheck -b debian/rules build
5925 </example>
5926           <p>
5927 <prgn>dpkg-depcheck</prgn> can also be used to check for run-time
5928 dependencies, especially if your package uses exec(2) to run other
5929 programs.
5930           <p>
5931 For more information please see <manref name="dpkg-depcheck" section="1">.
5932         </sect1>
5933
5934       </sect>
5935
5936
5937       <sect id="tools-porting">
5938         <heading>Porting tools</heading>
5939         <p>
5940 The following tools are helpful for porters and for
5941 cross-compilation.</p>
5942
5943         <sect1 id="quinn-diff">
5944           <heading><package>quinn-diff</package>
5945           <p>
5946 <package>quinn-diff</package> is used to locate the differences from
5947 one architecture to another.  For instance, it could tell you which
5948 packages need to be ported for architecture <var>Y</var>, based on
5949 architecture <var>X</var>.
5950
5951         <sect1 id="dpkg-cross">
5952           <heading><package>dpkg-cross</package>
5953           <p>
5954 <package>dpkg-cross</package> is a tool for installing libraries and
5955 headers for cross-compiling in a way similar to
5956 <package>dpkg</package>. Furthermore, the functionality of
5957 <prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
5958 enhanced to support cross-compiling.
5959         </sect1>
5960
5961
5962       <sect id="tools-doc">
5963         <heading>Documentation and information</heading>
5964         <p>
5965 The following packages provide information for maintainers or help
5966 with building documentation.
5967
5968         <sect1 id="debiandoc-sgml">
5969           <heading><package>debiandoc-sgml</package></heading>
5970           <p>
5971 <package>debiandoc-sgml</package> provides the DebianDoc SGML DTD,
5972 which is commonly used for Debian documentation.  This manual, for
5973 instance, is written in DebianDoc.  It also provides scripts for
5974 building and styling the source to various output formats.</p>
5975           <p>
5976 Documentation for the DTD can be found in the
5977 <package>debiandoc-sgml-doc</package> package.</p>
5978         </sect1>
5979
5980         <sect1 id="debian-keyring">
5981           <heading><package>debian-keyring</package></heading>
5982           <p>
5983 Contains the public GPG and PGP keys of Debian developers.  See <ref
5984 id="key-maint"> and the package documentation for more
5985 information.</p>
5986         </sect1>
5987
5988         <sect1 id="debview">
5989           <heading><package>debview</package></heading>
5990           <p>
5991 <package>debview</package> provides an Emacs mode for viewing Debian
5992 binary packages.  This lets you examine a package without unpacking
5993 it.</p>
5994         </sect1>
5995       </sect>
5996
5997 <!-- FIXME: add the following
5998
5999 questionable:
6000   dbs (referred to above)
6001   dpatch (referred to above)
6002   debarchiver
6003   ucf
6004   dpkg-awk
6005   grep-dctrl
6006   d-shlibs
6007   wajig
6008   magpie
6009   apt-dpkg-ref
6010   apt-show-source
6011   apt-show-versions
6012   pdbv
6013   epm
6014   apt-src
6015   apt-build
6016
6017 rejected:
6018   debaux: too new, unmaintained?
6019   dh-make-perl: too new, unmaintained?
6020 -->
6021
6022     </appendix>
6023   </book>
6024 </debiandoc>
6025
6026 <!-- Keep this comment at the end of the file
6027 Local variables:
6028 mode: sgml
6029 sgml-omittag:t
6030 sgml-shorttag:t
6031 sgml-minimize-attributes:nil
6032 sgml-always-quote-attributes:t
6033 sgml-indent-step:2
6034 sgml-indent-data:nil
6035 sgml-parent-document:nil
6036 sgml-exposed-tags:nil
6037 sgml-declaration:nil
6038 sgml-local-catalogs:nil
6039 sgml-local-ecat-files:nil
6040 End:
6041 -->