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