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