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