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