chiark / gitweb /
Remove all references to non-US.
[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.332 $">
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;2007 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 default.
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 opening a ticket in Debian RT by sending a mail 
478 to keyring@rt.debian.org with the words 'Debian RT' somewhere in the subject
479 line (case doesn't matter).
480 </enumlist>
481
482
483
484    <chapt id="resources">Resources for Debian Developers
485      <p>
486 In this chapter you will find a very brief road map of the Debian
487 mailing lists, the Debian machines
488 which may be available to you as a developer, and all the other
489 resources that are available to help you in your maintainer work.
490
491       <sect id="mailing-lists">Mailing lists
492         <p>
493 Much of the conversation between Debian developers (and users) is managed
494 through a wide array of mailing lists we host at
495 <tt><url id="http://&lists-host;/" name="&lists-host;"></tt>.
496 To find out more on how to subscribe or unsubscribe, how to post and how not
497 to post, where to find old posts and how to search them, how to contact the
498 list maintainers and see various other information about the mailing lists,
499 please read <url id="&url-debian-lists;">. This section will only cover
500 aspects of mailing lists that are of particular interest to developers.
501
502         <sect1 id="mailing-lists-rules">Basic rules for use
503         <p>
504 When replying to messages on the mailing list, please do not send a
505 carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
506 request to be copied.  Anyone who posts to a mailing list should read
507 it to see the responses.
508         <p>
509 Cross-posting (sending the same message to multiple lists) is discouraged.
510 As ever on the net, please trim down the quoting of articles you're
511 replying to.  In general, please adhere to the usual conventions for
512 posting messages.
513         <p>
514 Please read the <url name="code of conduct" id="&url-debian-lists;#codeofconduct">
515 for more information. The <url name="Debian Community Guidelines" id="&url-dcg;">
516 are also worth reading.
517
518         <sect1 id="core-devel-mailing-lists">Core development mailing lists
519         <p>
520 The core Debian mailing lists that developers should use are:
521 <list>
522   <item>&email-debian-devel-announce;, used to announce important things to
523         developers.
524         All developers are expected to be subscribed to this list.
525   </item>
526   <item>&email-debian-devel;, used to discuss various development related
527         technical issues.
528   </item>
529   <item>&email-debian-policy;, where the Debian Policy is discussed and
530         voted on.
531   </item>
532   <item>&email-debian-project;, used to discuss various non-technical
533         issues related to the project.
534   </item>
535 </list>
536         <p>
537 There are other mailing lists available for a variety of special topics;
538 see <url id="http://&lists-host;/"> for a list.
539
540         <sect1 id="mailing-lists-special">Special lists
541         <p>
542 &email-debian-private; is a special mailing list for private
543 discussions amongst Debian developers.  It is meant to be used for
544 posts which for whatever reason should not be published publicly.
545 As such, it is a low volume list, and users are urged not to use
546 &email-debian-private; unless it is really necessary.  Moreover, do
547 <em>not</em> forward email from that list to anyone.  Archives of this
548 list are not available on the web for obvious reasons, but you can see
549 them using your shell account on <tt>lists.debian.org</tt> and looking
550 in the <file>~debian/archive/debian-private</file> directory.
551         <p>
552 &email-debian-email; is a special mailing list used as a grab-bag 
553 for Debian related correspondence such as contacting upstream authors
554 about licenses, bugs, etc. or discussing the project with others where it
555 might be useful to have the discussion archived somewhere.
556
557         <sect1 id="mailing-lists-new">Requesting new development-related lists
558         <p>
559 Before requesting a mailing list that relates to the development of a
560 package (or a small group of related packages), please consider if using
561 an alias (via a .forward-aliasname file on master.debian.org, which
562 translates into a reasonably nice <var>you-aliasname@debian.org</var>
563 address) or a self-managed mailing list on <qref id="alioth">Alioth</qref>
564 is more appropriate.
565         <p>
566 If you decide that a regular mailing list on lists.debian.org is really what
567 you want, go ahead and fill in a request, following <url name="the HOWTO"
568 id="&url-debian-lists-new;">.
569
570       <sect id="irc-channels">IRC channels
571         <p>
572 Several IRC channels are dedicated to Debian's development. They are mainly
573 hosted on the <url id="&url-oftc;" name="Open and free technology community
574 (OFTC)"> network.  The <tt>irc.debian.org</tt> DNS entry is an alias to
575 <tt>irc.oftc.net</tt>.
576         <p>
577 The main channel for Debian in general is <em>#debian</em>. This is a large,
578 general-purpose channel where users can find recent news in the topic and
579 served by bots. <em>#debian</em> is for English speakers; there are also
580 <em>#debian.de</em>, <em>#debian-fr</em>, <em>#debian-br</em> and other
581 similarly named channels for speakers of other languages.
582         <p>
583 The main channel for Debian development is <em>#debian-devel</em>.
584 It is a very active channel since usually over 150 people are always
585 logged in. It's a channel for people who work
586 on Debian, it's not a support channel (there's <em>#debian</em> for that).
587 It is however open to anyone who wants to lurk (and learn). Its topic is
588 commonly full of interesting information for developers.
589         <p>
590 Since <em>#debian-devel</em> is an open channel, you
591 should not speak there of issues that are discussed in
592 &email-debian-private;. There's another channel for this purpose,
593 it's called <em>#debian-private</em> and it's protected by a key.
594 This key is available in the archives of debian-private in
595 <file>master.debian.org:&file-debian-private-archive;</file>,
596 just <prgn>zgrep</prgn> for <em>#debian-private</em> in
597 all the files.
598         <p>
599 There are other additional channels dedicated to specific subjects.
600 <em>#debian-bugs</em> is used for coordinating bug squashing parties.
601 <em>#debian-boot</em> is used to coordinate the work on the debian-installer.
602 <em>#debian-doc</em> is
603 occasionally used to talk about documentation, like the document you are
604 reading. Other channels are dedicated to an architecture or a set of
605 packages: <em>#debian-bsd</em>, <em>#debian-kde</em>, <em>#debian-jr</em>,
606 <em>#debian-edu</em>,
607 <em>#debian-oo</em> (OpenOffice
608 package) ...
609         <p>
610 Some non-English developers' channels exist as well, for example
611 <em>#debian-devel-fr</em> for
612 French speaking people interested in Debian's development.
613         <p>
614 Channels dedicated to Debian also exist on other IRC networks, notably on
615 the <url id="&url-openprojects;" name="freenode"> IRC network, which was 
616 pointed at by the <tt>irc.debian.org</tt> alias until 4th June 2006.
617         <p>
618 To get a cloak on freenode, you send J&ouml;rg Jaspert &lt;joerg@debian.org&gt;
619 a signed mail where you tell what your nick is.
620 Put "cloak" somewhere in the Subject: header.
621 The nick should be registered:
622 <url id="http://freenode.net/faq.shtml#nicksetup" name="Nick Setup Page">.
623 The mail needs to be signed by a key in the Debian keyring.
624 Please see
625 <url id="http://freenode.net/faq.shtml#projectcloak" name="Freenodes documentation">
626 for more information about cloaks.
627
628
629       <sect id="doc-rsrcs">Documentation
630         <p>
631 This document contains a lot of information
632 which is useful to Debian developers,
633 but it cannot contain everything. Most of the other interesting documents
634 are linked from <url id="&url-devel-docs;" name="The Developers' Corner">.
635 Take the time to browse all the links, you will learn many more things.
636
637
638       <sect id="server-machines">Debian machines
639         <p>
640 Debian has several computers working as servers, most of which serve
641 critical functions in the Debian project. Most of the machines are used
642 for porting activities, and they all have a permanent connection to the
643 Internet.
644         <p>
645 Some of the machines are available for individual developers to use,
646 as long as the developers follow the rules set forth in the
647 <url name="Debian Machine Usage Policies" id="&url-dmup;">.
648         <p>
649 Generally speaking, you can use these machines for Debian-related purposes
650 as you see fit.  Please be kind to system administrators, and do not use
651 up tons and tons of disk space, network bandwidth, or CPU without first
652 getting the approval of the system administrators.  Usually these machines are run by
653 volunteers.
654         <p>
655 Please take care to protect your Debian passwords and SSH keys installed on
656 Debian machines. Avoid login or upload methods which send passwords over
657 the Internet in the clear, such as telnet, FTP, POP etc.
658         <p>
659 Please do not put any material that doesn't relate to Debian on the Debian
660 servers, unless you have prior permission.
661         <p>
662 The current list of Debian machines is available at
663 <url id="&url-devel-machines;">. That web page contains machine names,
664 contact information, information about who can log in, SSH keys etc.
665         <p>
666 If you have a problem with the operation of a Debian server, and you
667 think that the system operators need to be notified of this problem,
668 you can check the list of open issues in the DSA queue of our request
669 tracker at <url id="&url-rt;"> (you can login with user "guest" and
670 password "readonly"). To report a new problem, simply send a mail to
671 <email>admin@rt.debian.org</email> and make sure to put the string
672 "Debian RT" somewhere in the subject.
673         <p>
674 If you have a problem with a certain service, not related to the system
675 administration (such as packages to be removed from the archive,
676 suggestions for the web site, etc.),
677 generally you'll report a bug against a ``pseudo-package''.  See <ref
678 id="submit-bug"> for information on how to submit bugs.
679         <p>
680 Some of the core servers are restricted, but the information from there
681 is mirrored to another server.
682
683       <sect1 id="servers-bugs">The bugs server
684         <p>
685 <tt>&bugs-host;</tt> is the canonical location for the Bug Tracking
686 System (BTS).
687         <p>
688 It is restricted; a mirror is available on <tt>merkel</tt>.
689         <p>
690 If you plan on doing some statistical analysis or
691 processing of Debian bugs, this would be the place to do it.  Please
692 describe your plans on &email-debian-devel; before implementing
693 anything, however, to reduce unnecessary duplication of effort or
694 wasted processing time.
695
696       <sect1 id="servers-ftp-master">The ftp-master server
697         <p>
698 The <tt>ftp-master.debian.org</tt> server holds the canonical copy of the Debian
699 archive. Generally, package uploads
700 go to this server; see <ref id="upload">.
701         <p>
702 It is restricted; a mirror is available on <tt>merkel</tt>.
703         <p>
704 Problems with the Debian FTP archive generally need to be reported as
705 bugs against the <package>ftp.debian.org</package> pseudo-package or
706 an email to &email-ftpmaster;, but also see the procedures in
707 <ref id="archive-manip">.
708
709       <sect1 id="servers-www">The www-master server
710         <p>
711 The main web server is <tt>www-master.debian.org</tt>.
712 It holds the official web pages, the face
713 of Debian for most newbies.
714         <p>
715 If you find a problem with the Debian web server, you should generally
716 submit a bug against the pseudo-package,
717 <package>www.debian.org</package>. Remember to check whether or not someone
718 else has already reported the problem to the
719 <url id="http://&bugs-host;/www.debian.org" name="Bug Tracking System">.
720
721       <sect1 id="servers-people">The people web server
722         <p>
723 <tt>people.debian.org</tt> is the server used
724 for developers' own web pages about anything related to Debian.
725         <p>
726 If you have some Debian-specific information which you want to serve
727 on the web, you can do this by putting material in the
728 <file>public_html</file> directory under your home directory on
729 <tt>people.debian.org</tt>.
730 This will be accessible at the URL
731 <tt>http://people.debian.org/~<var>your-user-id</var>/</tt>.
732         <p>
733 You should only use this particular location because it will be backed up,
734 whereas on other hosts it won't.
735         <p>
736 Usually the only reason to use a different host is when you need to publish
737 materials subject to the U.S. export restrictions, in which case you can use
738 one of the other servers located outside the United States.
739         <p>
740 Send mail to &email-debian-devel; if you have any questions.
741
742       <sect1 id="servers-cvs">The CVS server
743 <!-- TODO: document svn.debian.org, arch.debian.org also -->
744         <p>
745 Our CVS server is located on <tt>cvs.debian.org</tt>.
746         <p>
747 If you need to use a publicly accessible CVS
748 server, for instance, to help coordinate work on a package between
749 many different developers, you can request a CVS area on the server.
750           <p>
751 Generally, <tt>cvs.debian.org</tt> offers a combination of local CVS
752 access, anonymous client-server read-only access, and full
753 client-server access through <prgn>ssh</prgn>.  Also, the CVS area can
754 be accessed read-only via the Web at <url id="&url-cvsweb;">.
755         <p>
756 To request a CVS area, send a request via email to
757 &email-debian-admin;.  Include the name of the requested CVS area,
758 the Debian account that should own the CVS root area, and why you need it.
759
760       <sect1 id="dchroot">chroots to different distributions
761         <p>
762 On some machines, there are chroots to different distributions available.
763 You can use them like this:
764
765 <example>
766 vore% dchroot unstable
767 Executing shell in chroot: /org/vore.debian.org/chroots/user/unstable
768 </example>
769
770 In all chroots, the normal user home directories are available.
771 You can find out which chroots are available via
772 <tt>&url-devel-machines;</tt>.
773
774
775     <sect id="devel-db">The Developers Database
776         <p>
777 The Developers Database, at <url id="&url-debian-db;">, is an LDAP
778 directory for managing Debian developer attributes.  You can use this
779 resource to search the list of Debian developers.
780 Part of this information is also available through
781 the finger service on Debian servers, try
782 <prgn>finger yourlogin@db.debian.org</prgn> to see what it reports.
783         <p>
784 Developers can <url name="log into the database" id="&url-debian-db-login;">
785 to change various information about themselves, such as:
786 <list>
787         <item>forwarding address for your debian.org email
788         <item>subscription to debian-private
789         <item>whether you are on vacation
790         <item>personal information such as your address, country,
791               the latitude and longitude of the place where you live
792               for use in <url name="the world map of Debian developers"
793               id="&url-worldmap;">, phone and fax numbers, IRC nickname
794               and web page
795         <item>password and preferred shell on Debian Project machines
796 </list>
797         <p>
798 Most of the information is not accessible to the public, naturally.
799 For more information please read the online documentation that you can find
800 at <url id="&url-debian-db-doc;">.
801         <p>
802 Developers can also submit their SSH keys to be used for authorization on the
803 official Debian machines, and even add new *.debian.net DNS entries.
804 Those features are documented at <url id="&url-debian-db-mail-gw;">.
805
806
807     <sect id="archive">The Debian archive
808         <p>
809 The &debian-formal; distribution consists of a lot of packages
810 (<file>.deb</file>'s, currently around &number-of-pkgs;) and a few
811 additional files (such as documentation and installation disk images).
812         <p>
813 Here is an example directory tree of a complete Debian archive:
814         <p>
815 &sample-dist-dirtree;
816         <p>
817 As you can see, the top-level directory contains two directories,
818 <file>dists/</file> and <file>pool/</file>. The latter is a &ldquo;pool&rdquo; in which the
819 packages actually are, and which is handled by the archive maintenance
820 database and the accompanying programs. The former contains the
821 distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>.
822 The <file>Packages</file> and <file>Sources</file> files in the
823 distribution subdirectories can reference files in the <file>pool/</file>
824 directory. The directory tree below each of the distributions is arranged
825 in an identical manner.  What we describe below for <em>stable</em> is
826 equally applicable to the <em>unstable</em> and <em>testing</em>
827 distributions. 
828         <p>
829 <file>dists/stable</file> contains three directories, namely <file>main</file>,
830 <file>contrib</file>, and <file>non-free</file>. 
831         <p>
832 In each of the areas, there is a directory for the source packages
833 (<file>source</file>) and a directory for each supported architecture
834 (<file>binary-i386</file>, <file>binary-m68k</file>, etc.).
835         <p>
836 The <file>main</file> area contains additional directories which hold
837 the disk images and some essential pieces of documentation required
838 for installing the Debian distribution on a specific architecture
839 (<file>disks-i386</file>, <file>disks-m68k</file>, etc.).
840
841
842       <sect1 id="archive-sections">Sections
843         <p>
844 The <em>main</em> section of the Debian archive is what makes up the
845 <strong>official &debian-formal; distribution</strong>.  The
846 <em>main</em> section is official because it fully complies with all
847 our guidelines.  The other two sections do not, to different degrees;
848 as such, they are <strong>not</strong> officially part of
849 &debian-formal;.
850         <p>
851 Every package in the main section must fully comply with the <url
852 id="&url-dfsg;" name="Debian Free Software Guidelines"> (DFSG) and
853 with all other policy requirements as described in the <url
854 id="&url-debian-policy;" name="Debian Policy Manual">.  The DFSG is
855 our definition of &ldquo;free software.&rdquo;  Check out the Debian Policy
856 Manual for details.
857         <p>
858 Packages in the <em>contrib</em> section have to comply with the DFSG,
859 but may fail other requirements.  For instance, they may depend on
860 non-free packages.
861         <p>
862 Packages which do not conform to the DFSG are placed in the
863 <em>non-free</em> section. These packages are not considered as part
864 of the Debian distribution, though we support their use, and we
865 provide infrastructure (such as our bug-tracking system and mailing
866 lists) for non-free software packages.
867         <p>
868 The <url id="&url-debian-policy;" name="Debian Policy Manual">
869 contains a more exact definition of the three sections. The above
870 discussion is just an introduction.
871         <p>
872 The separation of the three sections at the top-level of the archive
873 is important for all people who want to distribute Debian, either via
874 FTP servers on the Internet or on CD-ROMs: by distributing only the
875 <em>main</em> and <em>contrib</em> sections, one can avoid any legal
876 risks.  Some packages in the <em>non-free</em> section do not allow
877 commercial distribution, for example.
878         <p>
879 On the other hand, a CD-ROM vendor could easily check the individual
880 package licenses of the packages in <em>non-free</em> and include as
881 many on the CD-ROMs as it's allowed to. (Since this varies greatly from
882 vendor to vendor, this job can't be done by the Debian developers.)
883         <p>
884 Note that the term "section" is also used to refer to categories
885 which simplify the organization and browsing of available packages, e.g.
886 <em>admin</em>, <em>net</em>, <em>utils</em> etc. Once upon a time, these
887 sections (subsections, rather) existed in the form of subdirectories within
888 the Debian archive. Nowadays, these exist only in the "Section" header
889 fields of packages.
890
891
892       <sect1>Architectures
893         <p>
894 In the first days, the Linux kernel was only available for Intel
895 i386 (or greater) platforms, and so was Debian. But as Linux became
896 more and more popular, the kernel was ported to other architectures,
897 too.
898         <p>
899 The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola
900 680x0 (like Atari, Amiga and Macintoshes), MIPS, and PowerPC.  The
901 Linux 2.2 kernel supports even more architectures, including ARM and
902 UltraSPARC.  Since Linux supports these platforms, Debian decided that
903 it should, too.  Therefore, Debian has ports underway; in fact, we
904 also have ports underway to non-Linux kernels.  Aside from
905 <em>i386</em> (our name for Intel x86), there is <em>m68k</em>,
906 <em>alpha</em>, <em>powerpc</em>, <em>sparc</em>, <em>hurd-i386</em>,
907 <em>arm</em>, <em>ia64</em>, <em>hppa</em>, <em>s390</em>, <em>mips</em>,
908 <em>mipsel</em> and <em>sh</em> as of this writing.
909         <p>
910 &debian-formal; 1.3 is only available as <em>i386</em>.  Debian 2.0
911 shipped for <em>i386</em> and <em>m68k</em> architectures.  Debian 2.1
912 ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and
913 <em>sparc</em> architectures.  Debian 2.2 added support for the
914 <em>powerpc</em> and <em>arm</em> architectures. Debian 3.0 added
915 support of five new architectures: <em>ia64</em>, <em>hppa</em>,
916 <em>s390</em>, <em>mips</em> and <em>mipsel</em>.
917         <p>
918 Information for developers and users about the specific ports are
919 available at the <url id="&url-debian-ports;" name="Debian Ports web
920 pages">.
921
922
923
924       <sect1>Packages
925         <p>
926 There are two types of Debian packages, namely <em>source</em> and
927 <em>binary</em> packages.
928         <p>
929 Source packages consist of either two or three files: a <file>.dsc</file>
930 file, and either a <file>.tar.gz</file> file or both an
931 <file>.orig.tar.gz</file> and a <file>.diff.gz</file> file.
932         <p>
933 If a package is developed specially for Debian and is not distributed
934 outside of Debian, there is just one <file>.tar.gz</file> file which
935 contains the sources of the program.  If a package is distributed
936 elsewhere too, the <file>.orig.tar.gz</file> file stores the so-called
937 <em>upstream source code</em>, that is the source code that's
938 distributed by the <em>upstream maintainer</em> (often the author of
939 the software). In this case, the <file>.diff.gz</file> contains the
940 changes made by the Debian maintainer.
941         <p>
942 The <file>.dsc</file> file lists all the files in the source package together
943 with checksums (<prgn>md5sums</prgn>) and some additional info about
944 the package (maintainer, version, etc.).
945
946
947       <sect1>Distributions
948         <p>
949 The directory system described in the previous chapter is itself
950 contained within <em>distribution directories</em>.  Each
951 distribution is actually contained in the <file>pool</file> directory in the
952 top-level of the Debian archive itself.
953         <p>
954 To summarize, the Debian archive has a root directory within an FTP
955 server.  For instance, at the mirror site,
956 <ftpsite>ftp.us.debian.org</ftpsite>, the Debian archive itself is
957 contained in <ftppath>/debian</ftppath>, which is a common location
958 (another is <file>/pub/debian</file>).
959         <p>
960 A distribution comprises Debian source and binary packages, and the
961 respective <file>Sources</file> and <file>Packages</file> index files, containing
962 the header information from all those packages. The former are kept in the
963 <file>pool/</file> directory, while the latter are kept in the <file>dists/</file>
964 directory of the archive (for backwards compatibility).
965
966
967         <sect2 id="sec-dists">Stable, testing, and unstable
968         <p>
969 There are always distributions called <em>stable</em> (residing in
970 <file>dists/stable</file>), <em>testing</em> (residing in
971 <file>dists/testing</file>), and <em>unstable</em> (residing in
972 <file>dists/unstable</file>). This reflects the development process of the
973 Debian project.
974         <p>
975 Active development is done in the <em>unstable</em> distribution
976 (that's why this distribution is sometimes called the <em>development
977 distribution</em>). Every Debian developer can update his or her
978 packages in this distribution at any time. Thus, the contents of this
979 distribution change from day to day. Since no special effort is made
980 to make sure everything in this distribution is working properly, it is
981 sometimes literally unstable.
982         <p>
983 The <qref id="testing">"testing"</qref> distribution is generated
984 automatically by taking
985 packages from unstable if they satisfy certain criteria. Those
986 criteria should ensure a good quality for packages within testing.
987 The update to testing is launched each day after the
988 new packages have been installed. See <ref id="testing">.
989         <p>
990 After a period of development, once the release manager deems fit, the
991 <em>testing</em> distribution is frozen, meaning that the policies
992 which control how packages move from <em>unstable</em> to <em>testing</em> are
993 tightened.  Packages which are too buggy are removed.  No changes are
994 allowed into <em>testing</em> except for bug fixes.  After some time
995 has elapsed, depending on progress, the <em>testing</em> distribution
996 is frozen even further.
997 Details of the handling of the testing distribution are published
998 by the Release Team on debian-devel-announce.
999 After the open issues are solved to the satisfaction of the Release Team,
1000 the distribution is released.
1001 Releasing means
1002 that <em>testing</em> is renamed to <em>stable</em>,
1003 and a new copy is created for the new <em>testing</em>,
1004 and the previous <em>stable</em> is renamed to <em>oldstable</em>
1005 and stays there until it is finally archived.
1006 On archiving, the contents are moved to <tt>&archive-host;</tt>).
1007         <p>
1008 This development cycle is based on the assumption that the
1009 <em>unstable</em> distribution becomes <em>stable</em> after passing a
1010 period of being in <em>testing</em>.  Even once a distribution is
1011 considered stable, a few bugs inevitably remain &mdash; that's why the
1012 stable distribution is updated every now and then. However, these
1013 updates are tested very carefully and have to be introduced into the
1014 archive individually to reduce the risk of introducing new bugs.  You
1015 can find proposed additions to <em>stable</em> in the
1016 <file>proposed-updates</file> directory.  Those packages in
1017 <file>proposed-updates</file> that pass muster are periodically moved as a
1018 batch into the stable distribution and the revision level of the
1019 stable distribution is incremented (e.g., &lsquo;3.0&rsquo; becomes
1020 &lsquo;3.0r1&rsquo;, &lsquo;2.2r4&rsquo; becomes &lsquo;2.2r5&rsquo;, and
1021 so forth).
1022 Please refer to
1023 <qref id="upload-stable">uploads to the <em>stable</em> distribution</qref>
1024 for details.
1025         <p>
1026 Note that development under <em>unstable</em> continues during the
1027 freeze period, since the <em>unstable</em> distribution remains in
1028 place in parallel with <em>testing</em>.
1029
1030     <sect2>
1031         <heading>More information about the testing distribution</heading>
1032         <p>
1033 Packages are usually installed into the `testing' distribution after they
1034 have undergone some degree of testing in unstable.
1035         <p>
1036 For more details, please see the <qref id="testing">information about the
1037 testing distribution</qref>.
1038
1039         <sect2 id="experimental">Experimental
1040           <p>
1041 The <em>experimental</em> distribution is a special distribution.
1042 It is not a full distribution in the same sense as `stable' and
1043 `unstable' are.  Instead, it is meant to be a temporary staging area
1044 for highly experimental software where there's a good chance that the
1045 software could break your system, or software that's just too unstable
1046 even for the <em>unstable</em> distribution (but there is a reason to
1047 package it nevertheless).  Users who download and install
1048 packages from <em>experimental</em> are expected to have been duly
1049 warned.  In short, all bets are off for the <em>experimental</em>
1050 distribution.
1051           <p>
1052 These are the <manref name="sources.list" section="5"> lines for
1053 <em>experimental</em>:
1054 <example>
1055 deb http://ftp.<var>xy</var>.debian.org/debian/ experimental main
1056 deb-src http://ftp.<var>xy</var>.debian.org/debian/ experimental main
1057 </example>
1058           <p>
1059 If there is a chance that the software could do grave damage to a system,
1060 it is likely to be better to put it into <em>experimental</em>.
1061 For instance, an experimental compressed file system should probably go
1062 into <em>experimental</em>.
1063           <p>
1064 Whenever there is a new upstream version of a package that introduces new
1065 features but breaks a lot of old ones, it should either not be uploaded, or
1066 be uploaded to <em>experimental</em>. A new, beta, version of some software
1067 which uses a completely different configuration can go into
1068 <em>experimental</em>, at the maintainer's discretion. If you are working
1069 on an incompatible or complex upgrade situation, you can also use
1070 <em>experimental</em> as a staging area, so that testers can get early
1071 access.
1072           <p>
1073 Some experimental software can still go into <em>unstable</em>, with a few
1074 warnings in the description, but that isn't recommended because packages
1075 from <em>unstable</em> are expected to propagate to <em>testing</em> and
1076 thus to <em>stable</em>. You should not be afraid to use
1077 <em>experimental</em> since it does not cause any pain to the ftpmasters,
1078 the experimental packages are automatically removed once you upload
1079 the package in <em>unstable</em> with a higher version number.
1080           <p>
1081 New software which isn't likely to damage your system can go directly into
1082 <em>unstable</em>.
1083           <p>
1084 An alternative to <em>experimental</em> is to use your personal web space
1085 on <tt>people.debian.org</tt>.
1086           <p>
1087 When uploading to unstable a package which had bugs fixed in experimental,
1088 please consider using the option <tt>-v</tt> to <prgn>dpkg-buildpackage</prgn>
1089 to finally get them closed.
1090
1091       <sect1 id="codenames">Release code names
1092         <p>
1093 Every released Debian distribution has a <em>code name</em>: Debian
1094 1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0,
1095 `hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; Debian 3.0, `woody';
1096 Debian 3.1, "sarge";
1097 Debian 4.0, "etch".  
1098 There is also a ``pseudo-distribution'', called `sid', which is the current
1099 `unstable' distribution; since packages are moved from `unstable' to
1100 `testing' as they approach stability, `sid' itself is never released.
1101 As well as the usual contents of a Debian distribution, `sid' contains
1102 packages for architectures which are not yet officially supported or
1103 released by Debian.  These architectures are planned to be integrated
1104 into the mainstream distribution at some future date.
1105         <p>
1106 Since Debian has an open development model (i.e., everyone can
1107 participate and follow the development) even the `unstable' and `testing'
1108 distributions are distributed to the Internet through the Debian FTP and
1109 HTTP server network. Thus, if we had called the directory which contains
1110 the release candidate version `testing', then we would have to rename it
1111 to `stable' when the version is released, which would cause all FTP
1112 mirrors to re-retrieve the whole distribution (which is quite large).
1113         <p>
1114 On the other hand, if we called the distribution directories
1115 <em>Debian-x.y</em> from the beginning, people would think that Debian
1116 release <em>x.y</em> is available. (This happened in the past, where a
1117 CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development
1118 version. That's the reason why the first official Debian release was
1119 1.1, and not 1.0.)
1120         <p>
1121 Thus, the names of the distribution directories in the archive are
1122 determined by their code names and not their release status (e.g.,
1123 `slink').  These names stay the same during the development period and
1124 after the release; symbolic links, which can be changed easily,
1125 indicate the currently released stable distribution.  That's why the
1126 real distribution directories use the <em>code names</em>, while
1127 symbolic links for <em>stable</em>, <em>testing</em>, and
1128 <em>unstable</em> point to the appropriate release directories.
1129
1130
1131     <sect id="mirrors">Debian mirrors
1132         <p>
1133 The various download archives and the web site have several mirrors
1134 available in order to relieve our canonical servers from heavy load.
1135 In fact, some of the canonical servers aren't public &mdash; a first tier
1136 of mirrors balances the load instead. That way, users always access
1137 the mirrors and get used to using them, which allows Debian to better
1138 spread its bandwidth requirements over several servers and networks,
1139 and basically makes users avoid hammering on one primary location.
1140 Note that the first tier of mirrors is as up-to-date as it can be since
1141 they update when triggered from the internal sites (we call this
1142 "push mirroring").
1143         <p>
1144 All the information on Debian mirrors, including a list of the available
1145 public FTP/HTTP servers, can be found at <url id="&url-debian-mirrors;">.
1146 This useful page also includes information and tools which can be helpful if
1147 you are interested in setting up your own mirror, either for internal or
1148 public access.
1149         <p>
1150 Note that mirrors are generally run by third-parties who are
1151 interested in helping Debian.  As such, developers generally do not
1152 have accounts on these machines.
1153
1154
1155     <sect id="incoming-system">
1156         <heading>The Incoming system
1157         <p>
1158 The Incoming system is responsible for collecting updated packages and
1159 installing them in the Debian archive. It consists of a set of
1160 directories and scripts that are installed on <tt>&ftp-master-host;</tt>.
1161         <p>
1162 Packages are uploaded by all the maintainers into a directory called
1163 <file>UploadQueue</file>. 
1164 This directory is scanned every few minutes by a daemon called
1165 <prgn>queued</prgn>, <file>*.command</file>-files are executed, and
1166 remaining and correctly signed <file>*.changes</file>-files are moved
1167 together with their corresponding files to the <file>unchecked</file>
1168 directory.
1169 This directory is not visible for most Developers, as ftp-master is restricted;
1170 it is scanned every 15 minutes by
1171 the <prgn>katie</prgn> script, which verifies the integrity of the uploaded
1172 packages and their cryptographic signatures.
1173 If the package is considered ready to be installed, it
1174 is moved into the <file>accepted</file> directory. If this is the first upload of
1175 the package (or it has new binary packages),
1176 it is moved to the <file>new</file> directory, where it waits
1177 for approval by the ftpmasters. If the package contains files to be installed
1178 "by hand" it is moved to the <file>byhand</file> directory, where it waits
1179 for manual installation by the ftpmasters. Otherwise, if any error has been detected,
1180 the package is refused and is moved to the <file>reject</file> directory.
1181         <p>
1182 Once the package is accepted, the system sends a confirmation
1183 mail to the maintainer and closes all the bugs marked as fixed by the upload,
1184 and the auto-builders may start recompiling it. The package is now publicly
1185 accessible at <url id="&url-incoming;">
1186 until it is really installed
1187 in the Debian archive.
1188 This happens only once a day
1189 (and is also called the `dinstall run' for historical reasons);
1190 the package
1191 is then removed from incoming and installed in the pool along with all
1192 the other packages. Once all the other updates (generating new
1193 <file>Packages</file> and <file>Sources</file> index files for example) have been
1194 made, a special script is called to ask all the primary mirrors to update
1195 themselves.
1196         <p>
1197 The archive maintenance software will also send the OpenPGP/GnuPG signed
1198 <file>.changes</file> file that you uploaded to the appropriate mailing
1199 lists. If a package is released with the <tt>Distribution:</tt> set to
1200 `stable', the announcement is sent to &email-debian-changes;.
1201 If a package is released with <tt>Distribution:</tt> set to `unstable'
1202 or `experimental', the announcement will be posted to
1203 &email-debian-devel-changes; instead.
1204         <p>
1205 Though ftp-master is restricted, a copy of the installation is available
1206 to all developers on <tt>&ftp-master-mirror;</tt>.
1207 <!-- FIXME: delete it or keep it for historical purposes?
1208         <p>
1209 All Debian developers have write access to the <file>unchecked</file>
1210 directory in order to upload their packages; they also have that access
1211 to the <file>reject</file> directory in order to remove their bad uploads
1212 or to move some files back to the <file>unchecked</file> directory. But
1213 all the other directories are only writable by the ftpmasters, which is
1214 why you cannot remove an upload once it has been accepted.
1215
1216       <sect1 id="delayed-incoming-broken">Delayed incoming
1217         <p>
1218 <em>Note:</em> This description here is currently not working, because
1219 ftp-master is restricted. Please see <ref id="delayed-incoming"> for
1220 the currently working way.
1221         <p>
1222 The <file>unchecked</file> directory has a special <file>DELAYED</file>
1223 subdirectory. It is itself subdivided in nine directories
1224 called <file>1-day</file> to <file>9-day</file>. Packages which are uploaded to
1225 one of those directories will be moved to the real unchecked
1226 directory after the corresponding number of days.
1227 This is done by a script which is run each day and which moves the
1228 packages between the directories. Those which are in "1-day" are
1229 installed in <file>unchecked</file> while the others are moved to the 
1230 adjacent directory (for example, a package in <file>5-day</file> will
1231 be moved to <file>4-day</file>). This feature is particularly useful
1232 for people who are doing non-maintainer uploads. Instead of
1233 waiting before uploading a NMU, it is uploaded as soon as it is
1234 ready, but to one of those <file>DELAYED/<var>x</var>-day</file> directories.
1235 That leaves the corresponding number of days for the maintainer
1236 to react and upload another fix themselves if they are not
1237 completely satisfied with the NMU. Alternatively they can remove
1238 the NMU.
1239         <p>
1240 The use of that delayed feature can be simplified with a bit
1241 of integration with your upload tool.  For instance, if you use 
1242 <prgn>dupload</prgn> (see <ref id="dupload">), you can add this
1243 snippet to your configuration file:
1244 <example>
1245 $delay = ($ENV{DELAY} || 7);
1246 $cfg{'delayed'} = {
1247          fqdn => "&ftp-master-host;",
1248          login => "yourdebianlogin",
1249          incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
1250          dinstall_runs => 1,
1251          method => "scpb"
1252 };
1253 </example>
1254 Once you've made that change, <prgn>dupload</prgn> can be used to
1255 easily upload a package in one of the delayed directories:
1256 <example>DELAY=5 dupload -X-to delayed &lt;changes-file&gt;</example>
1257 -->
1258
1259
1260     <sect id="pkg-info">Package information
1261         <p>
1262
1263       <sect1 id="pkg-info-web">On the web
1264         <p>
1265 Each package has several dedicated web pages.
1266 <tt>http://&packages-host;/<var>package-name</var></tt>
1267 displays each version of the package
1268 available in the various distributions.  Each version links to a page
1269 which provides information, including the package description,
1270 the dependencies, and package download links.
1271         <p>
1272 The bug tracking system tracks bugs for each package.
1273 You can view the bugs of a given package at the URL
1274 <tt>http://&bugs-host;/<var>package-name</var></tt>.
1275
1276       <sect1 id="madison">The <prgn>madison</prgn> utility
1277         <p>
1278 <prgn>madison</prgn> is a command-line utility that is available
1279 on <tt>&ftp-master-host;</tt>, and on
1280 the mirror on <tt>&ftp-master-mirror;</tt>. It
1281 uses a single argument corresponding to a package name. In result
1282 it displays which version of the package is available for each
1283 architecture and distribution combination. An example will explain
1284 it better.
1285         <p>
1286 <example>
1287 $ madison libdbd-mysql-perl
1288 libdbd-mysql-perl |   1.2202-4 |        stable | source, alpha, arm, i386, m68k, powerpc, sparc
1289 libdbd-mysql-perl |   1.2216-2 |       testing | source, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
1290 libdbd-mysql-perl | 1.2216-2.0.1 |       testing | alpha
1291 libdbd-mysql-perl |   1.2219-1 |      unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
1292 </example>
1293         <p>
1294 In this example, you can see that the version in <em>unstable</em> differs from
1295 the version in <em>testing</em> and that there has been a binary-only NMU of the
1296 package for the alpha architecture. Each version of the package has been
1297 recompiled on most of the architectures.
1298
1299     <sect id="pkg-tracking-system">The Package Tracking System
1300         <p>
1301 The Package Tracking System (PTS) is an email-based tool to track
1302 the activity of a source package. This really means that you can
1303 get the same emails that the package maintainer gets, simply by
1304 subscribing to the package in the PTS.
1305         <p>
1306 Each email sent through the PTS is classified under one of
1307 the keywords listed below. This will let you select the mails that
1308 you want to receive.
1309         <p>
1310 By default you will get:
1311 <taglist>
1312     <tag><tt>bts</tt>
1313     <item>
1314 All the bug reports and following discussions.
1315
1316     <tag><tt>bts-control</tt>
1317     <item>
1318 The email notifications from <email>control@bugs.debian.org</email>
1319 about bug report status changes.
1320     
1321     <tag><tt>upload-source</tt>
1322     <item>
1323 The email notification from <prgn>katie</prgn> when an uploaded source
1324 package is accepted.
1325
1326     <tag><tt>katie-other</tt>
1327     <item>
1328 Other warning and error emails from <prgn>katie</prgn> (such as an
1329 override disparity for the section and/or the priority field).
1330
1331     <tag><tt>default</tt>
1332     <item>
1333 Any non-automatic email sent to the PTS by people who wanted to
1334 contact the subscribers of the package. This can be done by sending mail
1335 to <tt><var>sourcepackage</var>@&pts-host;</tt>. In order to prevent spam,
1336 all messages sent to these addresses must contain the <tt>X-PTS-Approved</tt>
1337 header with a non-empty value.
1338
1339     <tag><tt>summary</tt>
1340     <item>
1341 Regular summary emails about the package's status.
1342 Currently, only progression in <em>testing</em> is sent.
1343
1344 </taglist>
1345
1346         <p>
1347 You can also decide to receive additional information:
1348 <taglist>
1349     <tag><tt>upload-binary</tt>
1350     <item>
1351 The email notification from <prgn>katie</prgn> when an uploaded binary
1352 package is accepted. In other words, whenever a build daemon or a porter
1353 uploads your package for another architecture, you can get an email to
1354 track how your package gets recompiled for all architectures.
1355
1356     <tag><tt>cvs</tt>
1357     <item>
1358 CVS commit notifications, if the package has a CVS repository and the
1359 maintainer has set up forwarding commit notifications to the PTS.
1360
1361     <tag><tt>ddtp</tt>
1362     <item>
1363 Translations of descriptions or debconf templates
1364 submitted to the Debian Description Translation Project.
1365
1366     <tag><tt>derivatives</tt>
1367     <item>
1368 Information about changes made to the package in derivative distributions
1369 (for example Ubuntu).
1370 </taglist>
1371
1372         <sect1 id="pts-commands">The PTS email interface
1373         <p>
1374 You can control your subscription(s) to the PTS by sending
1375 various commands to <email>pts@qa.debian.org</email>. 
1376
1377 <taglist>
1378
1379 <tag><tt>subscribe &lt;sourcepackage&gt; [&lt;email&gt;]</tt>
1380 <item>
1381   Subscribes <var>email</var> to communications related to the source package
1382   <var>sourcepackage</var>. Sender address is used if the second argument is
1383   not present. If <var>sourcepackage</var> is not a valid source package,
1384   you'll get a warning. However if it's a valid binary package, the PTS
1385   will subscribe you to the corresponding source package.
1386
1387 <tag><tt>unsubscribe &lt;sourcepackage&gt; [&lt;email&gt;]</tt>
1388 <item>
1389   Removes a previous subscription to the source package <var>sourcepackage</var>
1390   using the specified email address or the sender address if the second
1391   argument is left out. 
1392
1393 <tag><tt>unsubscribeall [&lt;email&gt;]</tt>
1394 <item>
1395   Removes all subscriptions of the specified email address or the sender
1396   address if the second argument is left out. 
1397
1398 <tag><tt>which [&lt;email&gt;]</tt>
1399 <item>
1400   Lists all subscriptions for the sender or the email address optionally 
1401   specified.
1402
1403 <tag><tt>keyword [&lt;email&gt;]</tt>
1404 <item>
1405   Tells you the keywords that you are accepting.
1406   For an explanation of keywords, <qref id="pkg-tracking-system">see
1407   above</qref>. Here's a quick summary:
1408   <list>
1409   <item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
1410   <item><tt>bts-control</tt>: reply to mails sent to &email-bts-control;
1411   <item><tt>summary</tt>: automatic summary mails about the state of a package
1412   <item><tt>cvs</tt>: notification of CVS commits
1413   <item><tt>ddtp</tt>: translations of descriptions and debconf templates
1414   <item><tt>derivatives</tt>: changes made on the package by derivative distributions
1415   <item><tt>upload-source</tt>: announce of a new source upload that
1416         has been accepted
1417   <item><tt>upload-binary</tt>: announce of a new binary-only upload (porting)
1418   <item><tt>katie-other</tt>: other mails from ftpmasters
1419         (override disparity, etc.)
1420   <item><tt>default</tt>: all the other mails (those which aren't "automatic")
1421   </list>
1422
1423 <tag><tt>keyword &lt;sourcepackage&gt; [&lt;email&gt;]</tt>
1424 <item>
1425   Same as the previous item but for the given source package, since
1426   you may select a different set of keywords for each source package.
1427
1428 <tag><tt>keyword [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</tt>
1429 <item>
1430   Accept (+) or refuse (-) mails classified under the given keyword(s).
1431   Define the list (=) of accepted keywords. This changes the default set
1432   of keywords accepted by a user.
1433
1434 <tag><tt>keywordall [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</tt>
1435 <item>
1436   Accept (+) or refuse (-) mails classified under the given keyword(s).
1437   Define the list (=) of accepted keywords. This changes the set of
1438   accepted keywords of all the currently active subscriptions of a user.
1439
1440 <tag><tt>keyword &lt;sourcepackage&gt; [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</tt>
1441 <item>
1442   Same as previous item but overrides the keywords list for the
1443   indicated source package.
1444   
1445 <tag><tt>quit | thanks | --</tt>
1446 <item>
1447   Stops processing commands. All following lines are ignored by
1448   the bot.
1449 </taglist>
1450
1451         <p>
1452 The <prgn>pts-subscribe</prgn> command-line utility (from the
1453 <package>devscripts</package> package) can be handy to temporarily
1454 subscribe to some packages, for example after having made an
1455 non-maintainer upload.
1456
1457         <sect1 id="pts-mail-filtering">Filtering PTS mails
1458         <p>
1459 Once you are subscribed to a package, you will get the mails sent to
1460 <tt><var>sourcepackage</var>@packages.qa.debian.org</tt>. Those mails
1461 have special headers appended to let you filter them in a special
1462 mailbox (e.g. with <prgn>procmail</prgn>). The added headers are
1463 <tt>X-Loop</tt>, <tt>X-PTS-Package</tt>, <tt>X-PTS-Keyword</tt> and
1464 <tt>X-Unsubscribe</tt>.
1465         <p>
1466 Here is an example of added headers for a source upload notification
1467 on the <package>dpkg</package> package:
1468 <example>
1469 X-Loop: dpkg@&pts-host;
1470 X-PTS-Package: dpkg
1471 X-PTS-Keyword: upload-source
1472 X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org
1473 </example>
1474
1475         <sect1 id="pts-cvs-commit">Forwarding CVS commits in the PTS
1476         <p>
1477 If you use a publicly accessible CVS repository for maintaining
1478 your Debian package, you may want to forward the commit notification
1479 to the PTS so that the subscribers (and possible co-maintainers) can
1480 closely follow the package's evolution.
1481         <p>
1482 Once you set up the CVS repository to generate commit notifications,
1483 you just have to make sure it sends a copy of those mails
1484 to <tt><var>sourcepackage</var>_cvs@&pts-host;</tt>. Only the people
1485 who accept the <em>cvs</em> keyword will receive these notifications.
1486
1487         <sect1 id="pts-web">The PTS web interface
1488         <p>
1489 The PTS has a web interface at <url id="http://&pts-host;/"> that puts
1490 together a lot of information about each source package. It features many useful
1491 links (BTS, QA stats, contact information, DDTP translation status,
1492 buildd logs) and gathers much more information from various places
1493 (30 latest changelog entries, testing status, ...). It's a very useful
1494 tool if you want to know what's going on with a specific source
1495 package. Furthermore there's a form that allows easy subscription to
1496 the PTS via email.
1497         <p>
1498 You can jump directly to the web page concerning a specific source package
1499 with a URL like <tt>http://&pts-host;/<var>sourcepackage</var></tt>.
1500         <p>
1501 This web interface has been designed like a portal for the development of
1502 packages: you can add custom content on your packages' pages. You can
1503 add "static information" (news items that are meant to stay available
1504 indefinitely) and news items in the "latest news" section.
1505         <p>
1506 Static news items can be used to indicate:
1507 <list>
1508 <item>the availability of a project hosted on <qref id="alioth">Alioth</qref> for co-maintaining the package
1509 <item>a link to the upstream web site
1510 <item>a link to the upstream bug tracker
1511 <item>the existence of an IRC channel dedicated to the software
1512 <item>any other available resource that could be useful in the maintenance of the package
1513 </list>
1514 Usual news items may be used to announce that:
1515 <list>
1516 <item>beta packages are available for testing
1517 <item>final packages are expected for next week
1518 <item>the packaging is about to be redone from scratch
1519 <item>backports are available
1520 <item>the maintainer is on vacation (if they wish to publish this information)
1521 <item>a NMU is being worked on
1522 <item>something important will affect the package
1523 </list>
1524         <p>
1525 Both kinds of news are generated in a similar manner: you just have to send
1526 an email either to <email>pts-static-news@qa.debian.org</email> or to
1527 <email>pts-news@qa.debian.org</email>. The mail should indicate which
1528 package is concerned by having the name of the source package in a
1529 <tt>X-PTS-Package</tt> mail header or in a <tt>Package</tt> pseudo-header (like the
1530 BTS reports). If a URL is available in the <tt>X-PTS-Url</tt> mail header or in
1531 the <tt>Url</tt> pseudo-header, then the result is a link to that URL instead
1532 of a complete news item.
1533         <p>
1534 Here are a few examples of valid mails used to generate news items in
1535 the PTS. The first one adds a link to the cvsweb interface of debian-cd
1536 in the "Static information" section:
1537 <example>
1538 From: Raphael Hertzog &lt;hertzog@debian.org&gt;
1539 To: pts-static-news@qa.debian.org
1540 Subject: Browse debian-cd CVS repository with cvsweb
1541
1542 Package: debian-cd
1543 Url: http://cvs.debian.org/debian-cd/
1544 </example>
1545         <p>
1546 The second one is an announcement sent to a mailing list which is also sent
1547 to the PTS so that it is published on the PTS web page of the package. Note the
1548 use of the BCC field to avoid answers sent to the PTS by mistake.
1549 <example>
1550 From: Raphael Hertzog &lt;hertzog@debian.org&gt;
1551 To: debian-gtk-gnome@lists.debian.org
1552 Bcc: pts-news@qa.debian.org
1553 Subject: Galeon 2.0 backported for woody
1554 X-PTS-Package: galeon
1555
1556 Hello gnomers!
1557
1558 I'm glad to announce that galeon has been backported for woody. You'll find
1559 everything here:
1560 ...
1561 </example>
1562         <p>
1563 Think twice before adding a news item to the PTS because you won't be able
1564 to remove it later and you won't be able to edit it either. The only thing
1565 that you can do is send a second news item that will deprecate the
1566 information contained in the previous one.
1567
1568     <sect id="ddpo">Developer's packages overview
1569         <p>
1570 A QA (quality assurance) web portal is available at <url
1571             id="&url-ddpo;"> which displays a table listing all the packages
1572 of a single developer (including those where the party is listed as
1573 a co-maintainer). The table gives a good summary about the developer's 
1574 packages: number of bugs by severity, list of available versions in each
1575 distribution, testing status and much more including links to any other
1576 useful information.
1577         <p>
1578 It is a good idea to look up your own data regularly so that
1579 you don't forget any open bugs, and so that you don't forget which
1580 packages are your responsibility.
1581
1582     <sect id="alioth">Debian *Forge: Alioth
1583         <p>
1584 Alioth is a fairly new Debian service, based on a slightly modified version
1585 of the GForge software (which evolved from SourceForge). This software
1586 offers developers access to easy-to-use tools such as bug trackers, patch
1587 manager, project/task managers, file hosting services, mailing lists, CVS
1588 repositories etc. All these tools are managed via a web interface.
1589         <p>
1590 It is intended to provide facilities to free software projects backed or led
1591 by Debian, facilitate contributions from external developers to projects
1592 started by Debian, and help projects whose goals are the promotion of Debian
1593 or its derivatives.
1594         <p>
1595 All Debian developers automatically have an account on Alioth.
1596 They can activate it by using the recover password facility.
1597 External developers can request guest accounts on Alioth.
1598         <p>
1599 For more information please visit <url id="&url-alioth;">.
1600
1601     <sect id="developer-misc">Goodies for Developers
1602         <p>
1603      <sect1 id="lwn">LWN Subscriptions
1604         <p>
1605 Since October of 2002, HP has sponsored a subscription to LWN for all 
1606 interested Debian developers.
1607
1608 Details on how to get access to this benefit are in
1609 <url id="http://lists.debian.org/debian-devel-announce/2002/10/msg00018.html">.
1610
1611
1612
1613    <chapt id="pkgs">Managing Packages
1614         <p>
1615 This chapter contains information related to creating, uploading,
1616 maintaining, and porting packages.
1617
1618
1619     <sect id="newpackage">New packages
1620         <p>
1621 If you want to create a new package for the Debian distribution, you
1622 should first check the <url id="&url-wnpp;" name="Work-Needing and
1623 Prospective Packages (WNPP)"> list. Checking the WNPP list ensures that
1624 no one is already working on packaging that software, and that effort is
1625 not duplicated. Read the <url id="&url-wnpp;" name="WNPP web pages"> for
1626 more information.
1627         <p>
1628 Assuming no one else is already working on your prospective package,
1629 you must then submit a bug report (<ref id="submit-bug">) against the
1630 pseudo-package <package>wnpp</package> 
1631 describing your plan to create a new package, including, but not
1632 limiting yourself to, a description of the package, the license of the
1633 prospective package, and the current URL where it can be downloaded
1634 from.
1635         <p>
1636 You should set the subject of the bug to ``ITP: <var>foo</var>
1637 -- <var>short description</var>'', substituting the name of the new
1638 package for <var>foo</var>.  The severity of the bug report must be set
1639 to <em>wishlist</em>. If you feel it's necessary, send a copy to
1640 &email-debian-devel; by putting the address in the <tt>X-Debbugs-CC:</tt> header
1641 of the message (no, don't use <tt>CC:</tt>, because that way the message's subject
1642 won't indicate the bug number).
1643         <p>
1644 Please include a <tt>Closes: bug#<var>nnnnn</var></tt> entry in the
1645 changelog of the new package in order for the bug report to be
1646 automatically closed once the new package is installed in the archive
1647 (see <ref id="upload-bugfix">).
1648         <p>
1649 When closing security bugs include CVE numbers as well as the 
1650 "Closes: #nnnnn".
1651 This is useful for the security team to track vulnerabilities.
1652 If an upload is made to fix the bug before the advisory ID is known,
1653 it is encouraged to modify the historical changelog entry with the next upload.
1654 Even in this case, please include all available pointers to background
1655 information in the original changelog entry.
1656
1657         <p>
1658 There are a number of reasons why we ask maintainers to announce their
1659 intentions:
1660           <list compact>
1661             <item>
1662 It helps the (potentially new) maintainer to tap into the experience
1663 of people on the list, and lets them know if anyone else is working
1664 on it already.
1665             <item>
1666 It lets other people thinking about working on the package know that
1667 there already is a volunteer, so efforts may be shared.
1668             <item>
1669 It lets the rest of the maintainers know more about the package than
1670 the one line description and the usual changelog entry ``Initial release''
1671 that gets posted to <tt>debian-devel-changes</tt>.
1672             <item>
1673 It is helpful to the people who live off unstable (and form our first
1674 line of testers).  We should encourage these people.
1675             <item>
1676 The announcements give maintainers and other interested parties a
1677 better feel of what is going on, and what is new, in the project.
1678           </list>
1679         <p>
1680 Please see <url id="http://ftp-master.debian.org/REJECT-FAQ.html">
1681 for common rejection reasons for a new package.
1682
1683     <sect id="changelog-entries">Recording changes in the package
1684           <p>
1685 Changes that you make to the package need to be recorded in the
1686 <file>debian/changelog</file>.  These changes should provide a concise
1687 description of what was changed, why (if it's in doubt), and note if
1688 any bugs were closed.  They also record when the package was
1689 completed.  This file will be installed in
1690 <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>, or
1691 <file>/usr/share/doc/<var>package</var>/changelog.gz</file> for native
1692 packages.
1693           <p>
1694 The <file>debian/changelog</file> file conforms to a certain structure,
1695 with a number of different fields.  One field of note, the
1696 <em>distribution</em>, is described in <ref id="distribution">.  More
1697 information about the structure of this file can be found in
1698 the Debian Policy section titled "<file>debian/changelog</file>".
1699           <p>
1700 Changelog entries can be used to automatically close Debian bugs when
1701 the package is installed into the archive.  See <ref
1702 id="upload-bugfix">.
1703           <p>
1704 It is conventional that the changelog entry of a package that
1705 contains a new upstream version of the software looks like this:
1706 <example>
1707   * new upstream version
1708 </example>
1709           <p>
1710 There are tools to help you create entries and finalize the
1711 <file>changelog</file> for release &mdash; see <ref id="devscripts">
1712 and <ref id="dpkg-dev-el">.
1713           <p>
1714 See also <ref id="bpp-debian-changelog">.
1715
1716
1717     <sect id="sanitycheck">Testing the package
1718         <p>
1719 Before you upload your package, you should do basic testing on it.  At
1720 a minimum, you should try the following activities (you'll need to
1721 have an older version of the same Debian package around):
1722 <list>
1723               <item>
1724 Install the package and make sure the software works, or upgrade the
1725 package from an older version to your new version if a Debian package
1726 for it already exists.
1727               <item>
1728 Run <prgn>lintian</prgn> over the package.  You can run
1729 <prgn>lintian</prgn> as follows: <tt>lintian -v
1730 <var>package-version</var>.changes</tt>. This will check the source
1731 package as well as the binary package.  If you don't understand the
1732 output that <prgn>lintian</prgn> generates, try adding the <tt>-i</tt>
1733 switch, which will cause <prgn>lintian</prgn> to output a very verbose
1734 description of the problem.
1735                 <p>
1736 Normally, a package should <em>not</em> be uploaded if it causes lintian
1737 to emit errors (they will start with <tt>E</tt>).
1738                 <p>
1739 For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
1740               <item>
1741 Optionally run <ref id="debdiff"> to analyze changes from an older version,
1742 if one exists.
1743               <item>
1744 Downgrade the package to the previous version (if one exists) &mdash; this
1745 tests the <file>postrm</file> and <file>prerm</file> scripts.
1746               <item>
1747 Remove the package, then reinstall it.
1748              <item>
1749 Copy the source package in a different directory and try unpacking it and
1750 rebuilding it.  This tests if the package relies on existing files outside of
1751 it, or if it relies on permissions being preserved on the files shipped inside
1752 the .diff.gz file.
1753             </list>
1754
1755
1756     <sect id="sourcelayout">Layout of the source package
1757         <p>
1758 There are two types of Debian source packages:
1759         <list>
1760           <item>the so-called <em>native</em> packages, where there is no
1761                 distinction between the original sources and the patches
1762                 applied for Debian
1763           <item>the (more common) packages where there's an original source
1764                 tarball file accompanied by another file that contains the
1765                 patches applied for Debian
1766         </list>
1767         <p>
1768 For the native packages, the source package includes a Debian source control
1769 file (<tt>.dsc</tt>) and the source tarball (<tt>.tar.gz</tt>). A source
1770 package of a non-native package includes a Debian source control file, the
1771 original source tarball (<tt>.orig.tar.gz</tt>) and the Debian patches
1772 (<tt>.diff.gz</tt>).
1773         <p>
1774 Whether a package is native or not is determined when it is built by
1775 <manref name="dpkg-buildpackage" section="1">. The rest of this section
1776 relates only to non-native packages.
1777         <p>
1778 The first time a version is uploaded which corresponds to a particular
1779 upstream version, the original source tar file should be uploaded and
1780 included in the <file>.changes</file> file.  Subsequently, this very same
1781 tar file should be used to build the new diffs and <file>.dsc</file>
1782 files, and will not need to be re-uploaded.
1783         <p>
1784 By default, <prgn>dpkg-genchanges</prgn> and
1785 <prgn>dpkg-buildpackage</prgn> will include the original source tar
1786 file if and only if the Debian revision part of the source version
1787 number is 0 or 1, indicating a new upstream version.  This behavior
1788 may be modified by using <tt>-sa</tt> to always include it or
1789 <tt>-sd</tt> to always leave it out.
1790         <p>
1791 If no original source is included in the upload, the original
1792 source tar-file used by <prgn>dpkg-source</prgn> when constructing the
1793 <file>.dsc</file> file and diff to be uploaded <em>must</em> be
1794 byte-for-byte identical with the one already in the archive.
1795        <p>
1796 Please notice that, in non-native packages, permissions on files that are not
1797 present in the .orig.tar.gz will not be preserved, as diff does not store file
1798 permissions in the patch.
1799
1800
1801     <sect id="distribution">Picking a distribution
1802         <p>
1803 Each upload needs to specify which distribution the package is intended
1804 for. The package build process extracts this information from the first
1805 line of the <file>debian/changelog</file> file and places it in the
1806 <tt>Distribution</tt> field of the <tt>.changes</tt> file.
1807         <p>
1808 There are several possible values for this field: `stable', `unstable',
1809 `testing-proposed-updates' and `experimental'. Normally, packages are
1810 uploaded into <em>unstable</em>.
1811         <p>
1812 Actually, there are two other possible distributions: `stable-security' and
1813 `testing-security', but read <ref id="bug-security"> for more information on
1814 those.
1815         <p>
1816 It is not possible to upload a package into several distributions
1817 at the same time.
1818
1819         <sect1 id="upload-stable">
1820           <heading>Special case: uploads to the <em>stable</em> distribution</heading>
1821           <p>
1822 Uploading to <em>stable</em> means that the package will transfered to the
1823 <em>p-u-new</em>-queue for review by the stable release managers, and
1824 if approved will be installed in
1825 <file>stable-proposed-updates</file> directory of the Debian archive.
1826 From there, it will be included in <em>stable</em> with the next point release.
1827           <p>
1828 Extra care should be taken when uploading to <em>stable</em>. Basically, a
1829 package should only be uploaded to stable if one of the following happens:
1830 <list>
1831         <item>a truly critical functionality problem
1832         <item>the package becomes uninstallable
1833         <item>a released architecture lacks the package
1834 </list>
1835 <p>
1836 In the past, uploads to <em>stable</em> were used to address security
1837 problems as well.  However, this practice is deprecated, as uploads
1838 used for Debian security advisories are automatically copied to the
1839 appropriate <file>proposed-updates</file> archive when the advisory is
1840 released.  See <ref id="bug-security"> for detailed information on
1841 handling security problems.
1842           <p>
1843 Changing anything else in the package that isn't important is discouraged,
1844 because even trivial fixes can cause bugs later on.
1845           <p>
1846 Packages uploaded to <em>stable</em> need to be compiled on systems running
1847 <em>stable</em>, so that their dependencies are limited to the libraries
1848 (and other packages) available in <em>stable</em>; for example, a package
1849 uploaded to <em>stable</em> that depends on a library package that only
1850 exists in unstable will be rejected. Making changes to dependencies of other
1851 packages (by messing with <tt>Provides</tt> or shlibs files), possibly making
1852 those other packages uninstallable, is strongly discouraged.
1853           <p>
1854 The Release Team (which can be reached at &email-debian-release;) will
1855 regularly evaluate the uploads To <em>stable-proposed-updates</em> and decide if
1856 your package can be included in <em>stable</em>. Please be clear (and
1857 verbose, if necessary) in your changelog entries for uploads to
1858 <em>stable</em>, because otherwise the package won't be considered for
1859 inclusion.
1860           <p>
1861 It's best practice to speak with the stable release manager <em>before</em>
1862 uploading to <em>stable</em>/<em>stable-proposed-updates</em>, so that the
1863 uploaded package fits the needs of the next point release.
1864
1865         <sect1 id="upload-t-p-u">
1866           <heading>Special case: uploads to <em>testing/testing-proposed-updates</em></heading>
1867           <p>
1868 Please see the information in the <qref id="t-p-u">testing section</qref> for details.
1869
1870
1871     <sect id="upload">Uploading a package
1872
1873         <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
1874           <p>
1875 To upload a package, you should upload the files (including the signed
1876 changes and dsc-file) with anonymous ftp to
1877 <ftpsite>&ftp-master-host;</ftpsite> in the directory &upload-queue;.
1878 To get the files processed there, they need to be signed with a key in the
1879 debian keyring.
1880           <p>
1881 Please note that you should transfer
1882 the changes file last.  Otherwise, your upload may be rejected because the
1883 archive maintenance software will parse the changes file and see that not
1884 all files have been uploaded.
1885           <p>
1886 You may also find the Debian packages <ref id="dupload"> or
1887 <ref id="dput"> useful
1888 when uploading packages. These handy programs help automate the
1889 process of uploading packages into Debian.
1890           <p>
1891 For removing packages, please see the README file in that ftp directory,
1892 and the Debian package <ref id="dcut">.
1893
1894         <sect1 id="delayed-incoming">Delayed uploads
1895           <p>
1896 Delayed uploads are done for the moment via the delayed queue at
1897 gluck. The upload-directory is
1898 <ftpsite>gluck:~tfheen/DELAYED/[012345678]-day</ftpsite>.
1899 0-day is uploaded multiple times per day to ftp-master.
1900           <p>
1901 With a fairly recent dput, this section
1902 <example>
1903 [tfheen_delayed]
1904 method = scp
1905 fqdn = gluck.debian.org
1906 incoming = ~tfheen
1907 </example>
1908 in ~/.dput.cf should work fine for uploading to the DELAYED queue.
1909           <p>
1910 <em>Note:</em>
1911 Since this upload queue goes to <tt>ftp-master</tt>, the
1912 prescription found in <ref id="upload-ftp-master"> applies here as well.
1913
1914         <sect1>Security uploads
1915           <p>
1916 Do <strong>NOT</strong> upload a package to the security upload queue
1917 (oldstable-security,
1918 stable-security, etc.) without prior authorization from the security
1919 team. If the package does not exactly meet the team's requirements, it
1920 will cause many problems and delays in dealing with the unwanted upload.
1921 For details, please see section <ref id="bug-security">.
1922
1923         <sect1>Other upload queues
1924           <p>
1925 The scp queues on ftp-master, and security are mostly unusable
1926 due to the login restrictions on those hosts.
1927           <p>
1928 The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are
1929 currently down. Work is underway to resurrect them. 
1930           <p>
1931 The queues on master.debian.org, samosa.debian.org, master.debian.or.jp,
1932 and ftp.chiark.greenend.org.uk are down permanently, and will not be
1933 resurrected. The queue in Japan will be replaced with a new queue on
1934 hp.debian.or.jp some day.
1935           <p>
1936 For the time being, the anonymous ftp queue on auric.debian.org (the
1937 former ftp-master) works, but it is deprecated and will be removed at
1938 some point in the future.
1939
1940       <sect1 id="upload-notification">
1941         <heading>Notification that a new package has been installed</heading>
1942         <p>
1943 The Debian archive maintainers are responsible for handling package
1944 uploads.  For the most part, uploads are automatically handled on a
1945 daily basis by the archive maintenance tools, <prgn>katie</prgn>.
1946 Specifically, updates to existing packages to
1947 the `unstable' distribution are handled automatically. In other cases,
1948 notably new packages, placing the uploaded package into the
1949 distribution is handled manually. When uploads are handled manually,
1950 the change to the archive may take up to a month to occur. Please be
1951 patient.
1952         <p>
1953 In any case, you will receive an email notification indicating that the
1954 package has been added to the archive, which also indicates which bugs will
1955 be closed by the upload.  Please examine this notification carefully,
1956 checking if any bugs you meant to close didn't get triggered.
1957         <p>
1958 The installation notification also includes information on what
1959 section the package was inserted into.  If there is a disparity, you
1960 will receive a separate email notifying you of that.  Read on below.
1961         <p>
1962 Note that if you upload via queues, the queue daemon software will
1963 also send you a notification by email.
1964
1965     <sect id="override-file">Specifying the package section, subsection and priority
1966         <p>
1967 The <file>debian/control</file> file's <tt>Section</tt> and
1968 <tt>Priority</tt> fields do not actually specify where the file will
1969 be placed in the archive, nor its priority.  In order to retain the
1970 overall integrity of the archive, it is the archive maintainers who
1971 have control over these fields.  The values in the
1972 <file>debian/control</file> file are actually just hints.
1973         <p>
1974 The archive maintainers keep track of the canonical sections and
1975 priorities for packages in the <em>override file</em>.  If there is a
1976 disparity between the <em>override file</em> and the package's fields
1977 as indicated in <file>debian/control</file>, then you will receive an
1978 email noting the divergence when the package is installed into the
1979 archive.  You can either correct your <file>debian/control</file> file
1980 for your next upload, or else you may wish to make a change in the
1981 <em>override file</em>.
1982         <p>
1983 To alter the actual section that a package is put in, you need to
1984 first make sure that the <file>debian/control</file> file in your package
1985 is accurate.  Next, send an email &email-override; or submit a bug
1986 against <package>ftp.debian.org</package> requesting that the section
1987 or priority for your package be changed from the old section or
1988 priority to the new one.  Be sure to explain your reasoning.
1989         <p>
1990 For more information about <em>override files</em>, see <manref
1991 name="dpkg-scanpackages" section="1"> and
1992 <url id="&url-bts-devel;#maintincorrect">.
1993         <p>
1994 Note that the <tt>Section</tt> field describes both the section as
1995 well as the subsection, which are described in <ref
1996 id="archive-sections">.  If the section is "main", it should be
1997 omitted.  The list of allowable subsections can be found in <url
1998 id="&url-debian-policy;ch-archive.html#s-subsections">.
1999
2000
2001     <sect id="bug-handling">Handling bugs
2002         <p>
2003 Every developer has to be able to work with the Debian <url name="bug
2004 tracking system" id="&url-bts;">. This includes knowing how to file bug
2005 reports properly (see <ref id="submit-bug">), how to update them and
2006 reorder them, and how to process and close them.
2007         <p>
2008 The bug tracking system's features are described
2009 in the <url id="&url-bts-devel;" name="BTS documentation for developers">.
2010 This includes closing bugs, sending followup messages, assigning severities
2011 and tags, marking bugs as forwarded, and other issues.
2012         <p>
2013 Operations such as reassigning bugs to other packages, merging separate
2014 bug reports about the same issue, or reopening bugs when they are
2015 prematurely closed, are handled using the so-called control mail server.
2016 All of the commands available on this server are described in the
2017 <url id="&url-bts-control;" name="BTS control server documentation">.
2018
2019       <sect1 id="bug-monitoring">Monitoring bugs
2020         <p>
2021 If you want to be a good maintainer, you should periodically check the
2022 <url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
2023 packages.  The BTS contains all the open bugs against your packages.
2024 You can check them by browsing this page:
2025 <tt>http://&bugs-host;/<var>yourlogin</var>@debian.org</tt>.
2026         <p>
2027 Maintainers interact with the BTS via email addresses at
2028 <tt>&bugs-host;</tt>.  Documentation on available commands can be
2029 found at <url id="&url-bts;">, or, if you have installed the
2030 <package>doc-debian</package> package, you can look at the local files
2031 &file-bts-docs;.
2032         <p>
2033 Some find it useful to get periodic reports on open bugs.  You can add
2034 a cron job such as the following if you want to get a weekly email
2035 outlining all the open bugs against your packages:
2036 <example>
2037 # ask for weekly reports of bugs in my packages
2038 &cron-bug-report;
2039 </example>
2040 Replace <var>address</var> with your official Debian
2041 maintainer address.
2042
2043       <sect1 id="bug-answering">Responding to bugs
2044         <p>
2045 When responding to bugs, make sure that any discussion you have about
2046 bugs is sent both to the original submitter of the bug, and to the bug
2047 itself (e.g., <email>123@&bugs-host;</email>). If you're writing a new
2048 mail and you don't remember the submitter email address, you can
2049 use the <email>123-submitter@&bugs-host;</email> email to
2050 contact the submitter <em>and</em> to record your mail within the
2051 bug log (that means you don't need to send a copy of the mail to
2052 <email>123@&bugs-host;</email>).
2053         <p>
2054 If you get a bug which mentions "FTBFS", this means "Fails to build
2055 from source".  Porters frequently use this acronym.
2056         <p>
2057 Once you've dealt with a bug report (e.g. fixed it), mark it as
2058 <em>done</em> (close it) by sending an explanation message to
2059 <email>123-done@&bugs-host;</email>. If you're fixing a bug by
2060 changing and uploading the package, you can automate bug closing as
2061 described in <ref id="upload-bugfix">.
2062         <p>
2063 You should <em>never</em> close bugs via the bug server <tt>close</tt>
2064 command sent to &email-bts-control;.  If you do so, the original
2065 submitter will not receive any information about why the bug was
2066 closed.
2067
2068       <sect1 id="bug-housekeeping">Bug housekeeping
2069         <p>
2070 As a package maintainer, you will often find bugs in other packages or
2071 have bugs reported against your packages which are actually bugs in
2072 other packages. The bug tracking system's features
2073 are described in the <url id="&url-bts-devel;" name="BTS documentation for
2074 Debian developers">. Operations such as reassigning, merging, and tagging
2075 bug reports are described in the <url id="&url-bts-control;" name="BTS
2076 control server documentation">. This section contains
2077 some guidelines for managing your own bugs, based on the collective
2078 Debian developer experience.
2079         <p>
2080 Filing bugs for problems that you find in other packages is one of
2081 the "civic obligations" of maintainership, see <ref id="submit-bug">
2082 for details. However, handling the bugs in your own packages is
2083 even more important.
2084         <p>
2085 Here's a list of steps that you may follow to handle a bug report:
2086 <enumlist>
2087     <item>
2088 Decide whether the report corresponds to a real bug or not. Sometimes
2089 users are just calling a program in the wrong way because they haven't
2090 read the documentation. If you diagnose this, just close the bug with
2091 enough information to let the user correct their problem (give pointers
2092 to the good documentation and so on). If the same report comes up
2093 again and again you may ask yourself if the documentation is good
2094 enough or if the program shouldn't detect its misuse in order to
2095 give an informative error message. This is an issue that may need
2096 to be brought up with the upstream author.
2097     <p>
2098 If the bug submitter disagrees with your decision to close the bug,
2099 they may reopen it until you find an agreement on how to handle it.
2100 If you don't find any, you may want to tag the bug <tt>wontfix</tt>
2101 to let people know that the bug exists but that it won't be corrected.
2102 If this situation is unacceptable, you (or the submitter) may want to
2103 require a decision of the technical committee by reassigning the bug
2104 to <package>tech-ctte</package> (you may use the clone command of
2105 the BTS if you wish to keep it reported against your package). Before
2106 doing so, please read the <url id="&url-tech-ctte;" name="recommended procedure">.
2107     <item>
2108 If the bug is real but it's caused by another package, just reassign
2109 the bug to the right package. If you don't know which package it should
2110 be reassigned to, you should ask for help on
2111 <qref id="irc-channels">IRC</qref> or on &email-debian-devel;.
2112 Please make sure that the maintainer(s) of the package
2113 the bug is reassigned to
2114 know why you reassigned it.
2115     <p>
2116 Sometimes you also have to adjust the severity of the bug so that it
2117 matches our definition of the severity. That's because people tend to
2118 inflate the severity of bugs to make sure their bugs are fixed quickly.
2119 Some bugs may even be dropped to wishlist severity when the requested
2120 change is just cosmetic.
2121     <item>
2122 If the bug is real but the same problem has already been reported by
2123 someone else, then the two relevant bug reports should be merged
2124 into one using the merge command of the BTS.
2125 In this way, when the
2126 bug is fixed, all of the submitters will be informed of this.
2127 (Note, however, that emails sent to one bug report's submitter won't
2128 automatically be sent to the other report's submitter.)
2129 For more
2130 details on the technicalities of the merge command and its relative,
2131 the unmerge command, see the BTS control server documentation.
2132     <item>
2133 The bug submitter may have forgotten to provide some information, in which
2134 case you have to ask them for the required information. You may use the
2135 <tt>moreinfo</tt> tag to mark the bug as such. Moreover if you can't
2136 reproduce the bug, you tag it <tt>unreproducible</tt>. Anyone who
2137 can reproduce the bug is then invited to provide more information
2138 on how to reproduce it. After a few months, if this information has not
2139 been sent by someone, the bug may be closed.
2140     <item>
2141 If the bug is related to the packaging, you just fix it. If you are not
2142 able to fix it yourself, then tag the bug as <tt>help</tt>. You can
2143 also ask for help on &email-debian-devel; or &email-debian-qa;. If it's an
2144 upstream problem, you have to forward it to the upstream author.
2145 Forwarding a bug is not enough, you have to check at each release if
2146 the bug has been fixed or not. If it has, you just close it, otherwise
2147 you have to remind the author about it. If you have the required skills
2148 you can prepare a patch that fixes the bug and
2149 send it to the author at the same time.
2150 Make sure to send the patch to the BTS and to
2151 tag the bug as <tt>patch</tt>.
2152     <item>
2153 If you have fixed a bug in your local copy, or if a fix has been
2154 committed to the CVS repository, you may tag the bug as
2155 <tt>pending</tt> to let people know that the bug is corrected and that
2156 it will be closed with the next upload (add the <tt>closes:</tt> in
2157 the <file>changelog</file>). This is particularly useful if you
2158 are several developers working on the same package.
2159     <item>
2160 Once a corrected package is available in the <em>unstable</em>
2161 distribution, you can close the bug. This can be done automatically,
2162 read <ref id="upload-bugfix">.
2163 </enumlist>
2164
2165       <sect1 id="upload-bugfix">When bugs are closed by new uploads
2166         <p>
2167 As bugs and problems are fixed in your packages, it is your
2168 responsibility as the package maintainer to close these bugs.  However,
2169 you should not close a bug until the package which fixes the bug has
2170 been accepted into the Debian archive.  Therefore, once you get
2171 notification that your updated package has been installed into the
2172 archive, you can and should close the bug in the BTS.
2173 Also, the bug should be closed with the correct version.
2174         <p>
2175 However, it's possible to avoid having to manually close bugs after the
2176 upload &mdash; just list the fixed bugs in your <file>debian/changelog</file>
2177 file, following a certain syntax, and the archive maintenance software
2178 will close the bugs for you. For example:
2179
2180 <example>
2181 acme-cannon (3.1415) unstable; urgency=low
2182
2183   * Frobbed with options (closes: Bug#98339)
2184   * Added safety to prevent operator dismemberment, closes: bug#98765,
2185     bug#98713, #98714.
2186   * Added man page. Closes: #98725.
2187 </example>
2188
2189 Technically speaking, the following Perl regular expression describes
2190 how bug closing changelogs are identified:
2191 <example>
2192   /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
2193 </example>
2194
2195 We prefer the <tt>closes: #<var>XXX</var></tt> syntax, as it is the
2196 most concise entry and the easiest to integrate with the text of the
2197 <file>changelog</file>.
2198 Unless specified different by the <var>-v</var>-switch to
2199 <prgn>dpkg-buildpackage</prgn>, only the bugs closed in the
2200 most recent changelog entry are closed (basically, exactly
2201 the bugs mentioned in the changelog-part
2202 in the <file>.changes</file> file are closed).
2203         <p>
2204 Historically, uploads identified as
2205 <qref id="nmu">Non-maintainer upload (NMU)</qref>
2206 were tagged <tt>fixed</tt> instead of being closed,
2207 but that practice was ceased with the advent of version-tracking.
2208 The same applied to the tag <tt>fixed-in-experimental</tt>.
2209         <p>
2210 If you happen to mistype a bug number or forget a bug in the changelog
2211 entries, don't hesitate to undo any damage the error caused. To reopen
2212 wrongly closed bugs, send a <tt>reopen <var>XXX</var></tt> command to
2213 the bug tracking system's control address, &email-bts-control;.  To
2214 close any remaining bugs that were fixed by your upload, email the
2215 <file>.changes</file> file to <email>XXX-done@&bugs-host;</email>,
2216 where <var>XXX</var> is the bug number, and
2217 put "Version: YYY" and an empty line as the first two lines
2218 of the body of the email,
2219 where <var>YYY</var> is the first version
2220 where the bug has been fixed.
2221
2222         <p>
2223 Bear in mind that it is not obligatory to close bugs using the
2224 changelog as described above.  If you simply want to close bugs that
2225 don't have anything to do with an upload you made, do it by emailing
2226 an explanation to <email>XXX-done@&bugs-host;</email>.  Do
2227 <strong>not</strong> close bugs in the changelog entry of a version if
2228 the changes in that version of the package don't have any bearing on
2229 the bug.
2230           <p>
2231 For general information on how to write your changelog entries, see
2232 <ref id="bpp-debian-changelog">.
2233
2234
2235       <sect1 id="bug-security">Handling security-related bugs
2236         <p>
2237 Due to their sensitive nature, security-related bugs must be handled
2238 carefully.  The Debian Security Team exists to coordinate this
2239 activity, keeping track of outstanding security problems, helping
2240 maintainers with security problems or fixing them themselves, sending
2241 security advisories, and maintaining security.debian.org.
2242
2243 <!-- information about the security database goes here once it's ready -->
2244 <!-- (mdz) -->
2245
2246 <p>
2247 When you become aware of a security-related bug in a Debian package,
2248 whether or not you are the maintainer, collect pertinent information
2249 about the problem, and promptly contact the security team at
2250 &email-security-team; as soon as possible.  <strong>DO NOT UPLOAD</strong> any
2251 packages for stable; the security team will do that.
2252
2253 Useful information includes, for example:
2254
2255 <list compact>
2256   <item>Which versions of the package are known to be affected by the
2257   bug.  Check each version that is present in a supported Debian
2258   release, as well as testing and unstable.
2259
2260   <item>The nature of the fix, if any is available (patches are
2261   especially helpful)
2262
2263   <item>Any fixed packages that you have prepared yourself (send only
2264   the <tt>.diff.gz</tt> and <tt>.dsc</tt> files and read <ref
2265   id="bug-security-building"> first)
2266
2267   <item>Any assistance you can provide to help with testing (exploits,
2268   regression testing, etc.)
2269
2270   <item>Any information needed for the advisory (see <ref
2271   id="bug-security-advisories">)
2272
2273 </list>
2274
2275         <sect2 id="bug-security-confidentiality">Confidentiality
2276           <p>
2277 Unlike most other activities within Debian, information about security
2278 issues must sometimes be kept private for a time.
2279 This allows software distributors to coordinate their disclosure in
2280 order to minimize their users' exposure.  Whether this is the
2281 case depends on the nature of the problem and corresponding fix, and
2282 whether it is already a matter of public knowledge.
2283
2284 <p>
2285 There are several ways developers can learn of a security problem:
2286
2287 <list compact>
2288     <item>they notice it on a public forum (mailing list, web site, etc.)
2289     <item>someone files a bug report
2290     <item>someone informs them via private email
2291 </list>
2292
2293  In the first two cases, the information is public and it is important
2294  to have a fix as soon as possible. In the last case, however, it
2295  might not be public information. In that case there are a few
2296  possible options for dealing with the problem:
2297
2298 <list>
2299   <item>If the security exposure is minor, there is sometimes no need
2300   to keep the problem a secret and a fix should be made and released.
2301
2302   <item>If the problem is severe, it is preferable to share the
2303   information with
2304   other vendors and coordinate a release. The security team keeps
2305   in contact with the various organizations and individuals and can take
2306   care of that.
2307 </list>
2308
2309 <p>
2310  In all cases if the person who reports the problem asks that it not
2311  be disclosed, such requests should be honored, with the obvious
2312  exception of informing the security team in order that a fix may be
2313  produced for a stable release of Debian.  When sending confidential
2314  information to the security team, be sure to mention this fact.
2315
2316 <p>
2317 Please note that if secrecy is needed you may not upload a fix to
2318 unstable (or anywhere else, such as a public CVS repository).  It is
2319 not sufficient to obfuscate the details of the change, as the code
2320 itself is public, and can (and will) be examined by the general public.
2321
2322 <p>
2323 There are two reasons for releasing information even though secrecy is
2324 requested: the problem has been known for a while, or the problem
2325 or exploit has become public.
2326
2327         <sect2 id="bug-security-advisories">Security Advisories
2328           <p>
2329 Security advisories are only issued for the current, released stable
2330 distribution, and <em>not</em> for testing or unstable.  When released,
2331 advisories
2332 are sent to the &email-debian-security-announce;
2333
2334 mailing list and posted on <url
2335 id="&url-debian-security-advisories;" name="the security web page">.
2336 Security advisories are written and posted by the security
2337 team. However they certainly do not mind if a
2338 maintainer can supply some of the information for them, or write part
2339 of the text. Information that should be in an advisory includes:
2340
2341 <list compact>
2342   <item>A description of the problem and its scope, including:
2343     <list>
2344        <item>The type of problem (privilege escalation, denial of
2345   service, etc.)
2346        <item>What privileges may be gained, and by whom (if any)
2347        <item>How it can be exploited
2348        <item>Whether it is remotely or locally exploitable
2349        <item>How the problem was fixed
2350     </list>
2351
2352   This information allows users to assess the threat to their systems.
2353
2354   <item>Version numbers of affected packages
2355   <item>Version numbers of fixed packages
2356   <item>Information on where to obtain the updated packages
2357   (usually from the Debian security archive)
2358   <item>References to upstream advisories, <url
2359   id="http://cve.mitre.org" name="CVE"> identifiers, and any other
2360   information useful in cross-referencing the vulnerability
2361 </list>
2362
2363          <sect2 id="bug-security-building">
2364             <heading>Preparing packages to address security issues</heading>
2365          <p>
2366 One way that you can assist the security team in their duties is to
2367 provide them with fixed packages suitable for a security advisory for
2368 the stable
2369 Debian release.
2370          <p>
2371  When an update is made to the stable release, care must be taken to
2372  avoid changing system behavior or introducing new bugs.  In order to
2373  do this, make as few changes as possible to fix the bug.  Users and
2374  administrators rely on the exact behavior of a release once it is
2375  made, so any change that is made might break someone's system.  This
2376  is especially true of libraries: make sure you never change the API or
2377  ABI, no matter how small the change.
2378 <p>
2379 This means that moving to a new upstream version is not a good
2380 solution.  Instead, the relevant changes should be back-ported to the
2381 version present in the current stable Debian release. Generally,
2382 upstream maintainers are willing to help if needed.  If not, the
2383 Debian security team may be able to help.
2384 <p>
2385 In some cases, it is not possible to back-port a security fix, for
2386 example when large amounts of source code need to be modified or
2387 rewritten.  If this happens, it may be necessary to move to a new
2388 upstream version.  However, this is only done in extreme situations,
2389 and you must always coordinate that with the security team beforehand.
2390 <p>
2391 Related to this is another important guideline: always test your
2392 changes.  If you have an exploit available, try it and see if it
2393 indeed succeeds on the unpatched package and fails on the fixed
2394 package.  Test other, normal actions as well, as sometimes a security
2395 fix can break seemingly unrelated features in subtle ways.
2396 <p>
2397 Do <strong>NOT</strong> include any changes in your package which are
2398 not directly related to fixing the vulnerability.  These will only
2399 need to be reverted, and this wastes time.  If there are other bugs in
2400 your package that you would like to fix, make an upload to
2401 proposed-updates in the usual way, after the security advisory is
2402 issued.  The security update mechanism is not a means for introducing
2403 changes to your package which would otherwise be rejected from the
2404 stable release, so please do not attempt to do this.
2405 <p>
2406 Review and test your changes as much as possible.  Check the
2407 differences from the previous version repeatedly
2408 (<prgn>interdiff</prgn> from the <package>patchutils</package> package
2409 and <prgn>debdiff</prgn> from <package>devscripts</package> are useful
2410 tools for this, see <ref id="debdiff">).
2411 <p>
2412 Be sure to verify the following items:
2413
2414 <list>
2415     <item>Target the right distribution in your
2416     <file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
2417     testing this is <tt>testing-security</tt>, and for the previous
2418     stable release, this is <tt>oldstable-security</tt>. Do not target
2419     <var>distribution</var>-proposed-updates or <tt>stable</tt>!
2420
2421     <item>The upload should have urgency=high.
2422
2423     <item>Make descriptive, meaningful changelog entries.  Others will
2424     rely on them to determine whether a particular bug was fixed.
2425     Always include an external reference, preferably a CVE
2426     identifier, so that it can be cross-referenced.  Include the same
2427     information in the changelog for unstable, so that it is clear that
2428     the same bug was fixed, as this is very helpful when verifying
2429     that the bug is fixed in the next stable release.  If a CVE
2430     identifier has not yet been assigned, the security team will
2431     request one so that it can be included in the package and in the advisory.
2432
2433     <item>Make sure the version number is proper. It must be greater
2434     than the current package, but less than package versions in later
2435     distributions.  If in doubt, test it with <tt>dpkg
2436     --compare-versions</tt>.  Be careful not to re-use a version
2437     number that you have already used for a previous upload.  For
2438     <em>testing</em>, there must be
2439     a higher version in <em>unstable</em>. If there is none yet (for example,
2440     if <em>testing</em> and <em>unstable</em> have the same version) you must upload a
2441     new version to unstable first.
2442
2443     <item>Do not make source-only uploads if your package has any
2444     binary-all packages (do not use the <tt>-S</tt> option to
2445     <prgn>dpkg-buildpackage</prgn>).  The <prgn>buildd</prgn> infrastructure will
2446     not build those. This point applies to normal package uploads as
2447     well.
2448
2449     <item>Unless the upstream source has been uploaded to
2450     security.debian.org before (by a previous security update), build
2451     the upload with full upstream source (<tt>dpkg-buildpackage
2452     -sa</tt>).  If there has been a previous upload to
2453     security.debian.org with the same upstream version, you may upload
2454     without upstream source (<tt>dpkg-buildpackage -sd</tt>).
2455
2456     <item>Be sure to use the exact same <file>*.orig.tar.gz</file> as used in the
2457     normal archive, otherwise it is not possible to move the security
2458     fix into the main archives later.
2459
2460     <item>Build the package on a clean
2461     system which only has packages installed from the distribution you
2462     are building for. If you do not have such a system yourself, you
2463     can use a debian.org machine (see <ref id="server-machines">)
2464     or setup a chroot (see <ref id="pbuilder"> and
2465     <ref id="debootstrap">).
2466 </list>
2467
2468       <sect2 id="bug-security-upload">Uploading the fixed package
2469 <p>
2470 Do <strong>NOT</strong> upload a package to the security upload queue
2471 (oldstable-security, stable-security, etc.) without
2472 prior authorization from the security team.  If the package does not
2473 exactly meet the team's requirements, it will cause many problems and
2474 delays in dealing with the unwanted upload.
2475 <p>
2476 Do <strong>NOT</strong> upload your fix to proposed-updates without
2477 coordinating with the security team.  Packages from
2478 security.debian.org will be copied into the proposed-updates directory
2479 automatically.  If a package with the same or a higher version number
2480 is already installed into the archive, the security update will be
2481 rejected by the archive system.  That way, the stable distribution
2482 will end up without a security update for this package instead.
2483 <p>
2484 Once you have created and tested the new package and it has been
2485 approved by the security team, it needs to be uploaded so that it can
2486 be installed in the archives. For security uploads, the place to
2487 upload to is
2488 <tt>ftp://security-master.debian.org/pub/SecurityUploadQueue/</tt> .
2489
2490 <p>
2491 Once an upload to the security queue has been accepted, the package
2492 will automatically be rebuilt for all architectures and stored for
2493 verification by the security team.
2494
2495 <p>
2496 Uploads which are waiting for acceptance or verification are only
2497 accessible by the security team. This is necessary since there might
2498 be fixes for security problems that cannot be disclosed yet.
2499
2500 <p>
2501 If a member of the security team accepts a package, it will be
2502 installed on security.debian.org as well as proposed for the proper
2503 <var>distribution</var>-proposed-updates on ftp-master.
2504
2505     <sect id="archive-manip">
2506       <heading>Moving, removing, renaming, adopting, and orphaning
2507       packages</heading>
2508       <p>
2509 Some archive manipulation operations are not automated in the Debian
2510 upload process.  These procedures should be manually followed by
2511 maintainers.  This chapter gives guidelines on what to do in these
2512 cases.
2513
2514       <sect1 id="moving-pkgs">Moving packages
2515         <p>
2516 Sometimes a package will change its section.  For instance, a
2517 package from the `non-free' section might be GPL'd in a later version,
2518 in which case the package should be moved to `main' or
2519 `contrib'.<footnote> See the <url id="&url-debian-policy;"
2520 name="Debian Policy Manual"> for guidelines on what section a package
2521 belongs in.
2522           </footnote>
2523         <p>
2524 If you need to change the section for one of your packages, change the
2525 package control information to place the package in the desired
2526 section, and re-upload the package (see the <url id="&url-debian-policy;"
2527 name="Debian Policy Manual"> for details). 
2528 You must ensure that you include the <file>.orig.tar.gz</file> in your upload
2529 (even if you are not uploading a new upstream version),
2530 or it will not appear in the new section together with the rest of the package.
2531 If your new section is
2532 valid, it will be moved automatically. If it does not, then contact
2533 the ftpmasters in order to understand what happened.
2534         <p>
2535 If, on the other hand, you need to change the <em>subsection</em> of
2536 one of your packages (e.g., ``devel'', ``admin''), the procedure is
2537 slightly different.  Correct the subsection as found in the control
2538 file of the package, and re-upload that.  Also, you'll need to get the
2539 override file updated, as described in <ref id="override-file">.
2540
2541
2542       <sect1 id="removing-pkgs">Removing packages
2543         <p>
2544 If for some reason you want to completely remove a package (say, if it
2545 is an old compatibility library which is no longer required), you
2546 need to file a bug against <tt>ftp.debian.org</tt> asking that the
2547 package be removed;
2548 as all bugs, this bug should normally have normal severity.
2549 Make sure you indicate which distribution the
2550 package should be removed from. Normally, you can only have packages
2551 removed from <em>unstable</em> and <em>experimental</em>.  Packages
2552 are not removed from <em>testing</em> directly. Rather, they will be
2553 removed automatically after the package has been removed from
2554 <em>unstable</em> and no package in <em>testing</em> depends on it.
2555         <p>
2556 There is one exception when an explicit removal request is not necessary:
2557 If a (source or binary) package is an orphan, it will be removed
2558 semi-automatically.
2559 For a binary-package, this means if there is no longer any source package
2560 producing this binary package;
2561 if the binary package is just no longer produced on some architectures,
2562 a removal request is still necessary.
2563 For a source-package, this means that all binary packages it refers to
2564 have been taken over by another source package.
2565         <p>
2566 In your removal request, you have to detail the reasons justifying the request.
2567 This is to
2568 avoid unwanted removals and to keep a trace of why a package has been
2569 removed. For example, you can provide the name of the package that
2570 supersedes the one to be removed.
2571         <p>
2572 Usually you only ask for the removal of a package maintained by yourself.
2573 If you want to remove another package, you have to get the approval
2574 of its maintainer.
2575         <p>
2576 Further information relating to these and other package removal related
2577 topics may be found at <url id="http://wiki.debian.org/ftpmaster_Removals"> and
2578 <url id="http://qa.debian.org/howto-remove.html">.
2579         <p>
2580 If in doubt concerning whether a package is disposable, email
2581 &email-debian-devel; asking for opinions.  Also of interest is the
2582 <prgn>apt-cache</prgn> program from the <package>apt</package>
2583 package.  When invoked as <tt>apt-cache showpkg
2584 <var>package</var></tt>, the program will show details for
2585 <var>package</var>, including reverse depends.
2586 Other useful programs include
2587 <tt>apt-cache rdepends</tt>,
2588 <prgn>apt-rdepends</prgn> and
2589 <prgn>grep-dctrl</prgn>.
2590 Removal of orphaned packages is discussed on &email-debian-qa;.
2591         <p>
2592 Once the package has been removed, the package's bugs should be handled.
2593 They should either be reassigned to another package in the case where
2594 the actual code has evolved into another package (e.g. <tt>libfoo12</tt>
2595 was removed because <tt>libfoo13</tt> supersedes it) or closed if the
2596 software is simply no longer part of Debian.
2597
2598         <sect2>Removing packages from <file>Incoming</file>
2599           <p>
2600 In the past, it was possible to remove packages from <file>incoming</file>.
2601 However, with the introduction of the new incoming system, this is no longer
2602 possible.  Instead, you have to upload a new revision of your package with
2603 a higher version than the package you want to replace.  Both versions will be
2604 installed in the archive but only the higher version will actually be
2605 available in <em>unstable</em> since the previous version will immediately
2606 be replaced by the higher.  However, if you do proper testing of your
2607 packages, the need to replace a package should not occur too often anyway.
2608
2609       <sect1>Replacing or renaming packages
2610         <p>
2611 When you make a mistake naming your package, you should follow a two-step
2612 process to rename it. First, set
2613 your <file>debian/control</file> file to replace and conflict with the
2614 obsolete name of the package (see the <url id="&url-debian-policy;"
2615 name="Debian Policy Manual"> for details).  Once you've uploaded
2616 the package and the package has moved into the archive, file a bug
2617 against <tt>ftp.debian.org</tt> asking to remove the package with the
2618 obsolete name. Do not forget to properly reassign the package's bugs
2619 at the same time.
2620         <p>
2621 At other times, you may make a mistake in constructing your package and
2622 wish to replace it. The only way to do this is to increase the version
2623 number and upload a new version. The old version will be expired in
2624 the usual manner.  Note that this applies to each part of your package,
2625 including the sources: if you wish to replace the upstream source tarball
2626 of your package, you will need to upload it with a different version. An
2627 easy possibility is to replace <file>foo_1.00.orig.tar.gz</file> with
2628 <file>foo_1.00+0.orig.tar.gz</file>. This restriction gives each file
2629 on the ftp site a unique name, which helps to ensure consistency across the
2630 mirror network.
2631
2632       <sect1 id="orphaning">Orphaning a package
2633         <p>
2634 If you can no longer maintain a package, you need to inform others,
2635 and see that the package is marked as orphaned.
2636 You should set the package maintainer to <tt>Debian QA Group
2637 &orphan-address;</tt> and submit a bug report
2638 against the pseudo package <package>wnpp</package>.  The bug report should be
2639 titled <tt>O: <var>package</var> -- <var>short description</var></tt>
2640 indicating that the package is now orphaned.  The severity of the bug
2641 should be set to <em>normal</em>; if the package has a priority of standard
2642 or higher, it should be set to important.
2643 If you feel it's necessary, send a copy
2644 to &email-debian-devel; by putting the address in the X-Debbugs-CC: header
2645 of the message (no, don't use CC:, because that way the message's subject
2646 won't indicate the bug number).
2647         <p>
2648 If you just intend to give the package away, but you can keep maintainership
2649 for the moment, then you should instead submit
2650 a bug against <package>wnpp</package> and title it <tt>RFA: <var>package</var> --
2651 <var>short description</var></tt>.
2652 <tt>RFA</tt> stands for <em>Request For Adoption</em>.
2653         <p>
2654 More information is on the <url id="&url-wnpp;" name="WNPP web pages">.
2655
2656       <sect1 id="adopting">Adopting a package
2657         <p>
2658 A list of packages in need of a new maintainer is available in the
2659 <url name="Work-Needing and Prospective Packages list (WNPP)"
2660 id="&url-wnpp;">. If you wish to take over maintenance of any of the
2661 packages listed in the WNPP, please take a look at the aforementioned
2662 page for information and procedures.
2663         <p>
2664 It is not OK to simply take over a package that you feel is neglected
2665 &mdash; that would be package hijacking.  You can, of course, contact the
2666 current maintainer and ask them if you may take over the package.
2667 If you have reason to believe a maintainer has gone AWOL
2668 (absent without leave), see <ref id="mia-qa">.
2669         <p>
2670 Generally, you may not take over the package without the assent of the
2671 current maintainer. Even if they ignore you, that is still not grounds to
2672 take over a package. Complaints about maintainers should be brought up on
2673 the developers' mailing list. If the discussion doesn't end with a positive
2674 conclusion, and the issue is of a technical nature, consider bringing it to
2675 the attention of the technical committee (see the <url name="technical
2676 committee web page" id="&url-tech-ctte;"> for more information).
2677         <p>
2678 If you take over an old package, you probably want to be listed as the
2679 package's official maintainer in the bug system. This will happen
2680 automatically once you upload a new version with an updated
2681 <tt>Maintainer:</tt> field, although it can take a few hours after the
2682 upload is done. If you do not expect to upload a new version for a while,
2683 you can use <ref id="pkg-tracking-system"> to get the bug reports. However,
2684 make sure that the old maintainer has no problem with the fact that
2685 they will continue to receive the bugs during that time.
2686
2687
2688     <sect id="porting">Porting and being ported
2689       <p>
2690 Debian supports an ever-increasing number of architectures.  Even if
2691 you are not a porter, and you don't use any architecture but one, it
2692 is part of your duty as a maintainer to be aware of issues of
2693 portability.  Therefore, even if you are not a porter, you should read
2694 most of this chapter.
2695       <p>
2696 Porting is the act of building Debian packages for architectures that
2697 are different from the original architecture of the package
2698 maintainer's binary package.  It is a unique and essential activity.
2699 In fact, porters do most of the actual compiling of Debian packages.
2700 For instance, for a single <em>i386</em> binary package, there must be
2701 a recompile for each architecture, which amounts to
2702 &number-of-arches; more builds.
2703
2704
2705       <sect1 id="kind-to-porters">Being kind to porters
2706         <p>
2707 Porters have a difficult and unique task, since they are required to
2708 deal with a large volume of packages.  Ideally, every source package
2709 should build right out of the box.  Unfortunately, this is often not
2710 the case.  This section contains a checklist of ``gotchas'' often
2711 committed by Debian maintainers &mdash; common problems which often stymie
2712 porters, and make their jobs unnecessarily difficult.
2713         <p>
2714 The first and most important thing is to respond quickly to bug or
2715 issues raised by porters.  Please treat porters with courtesy, as if
2716 they were in fact co-maintainers of your package (which, in a way, they
2717 are).  Please be tolerant of succinct or even unclear bug reports;
2718 do your best to hunt down whatever the problem is.
2719         <p>
2720 By far, most of the problems encountered by porters are caused by
2721 <em>packaging bugs</em> in the source packages.  Here is a checklist
2722 of things you should check or be aware of.
2723
2724 <enumlist>
2725             <item>
2726 Make sure that your <tt>Build-Depends</tt> and
2727 <tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
2728 are set properly.  The best way to validate this is to use the
2729 <package>debootstrap</package> package to create an unstable chroot
2730 environment (see <ref id="debootstrap">).
2731 Within that chrooted environment, install the
2732 <package>build-essential</package> package and any package
2733 dependencies mentioned in <tt>Build-Depends</tt> and/or
2734 <tt>Build-Depends-Indep</tt>.  Finally, try building your package
2735 within that chrooted environment.  These steps can be automated
2736 by the use of the <prgn>pbuilder</prgn> program which is provided by
2737 the package of the same name (see <ref id="pbuilder">).
2738                 <p>
2739 If you can't set up a proper chroot, <prgn>dpkg-depcheck</prgn> may be
2740 of assistance (see <ref id="dpkg-depcheck">).
2741                 <p>
2742 See the <url id="&url-debian-policy;" name="Debian Policy
2743 Manual"> for instructions on setting build dependencies.
2744             <item>
2745 Don't set architecture to a value other than ``all'' or ``any'' unless
2746 you really mean it.  In too many cases, maintainers don't follow the
2747 instructions in the <url id="&url-debian-policy;" name="Debian Policy
2748 Manual">.  Setting your architecture to ``i386'' is usually incorrect.
2749             <item>
2750 Make sure your source package is correct.  Do <tt>dpkg-source -x
2751 <var>package</var>.dsc</tt> to make sure your source package unpacks
2752 properly.  Then, in there, try building your package from scratch with
2753 <prgn>dpkg-buildpackage</prgn>.
2754             <item>
2755 Make sure you don't ship your source package with the
2756 <file>debian/files</file> or <file>debian/substvars</file> files.
2757 They should be removed by the `clean' target of
2758 <file>debian/rules</file>.
2759             <item>
2760 Make sure you don't rely on locally installed or hacked configurations
2761 or programs.  For instance, you should never be calling programs in
2762 <file>/usr/local/bin</file> or the like.  Try not to rely on programs
2763 being setup in a special way.  Try building your package on another
2764 machine, even if it's the same architecture.
2765             <item>
2766 Don't depend on the package you're building being installed already (a
2767 sub-case of the above issue).
2768             <item>
2769 Don't rely on the compiler being a certain version, if possible.  If
2770 not, then make sure your build dependencies reflect the restrictions,
2771 although you are probably asking for trouble, since different
2772 architectures sometimes standardize on different compilers.
2773             <item>
2774 Make sure your debian/rules contains separate ``binary-arch'' and
2775 ``binary-indep'' targets, as the Debian Policy Manual requires.
2776 Make sure that both targets work independently, that is, that you can
2777 call the target without having called the other before. To test this,
2778 try to run <tt>dpkg-buildpackage -B</tt>.
2779           </enumlist>
2780
2781
2782       <sect1 id="porter-guidelines">Guidelines for porter uploads
2783         <p>
2784 If the package builds out of the box for the architecture to be ported
2785 to, you are in luck and your job is easy.  This section applies to
2786 that case; it describes how to build and upload your binary package so
2787 that it is properly installed into the archive.  If you do have to
2788 patch the package in order to get it to compile for the other
2789 architecture, you are actually doing a source NMU, so consult <ref
2790 id="nmu-guidelines"> instead.
2791         <p>
2792 For a porter upload, no changes are being made to the source.  You do
2793 not need to touch any of the files in the source package.  This
2794 includes <file>debian/changelog</file>.
2795         <p>
2796 The way to invoke <prgn>dpkg-buildpackage</prgn> is as
2797 <tt>dpkg-buildpackage -B -m<var>porter-email</var></tt>.  Of course,
2798 set <var>porter-email</var> to your email address.  This will do a
2799 binary-only build of only the architecture-dependent portions of the
2800 package, using the `binary-arch' target in <file>debian/rules</file>.
2801         <p>
2802 If you are working on a Debian machine for your porting efforts and you
2803 need to sign your upload locally for its acceptance in the archive, you
2804 can run <prgn>debsign</prgn> on your <file>.changes</file> file to have
2805 it signed conveniently, or use the remote signing mode of <prgn>dpkg-sig</prgn>.
2806
2807
2808         <sect2 id="binary-only-nmu">
2809           <heading>Recompilation or binary-only NMU</heading>
2810         <p>
2811 Sometimes the initial porter upload is problematic because the environment
2812 in which the package was built was not good enough (outdated or obsolete
2813 library, bad compiler, ...). Then you may just need to recompile it in
2814 an updated environment. However, you have to bump the version number in
2815 this case, so that the old bad package can be replaced in the Debian archive
2816 (<prgn>katie</prgn> refuses to install new packages if they don't have a
2817 version number greater than the currently available one).
2818         <p>
2819 You have to make sure that your binary-only NMU doesn't render the package
2820 uninstallable. This could happen when a source package generates
2821 arch-dependent and arch-independent packages that depend on each other via
2822 $(Source-Version).
2823         <p>
2824 Despite the
2825 required modification of the changelog, these are called binary-only NMUs
2826 &mdash; there is no need in this case to trigger all other architectures
2827 to consider themselves out of date or requiring recompilation.
2828         <p>
2829 Such recompilations require special ``magic'' version numbering, so that
2830 the archive maintenance tools recognize that, even though there is a
2831 new Debian version, there is no corresponding source update.  If you
2832 get this wrong, the archive maintainers will reject your upload (due
2833 to lack of corresponding source code).
2834         <p>
2835 The ``magic'' for a recompilation-only NMU is triggered by using a
2836 suffix appended to the package version number,
2837 following the form b&lt;number&gt;.
2838 For instance, if the latest version you are
2839 recompiling against was version ``2.9-3'', your NMU should carry a
2840 version of ``2.9-3+b1''.  If the latest version was ``3.4+b1'' (i.e, a
2841 native package with a previous recompilation NMU), your NMU should have
2842 a version number of ``3.4+b2''.
2843
2844 <footnote>
2845 In the past, such NMUs used the third-level number on the Debian part of
2846 the revision to denote their recompilation-only status; however, this
2847 syntax was ambiguous with native packages and did not allow proper
2848 ordering of recompile-only NMUs, source NMUs, and security NMUs on the
2849 same package, and has therefore been abandoned in favor of this new
2850 syntax.</footnote>
2851         <p>
2852 Similar to initial porter uploads, the correct way of invoking
2853 <prgn>dpkg-buildpackage</prgn> is <tt>dpkg-buildpackage -B</tt> to only
2854 build the architecture-dependent parts of the package.
2855
2856
2857         <sect2 id="source-nmu-when-porter">
2858           <heading>When to do a source NMU if you are a porter</heading>
2859           <p>
2860 Porters doing a source NMU generally follow the guidelines found in
2861 <ref id="nmu">, just like non-porters.  However, it is expected that
2862 the wait cycle for a porter's source NMU is smaller than for a
2863 non-porter, since porters have to cope with a large quantity of
2864 packages.
2865 Again, the situation varies depending on the distribution they are
2866 uploading to. It also varies whether the architecture is a candidate
2867 for inclusion into the next stable release; the release managers
2868 decide and announce which architectures are candidates.
2869           <p>
2870 If you are a porter doing an NMU for `unstable', the above
2871 guidelines for porting should be followed, with two variations.
2872 Firstly, the acceptable waiting period &mdash; the time between when the
2873 bug is submitted to the BTS and when it is OK to do an NMU &mdash; is seven
2874 days for porters working on the unstable distribution.  This period
2875 can be shortened if the problem is critical and imposes hardship on
2876 the porting effort, at the discretion of the porter group.  (Remember,
2877 none of this is Policy, just mutually agreed upon guidelines.)
2878 For uploads to stable or testing, please coordinate with the appropriate
2879 release team first.
2880           <p>
2881 Secondly, porters doing source NMUs should make sure that the bug they
2882 submit to the BTS should be of severity `serious' or greater.  This
2883 ensures that a single source package can be used to compile every
2884 supported Debian architecture by release time.  It is very important
2885 that we have one version of the binary and source package for all
2886 architecture in order to comply with many licenses.
2887           <p>
2888 Porters should try to avoid patches which simply kludge around bugs in
2889 the current version of the compile environment, kernel, or libc.
2890 Sometimes such kludges can't be helped.  If you have to kludge around
2891 compiler bugs and the like, make sure you <tt>#ifdef</tt> your work
2892 properly; also, document your kludge so that people know to remove it
2893 once the external problems have been fixed.
2894           <p>
2895 Porters may also have an unofficial location where they can put the
2896 results of their work during the waiting period.  This helps others
2897 running the port have the benefit of the porter's work, even during
2898 the waiting period.  Of course, such locations have no official
2899 blessing or status, so buyer beware.
2900
2901
2902       <sect1 id="porter-automation">
2903           <heading>Porting infrastructure and automation</heading>
2904           <p>
2905 There is infrastructure and several tools to help automate package
2906 porting. This section contains a brief overview of this automation and
2907 porting to these tools; see the package documentation or references for
2908 full information.</p>
2909
2910           <sect2>
2911             <heading>Mailing lists and web pages</heading>
2912             <p>
2913 Web pages containing the status of each port can be found at <url
2914 id="&url-debian-ports;">.
2915             <p>
2916 Each port of Debian has a mailing list.  The list of porting mailing
2917 lists can be found at <url id="&url-debian-port-lists;">.  These lists
2918 are used to coordinate porters, and to connect the users of a given
2919 port with the porters.</p>
2920           </sect2>
2921
2922           <sect2>
2923             <heading>Porter tools</heading>
2924             <p>
2925 Descriptions of several porting tools can be found in <ref
2926 id="tools-porting">.</p>
2927           </sect2>
2928
2929           <sect2 id="buildd">
2930             <heading><package>buildd</package></heading>
2931             <p>
2932 The <package>buildd</package> system is used as a distributed,
2933 client-server build distribution system.  It is usually used in
2934 conjunction with <em>auto-builders</em>, which are ``slave'' hosts
2935 which simply check out and attempt to auto-build packages which need
2936 to be ported.  There is also an email interface to the system, which
2937 allows porters to ``check out'' a source package (usually one which
2938 cannot yet be auto-built) and work on it.
2939           <p>
2940 <package>buildd</package> is not yet available as a package; however,
2941 most porting efforts are either using it currently or planning to use
2942 it in the near future.  The actual automated builder is packaged as
2943 <package>sbuild</package>, see its description in <ref id="sbuild">.
2944 The complete <package>buildd</package> system also collects a number of as yet unpackaged
2945 components which are currently very useful and in use continually,
2946 such as <prgn>andrea</prgn> and
2947 <prgn>wanna-build</prgn>.
2948           <p>
2949 Some of the data produced by <package>buildd</package> which is
2950 generally useful to porters is available on the web at <url
2951 id="&url-buildd;">.  This data includes nightly updated information
2952 from <prgn>andrea</prgn> (source dependencies) and
2953 <package>quinn-diff</package> (packages needing recompilation).
2954           <p>
2955 We are quite proud of this system, since it has so
2956 many possible uses.  Independent development groups can use the system for
2957 different sub-flavors of Debian, which may or may not really be of
2958 general interest (for instance, a flavor of Debian built with <prgn>gcc</prgn>
2959 bounds checking).  It will also enable Debian to recompile entire
2960 distributions quickly.
2961           <p>
2962 The buildds admins of each arch can be contacted at the mail address
2963 $arch@buildd.debian.org.
2964
2965        <sect1 id="packages-arch-specific">When your package is <em>not</em> portable
2966        <p>
2967 Some packages still have issues with building and/or working on some
2968 of the architectures supported by Debian, and cannot be ported at all,
2969 or not within a reasonable amount of time. An example is a package that
2970 is SVGA-specific (only i386), or uses other hardware-specific features
2971 not supported on all architectures.
2972        <p>
2973 In order to prevent broken packages from being uploaded to the archive, and
2974 wasting buildd time, you need to do a few things:
2975        <p>
2976       <list>
2977       <item>
2978        <p>
2979 First, make sure your package <em>does</em> fail to build on
2980 architectures that it cannot support.
2981 There are a few ways to achieve this.
2982 The preferred way is to have a small testsuite during build time
2983 that will test the functionality, and fail if it doesn't work.
2984 This is a good idea anyway,
2985 as this will prevent (some) broken uploads on all architectures,
2986 and also will allow the package to build
2987 as soon as the required functionality is available.
2988        <p>
2989 Additionally, if you believe the list of supported architectures is
2990 pretty constant, you should change 'any' to a list of supported
2991 architectures in debian/control.  This way, the build will fail also,
2992 and indicate this to a human reader without actually trying.
2993       <item>
2994        <p>
2995 In order to prevent autobuilders from needlessly trying to build your
2996 package, it must be included in <file>packages-arch-specific</file>, a
2997 list used by the <prgn>wanna-build</prgn> script.
2998 The current version is available as
2999 <url id="http://cvs.debian.org/srcdep/Packages-arch-specific?cvsroot=dak">;
3000 please see the top of the file for whom to contact for changes.
3001       </list>
3002        <p>
3003 Please note that it is insufficient to only add your package to
3004 Packages-arch-specific
3005 without making it fail to build on unsupported architectures:
3006 A porter or any other person trying to build your package might
3007 accidently upload it without noticing it doesn't work.
3008 If in the past some binary packages were uploaded on unsupported architectures,
3009 request their removal by filing a bug against
3010 <package>ftp.debian.org</package>
3011
3012
3013     <sect id="nmu">Non-Maintainer Uploads (NMUs)
3014       <p>
3015 Under certain circumstances it is necessary for someone other than the
3016 official package maintainer to make a release of a package. This is
3017 called a non-maintainer upload, or NMU.
3018        <p>
3019 This section handles only source NMUs, i.e. NMUs which upload a new
3020 version of the package. For binary-only NMUs by porters or QA members,
3021 please see <ref id="binary-only-nmu">.
3022 If a buildd builds and uploads a package,
3023 that too is strictly speaking a binary NMU.
3024 See <ref id="buildd"> for some more information.
3025         <p>
3026 The main reason why NMUs are done is when a
3027 developer needs to fix another developer's package in order to
3028 address serious problems or crippling bugs
3029 or when the package maintainer is unable to release a fix
3030 in a timely fashion.
3031         <p>
3032 First and foremost, it is critical that NMU patches to source should
3033 be as non-disruptive as possible.  Do not do housekeeping tasks, do
3034 not change the name of modules or files, do not move directories; in
3035 general, do not fix things which are not broken.  Keep the patch as
3036 small as possible.  If things bother you aesthetically, talk to the
3037 Debian maintainer, talk to the upstream maintainer, or submit a bug.
3038 However, aesthetic changes must <em>not</em> be made in a non-maintainer
3039 upload.
3040         <p>
3041 And please remember the Hippocratic Oath: "Above all, do no harm."  It
3042 is better to leave a package with an open grave bug than applying a
3043 non-functional patch, or one that hides the bug instead of resolving
3044 it.
3045
3046
3047       <sect1 id="nmu-guidelines">How to do a NMU
3048         <p>
3049 NMUs which fix important, serious or higher severity bugs are encouraged
3050 and accepted.
3051 You should endeavor to reach the current maintainer of the package; they
3052 might be just about to upload a fix for the problem, or have a better
3053 solution.
3054         <p>
3055 NMUs should be made to assist a package's maintainer in resolving bugs.
3056 Maintainers should be thankful for that help, and NMUers should respect
3057 the decisions of maintainers, and try to personally help the maintainer by
3058 their work.
3059         <p>
3060 A NMU should follow all conventions, written down in this section.
3061 For an upload to testing or unstable, this order of steps is recommended:
3062         <p>
3063 <list>
3064             <item>
3065 Make sure that the package's bugs that the NMU is meant to address are all
3066 filed in the Debian Bug Tracking System (BTS).
3067 If they are not, submit them immediately.
3068             <item>
3069 Wait a few days for the response from the maintainer. If you don't get
3070 any response, you may want to help them by sending the patch that fixes
3071 the bug. Don't forget to tag the bug with the "patch" keyword.
3072             <item>
3073 Wait a few more days. If you still haven't got an answer from the
3074 maintainer, send them a mail announcing your intent to NMU the package.
3075 Prepare an NMU as described in this section, and test it
3076 carefully on your machine (cf. <ref id="sanitycheck">).
3077 Double check that your patch doesn't have any unexpected side effects.
3078 Make sure your patch is as small and as non-disruptive as it can be.  
3079             <item>
3080 Upload your package to incoming in <file>DELAYED/7-day</file> (cf.
3081 <ref id="delayed-incoming">), send the final patch to the maintainer via
3082 the BTS, and explain to them that they have 7 days to react if they want
3083 to cancel the NMU.
3084             <item>
3085 Follow what happens, you're responsible for any bug that you introduced
3086 with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS)
3087 to stay informed of the state of the package after your NMU.
3088 </list>
3089         <p>
3090 At times, the release manager or an organized group of developers can
3091 announce a certain period of time in which the NMU rules are relaxed.
3092 This usually involves shortening the period during which one is to wait
3093 before uploading the fixes, and shortening the DELAYED period. It is
3094 important to notice that even in these so-called "bug squashing party"
3095 times, the NMU'er has to file bugs and contact the developer first,
3096 and act later.
3097 Please see <ref id="qa-bsp"> for details.
3098         <p>
3099 For the testing distribution, the rules may be changed by the release
3100 managers. Please take additional care, and acknowledge that the usual way
3101 for a package to enter testing is through unstable.
3102         <p>
3103 For the stable distribution, please take extra care. Of course, the release
3104 managers may also change the rules here. Please verify before you upload that
3105 all your changes are OK for inclusion into the next stable release by the
3106 release manager.
3107         <p>
3108 When a security bug is detected, the security team may do an NMU, using
3109 their own rules. Please refer to <ref id="bug-security"> for more
3110 information.
3111         <p>
3112 For the differences for Porters NMUs, please see 
3113 <ref id="source-nmu-when-porter">.
3114         <p>
3115 Of course, it is always possible to agree on special rules with a maintainer
3116 (like the maintainer asking "please upload this fix directly for me, and no
3117 diff required").
3118
3119
3120         <sect1 id="nmu-version">NMU version numbering
3121           <p>
3122 Whenever you have made a change to a package, no matter how trivial,
3123 the version number needs to change.  This enables our packing system
3124 to function.
3125           <p>
3126 If you are doing a non-maintainer upload (NMU), you should add a new
3127 minor version number to the <var>debian-revision</var> part of the
3128 version number (the portion after the last hyphen).  This extra minor
3129 number will start at `1'.  For example, consider the package `foo',
3130 which is at version 1.1-3.  In the archive, the source package control
3131 file would be <file>foo_1.1-3.dsc</file>.  The upstream version is
3132 `1.1' and the Debian revision is `3'.  The next NMU would add a new
3133 minor number `.1' to the Debian revision; the new source control file
3134 would be <file>foo_1.1-3.1.dsc</file>.
3135           <p>
3136 The Debian revision minor number is needed to avoid stealing one of
3137 the package maintainer's version numbers, which might disrupt their
3138 work.