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