1 <!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!ENTITY % versiondata SYSTEM "version.ent"> %versiondata;
5 <!-- common, language independant entities -->
6 <!ENTITY % commondata SYSTEM "common.ent" > %commondata;
8 <!-- CVS revision of this document -->
9 <!ENTITY cvs-rev "$Revision: 1.220 $">
10 <!-- if you are translating this document, please notate the CVS
11 revision of the developers reference here -->
13 <!ENTITY cvs-en-rev "X.YY">
16 <!-- how to mark a section that needs more work -->
17 <!ENTITY FIXME "<em>FIXME:</em> ">
22 <title>Debian Developer's Reference
24 <author>Developer's Reference Team &email-devel-ref;
25 <author>Adam Di Carlo, editor
26 <author>Raphaël Hertzog
27 <author>Christian Schwarz
29 <version>ver. &version;, &date-en;
33 copyright © 1998—2003 Adam Di Carlo</copyrightsummary>
35 copyright © 2002—2003 Raphaël Hertzog</copyrightsummary>
37 copyright © 1997, 1998 Christian Schwarz</copyrightsummary>
39 This manual is free software; you may redistribute it and/or modify it
40 under the terms of the GNU General Public License as published by the
41 Free Software Foundation; either version 2, or (at your option) any
44 This is distributed in the hope that it will be useful, but
45 <em>without any warranty</em>; without even the implied warranty of
46 merchantability or fitness for a particular purpose. See the GNU
47 General Public License for more details.
49 A copy of the GNU General Public License is available as &file-GPL; in
50 the &debian-formal; distribution or on the World Wide Web at <url
51 id="&url-gpl;" name="the GNU web site">. You can also obtain it by
52 writing to the &fsf-addr;.
56 <chapt id="scope">Scope of This Document
58 The purpose of this document is to provide an overview of the
59 recommended procedures and the available resources for Debian
62 <!-- FIXME: rewrites -->
64 The procedures discussed within include how to become a maintainer
65 (<ref id="new-maintainer">); how to create new packages
66 (<ref id="newpackage">) and how to upload packages (<ref id="upload">);
67 how to handle bug reports (<ref id="bug-handling">); how to move,
68 remove, or orphan packages (<ref id="archive-manip">); how to port
69 packages (<ref id="porting">); and how and when to do interim
70 releases of other maintainers' packages (<ref id="nmu">).
72 The resources discussed in this reference include the mailing lists
73 (<ref id="mailing-lists">) and servers (<ref id="server-machines">); a
74 discussion of the structure of the Debian archive (<ref
75 id="archive">); explanation of the different servers which accept
76 package uploads (<ref id="upload-ftp-master">); and a discussion of
77 resources which can help maintainers with the quality of their
78 packages (<ref id="tools">).
80 It should be clear that this reference does not discuss the technical
81 details of the Debian package nor how to generate Debian packages.
82 Nor does this reference detail the standards to which Debian software
83 must comply. All of such information can be found in the <url
84 id="&url-debian-policy;" name="Debian Policy Manual">.
86 Furthermore, this document is <em>not an expression of formal
87 policy</em>. It contains documentation for the Debian system and
88 generally agreed-upon best practices. Thus, it is what is called a
89 ``normative'' document.
92 <chapt id="new-maintainer">Applying to Become a Maintainer
94 <sect id="getting-started">Getting started
96 So, you've read all the documentation, you've gone through the <url
97 id="&url-newmaint-guide;" name="Debian New Maintainers' Guide">,
98 understand what everything in the <package>hello</package> example
99 package is for, and you're about to Debianize your favorite piece of
100 software. How do you actually become a Debian developer so that your
101 work can be incorporated into the Project?
103 Firstly, subscribe to &email-debian-devel; if you haven't already.
104 Send the word <tt>subscribe</tt> in the <em>Subject</em> of an email
105 to &email-debian-devel-req;. In case of problems, contact the list
106 administrator at &email-listmaster;. More information on available
107 mailing lists can be found in <ref id="mailing-lists">.
108 &email-debian-devel-announce; is another list which is mandatory
109 for anyone who wishes to follow Debian's development.
111 You should subscribe and lurk (that is, read without posting) for a
112 bit before doing any coding, and you should post about your intentions
113 to work on something to avoid duplicated effort.
115 Another good list to subscribe to is &email-debian-mentors;. See <ref
116 id="mentors"> for details. The IRC channel <tt>#debian</tt> can also be
120 When you know how you want to contribute to &debian-formal;, you
121 should get in contact with existing Debian maintainers who are working
122 on similar tasks. That way, you can learn from experienced developers.
123 For example, if you are interested in packaging existing software for
124 Debian you should try to get a sponsor. A sponsor will work together
125 with you on your package and upload it to the Debian archive once they
126 are happy with the packaging work you have done. You can find a sponsor
127 by mailing the &email-debian-mentors; mailing list, describing your
128 package and yourself and asking for a sponsor (see <ref id="sponsoring">
129 for more information on sponsoring). On the other hand, if you are
130 interested in porting Debian to alternative architectures or kernels
131 you can subscribe to port specific mailing lists and ask there how to
132 get started. Finally, if you are interested in documentation or
133 Quality Assurance (QA) work you can join maintainers already working on
134 these tasks and submit patches and improvements.
137 <sect id="registering">Registering as a Debian developer
139 Before you decide to register with &debian-formal;, you will need to
140 read all the information available at the <url id="&url-newmaint;"
141 name="New Maintainer's Corner">. It describes exactly the
142 preparations you have to do before you can register to become a Debian
145 For example, before you apply, you have to read the <url
146 id="&url-social-contract;" name="Debian Social Contract">.
147 Registering as a developer means that you agree with and pledge to
148 uphold the Debian Social Contract; it is very important that
149 maintainers are in accord with the essential ideas behind
150 &debian-formal;. Reading the <url id="&url-gnu-manifesto;" name="GNU
151 Manifesto"> would also be a good idea.
153 The process of registering as a developer is a process of verifying
154 your identity and intentions, and checking your technical skills. As
155 the number of people working on &debian-formal; has grown to over
156 &number-of-maintainers; people and our systems are used in several
157 very important places we have to be careful about being compromised.
158 Therefore, we need to verify new maintainers before we can give them
159 accounts on our servers and let them upload packages.
161 Before you actually register you should have shown that you can do
162 competent work and will be a good contributor. You can show this by
163 submitting patches through the Bug Tracking System or having a package
164 sponsored by an existing maintainer for a while. Also, we expect that
165 contributors are interested in the whole project and not just in
166 maintaining their own packages. If you can help other maintainers by
167 providing further information on a bug or even a patch, then do so!
169 Registration requires that you are familiar with Debian's philosophy
170 and technical documentation. Furthermore, you need a GnuPG key which
171 has been signed by an existing Debian maintainer. If your GnuPG key
172 is not signed yet, you should try to meet a Debian maintainer in
173 person to get your key signed. There's a <url id="&url-gpg-coord;"
174 name="GnuPG Key Signing Coordination page"> which should help you find
175 a maintainer close to you (If you cannot find a Debian maintainer
176 close to you, there's an alternative way to pass the ID check. You
177 can send in a photo ID signed with your GnuPG key. Having your GnuPG
178 key signed is the preferred way, however. See the
179 <url id="&url-newmaint-id;" name="identification page"> for more
180 information about these two options.)
183 If you do not have an OpenPGP key yet, generate one. Every developer
184 needs a OpenPGP key in order to sign and verify package uploads. You
185 should read the manual for the software you are using, since it has
186 much important information which is critical to its security. Many
187 more security failures are due to human error than to software failure
188 or high-powered spy techniques. See <ref id="key-maint"> for more
189 information on maintaining your public key.
191 Debian uses the <prgn>GNU Privacy Guard</prgn> (package
192 <package>gnupg</package> version 1 or better) as its baseline standard.
193 You can use some other implementation of OpenPGP as well. Note that
194 OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC
197 The recommended public key algorithm for use in Debian development
198 work is DSA (sometimes call ``DSS'' or ``DH/ElGamal''). Other key
199 types may be used however. Your key length must be at least 1024
200 bits; there is no reason to use a smaller key, and doing so would be
201 much less secure. Your key must be signed with at least your own user
202 ID; this prevents user ID tampering. <prgn>gpg</prgn> does this
205 If your public key isn't on public key servers such as &pgp-keyserv;,
206 please read the documentation available locally in &file-keyservs;.
207 That document contains instructions on how to put your key on the
208 public key servers. The New Maintainer Group will put your public key
209 on the servers if it isn't already there.
211 Some countries restrict the use of cryptographic software by their
212 citizens. This need not impede one's activities as a Debian package
213 maintainer however, as it may be perfectly legal to use cryptographic
214 products for authentication, rather than encryption purposes.
215 &debian-formal; does not require the use of cryptography <em>qua</em>
216 cryptography in any manner. If you live in a country where use of
217 cryptography even for authentication is forbidden
218 then please contact us so we can make special arrangements.
220 To apply as a new maintainer, you need an existing Debian maintainer
221 to verify your application (an <em>advocate</em>). After you have
222 contributed to Debian for a while, and you want to apply to become a
223 registered developer, an existing developer with whom you
224 have worked over the past months has to express his belief that you
225 can contribute to Debian successfully.
227 When you have found an advocate, have your GnuPG key signed and have
228 already contributed to Debian for a while, you're ready to apply.
229 You can simply register on our <url id="&url-newmaint-apply;"
230 name="application page">. After you have signed up, your advocate
231 has to confirm your application. When your advocate has completed
232 this step you will be assigned an Application Manager who will
233 go with you through the necessary steps of the New Maintainer process.
234 You can always check your status on the <url id="&url-newmaint-db;"
235 name="applications status board">.
237 For more details, please consult <url id="&url-newmaint;" name="New
238 Maintainer's Corner"> at the Debian web site. Make sure that you
239 are familiar with the necessary steps of the New Maintainer process
240 before actually applying. If you are well prepared, you can save
241 a lot of time later on.
244 <sect id="mentors">Debian mentors and sponsors
246 The mailing list &email-debian-mentors; has been set up for novice
247 maintainers who seek help with initial packaging and other
248 developer-related issues. Every new developer is invited to subscribe
249 to that list (see <ref id="mailing-lists"> for details).
251 Those who prefer one-on-one help (e.g., via private email) should also
252 post to that list and an experienced developer will volunteer to help.
254 In addition, if you have some packages ready for inclusion in Debian,
255 but are waiting for your new maintainer application to go through, you
256 might be able find a sponsor to upload your package for you. Sponsors
257 are people who are official Debian maintainers, and who are willing to
258 criticize and upload your packages for you. Those who are seeking a
259 sponsor can request one at <url id="&url-sponsors;">.
261 If you wish to be a mentor and/or sponsor, more information is
262 available in <ref id="newmaint">.
265 <chapt id="developer-duties">Debian Developer's Duties
267 <sect id="user-maint">Maintaining your Debian information
269 There's a LDAP database containing information about Debian developers at
270 <url id="&url-debian-db;">. You should enter your information there and
271 update it as it changes. Most notably, make sure that the address where your
272 debian.org email gets forwarded to is always up to date, as well as the
273 address where you get your debian-private subscription if you choose to
276 For more information about the database, please see <ref id="devel-db">.
280 <sect id="key-maint">Maintaining your public key
282 Be very careful with your private keys. Do not place them on any
283 public servers or multiuser machines, such as the Debian servers
284 (see <ref id="server-machines">). Back your keys up; keep a copy offline.
285 Read the documentation that comes with your software; read the <url
286 id="&url-pgp-faq;" name="PGP FAQ">.
288 If you add signatures to your public key, or add user identities, you
289 can update the Debian key ring by sending your key to the key server at
290 <tt>&keyserver-host;</tt>. If you need to add a completely new key,
291 or remove an old key, send mail to &email-debian-keyring;. The same
292 key extraction routines discussed in <ref id="registering"> apply.
294 You can find a more in-depth discussion of Debian key maintenance in
295 the documentation of the <package>debian-keyring</package> package.
298 <sect id="voting">Voting
300 Even though Debian isn't really a democracy, we use a democratic
301 process to elect our leaders and to approve general resolutions.
302 These procedures are defined by the
303 <url id="&url-constitution;" name="Debian Constitution">.
305 Other than the yearly leader election, votes are not routinely held, and
306 they are not undertaken lightly. Each proposal is first discussed on
307 the &email-debian-vote; mailing list and it requires several endorsements
308 before the project secretary starts the voting procedure.
310 You don't have to track the pre-vote discussions, as the secretary will
311 issue several calls for votes on &email-debian-devel-announce; (and all
312 developers are expected to be subscribed to that list). Democracy doesn't
313 work well if people don't take part in the vote, which is why we encourage
314 all developers to vote. Voting is conducted via GPG-signed/encrypted emails
317 The list of all the proposals (past and current) is available on the
318 <url id="&url-vote;" name="Debian Voting Information"> page, along with
319 information on how to make, second and vote on proposals.
322 <sect id="inform-vacation">Going on vacation gracefully
324 It is common for developers to have periods of absence, whether those are
325 planned vacations or simply being buried in other work. The important thing
326 to notice is that the other developers need to know that you're on vacation
327 so that they can do whatever is needed if a problem occurs with your
328 packages or other duties in the project.
330 Usually this means that other developers are allowed to NMU (see
331 <ref id="nmu">) your package if a big problem (release critical bugs,
332 security update, etc.) occurs while you're on vacation. Sometimes it's
333 nothing as critical as that, but it's still appropriate to let the others
334 know that you're unavailable.
336 In order to inform the other developers, there's two things that you should do.
337 First send a mail to &email-debian-private; with "[VAC] " prepended to the
338 subject of your message<footnote>This is so that the message can be easily
339 filtered by people who don't want to read vacation notices.</footnote>
340 and state the period of time when you will be on vacation. You can also give
341 some special instructions on what to do if a problem occurs.
343 The other thing to do is to mark yourself as "on vacation" in the
344 <qref id="devel-db">Debian developers' LDAP database</qref> (this
345 information is only accessible to Debian developers).
346 Don't forget to remove the "on vacation" flag when you come back!
349 <sect id="upstream-coordination">Coordination with upstream developers
351 A big part of your job as Debian maintainer will be to stay in contact
352 with the upstream developers. Debian users will sometimes report bugs
353 that are not specific to Debian to our bug tracking system. You
354 have to forward these bug reports to the upstream developers so that
355 they can be fixed in a future upstream release.
357 While it's not your job to fix non-Debian specific bugs, you may freely
358 do so if you're able. When you make such fixes, be sure to pass them on
359 to the upstream maintainers as well. Debian users and developers will
360 sometimes submit patches to fix upstream bugs -- you should evaluate
361 and forward these patches upstream.
363 If you need to modify the upstream sources in order to build a policy
364 compliant package, then you should propose a nice fix to the upstream
365 developers which can be included there, so that you won't have to
366 modify the sources of the next upstream version. Whatever changes you
367 need, always try not to fork from the upstream sources.
370 <sect id="rc-bugs">Managing release-critical bugs
372 Generally you should deal with bug reports on your packages as described in
373 <ref id="bug-handling">. However, there's a special category of bugs that
374 you need to take care of -- the so-called release-critical bugs (RC bugs).
375 All bug reports that have severity <em>critical</em>, <em>grave</em> or
376 <em>serious</em> are considered to have an impact on whether the package can
377 be released in the next stable release of Debian.
378 Those bugs can delay the Debian release
379 and/or can justify the removal of a package at freeze time. That's why
380 these bugs need to be corrected as quickly as possible.
382 Developers who are part of the <url id="&url-debian-qa;"
383 name="Quality Assurance"> group are following all such bugs, and trying
384 to help whenever possible. If, for any reason, you aren't able fix an
385 RC bug in a package of yours within 2 weeks, you should either ask for help
386 by sending a mail to the Quality Assurance (QA) group
387 &email-debian-qa;, or explain your difficulties and present a plan to fix
388 them by sending a mail to the bug report. Otherwise, people
389 from the QA group may want to do a Non-Maintainer Upload (see
390 <ref id="nmu">) after trying to contact you (they might not wait as long as
391 usual before they do their NMU if they have seen no recent activity from you
397 If you choose to leave the Debian project, you should make sure you do
401 Orphan all your packages, as described in <ref id="orphaning">.
403 Send an email about why you are leaving the project to
404 &email-debian-private;.
406 Notify the Debian key ring maintainers that you are leaving by
407 emailing to &email-debian-keyring;.
412 <chapt id="resources">Resources for Debian Developers
414 In this chapter you will find a very brief road map of the Debian
415 mailing lists, the Debian machines
416 which may be available to you as a developer, and all the other
417 resources that are available to help you in your maintainer work.
419 <sect id="mailing-lists">Mailing lists
421 Much of the conversation between Debian developers (and users) is managed
422 through a wide array of mailing lists we host at
423 <tt><url id="http://&lists-host;/" name="&lists-host;"></tt>.
424 To find out more on how to subscribe or unsubscribe, how to post and how not
425 to post, where to find old posts and how to search them, how to contact the
426 list maintainers and see various other information about the mailing lists,
427 please read <url id="&url-debian-lists;">. This section will only cover
428 aspects of mailing lists that are of particular interest to developers.
430 <sect1 id="mailing-lists-rules">Basic rules for use
432 When replying to messages on the mailing list, please do not send a
433 carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
434 request to be copied. Anyone who posts to a mailing list should read
435 it to see the responses.
437 Cross-posting (sending the same message to multiple lists) is discouraged.
438 As ever on the net, please trim down the quoting of articles you're
439 replying to. In general, please adhere to the usual conventions for
442 Please read the <url name="code of conduct" id="&url-debian-lists;#codeofconduct">
443 for more information.
445 <sect1 id="core-devel-mailing-lists">Core development mailing lists
447 The core Debian mailing lists that developers should use are:
449 <item>&email-debian-devel-announce;, used to announce important things to
451 All developers are expected to be subscribed to this list.
453 <item>&email-debian-devel;, used to discuss various development related
456 <item>&email-debian-policy;, where the Debian Policy is discussed and
459 <item>&email-debian-project;, used to discuss various non-technical
460 issues related to the project.
464 There are other mailing lists available for a variety of special topics;
465 see <url id="http://&lists-host;/"> for a list.
467 <sect1 id="mailing-lists-special">Special lists
469 &email-debian-private; is a special mailing list for private
470 discussions amongst Debian developers. It is meant to be used for
471 posts which for whatever reason should not be published publicly.
472 As such, it is a low volume list, and users are urged not to use
473 &email-debian-private; unless it is really necessary. Moreover, do
474 <em>not</em> forward email from that list to anyone. Archives of this
475 list are not available on the web for obvious reasons, but you can see
476 them using your shell account on <tt>lists.debian.org</tt> and looking
477 in the <file>~debian/archive/debian-private</file> directory.
479 &email-debian-email; is a special mailing list used as a grab-bag
480 for Debian related correspondence such as contacting upstream authors
481 about licenses, bugs, etc. or discussing the project with others where it
482 might be useful to have the discussion archived somewhere.
484 <sect1 id="mailing-lists-new">Requesting new development-related lists
486 Before requesting a mailing list that relates to the development of a
487 package (or a small group of related packages), please consider if using
488 an alias (via a .forward-aliasname file on master.debian.org, which
489 translates into a reasonably nice <var>you-aliasname@debian.org</var>
490 address) or a self-managed mailing list on <qref id="alioth">Alioth</qref>
493 If you decide that a regular mailing list on lists.debian.org is really what
494 you want, go ahead and fill in a request, following <url name="the HOWTO"
495 id="&url-debian-lists-new;">.
497 <sect id="irc-channels">IRC channels
499 Several IRC channels are dedicated to Debian's development. They are mainly
500 hosted on the <url id="&url-openprojects;" name="freenode"> network
501 (previously known as Open Projects Network).
502 The <tt>irc.debian.org</tt> DNS entry is an alias to
503 <tt>irc.freenode.net</tt>.
505 The main channel for Debian in general is <em>#debian</em>. This is a large,
506 general-purpose channel where users can find recent news in the topic and
507 served by bots. <em>#debian</em> is for English speakers; there are also
508 <em>#debian.de</em>, <em>#debian-fr</em>, <em>#debian-br</em> and other
509 similarly named channels for speakers of other languages.
511 The main channel for Debian development is <em>#debian-devel</em>.
512 It is a very active channel since usually over 150 people are always
513 logged in. It's a channel for people who work
514 on Debian, it's not a support channel (there's <em>#debian</em> for that).
515 It is however open to anyone who wants to lurk (and learn). Its topic is
516 commonly full of interesting information for developers.
518 Since <em>#debian-devel</em> it's an open channel, you
519 should not speak there of issues that are discussed in
520 &email-debian-private;. There's another channel for this purpose,
521 it's called <em>#debian-private</em> and it's protected by a key.
522 This key is available in the archives of debian-private in
523 <file>master.debian.org:&file-debian-private-archive;</file>,
524 just <prgn>zgrep</prgn> for <em>#debian-private</em> in
527 There are other additional channels dedicated to specific subjects.
528 <em>#debian-bugs</em> is used for coordinating bug squash parties.
529 <em>#debian-boot</em> is used to coordinate the work on the boot
530 floppies (i.e., the installer). <em>#debian-doc</em> is
531 occasionally used to talk about documentation, like the document you are
532 reading. Other channels are dedicated to an architecture or a set of
533 packages: <em>#debian-bsd</em>, <em>#debian-kde</em>, <em>#debian-jr</em>,
534 <em>#debian-edu</em>,
535 <em>#debian-sf</em> (SourceForge package), <em>#debian-oo</em> (OpenOffice
538 Some non-English developers' channels exist as well, for example
539 <em>#debian-devel-fr</em> for
540 French speaking people interested in Debian's development.
542 Channels dedicated to Debian also exist on other IRC networks, notably on
543 the <url name="Open and free technology community (OFTC)"
544 id="http://www.oftc.net/"> IRC network.
547 <sect id="doc-rsrcs">Documentation
549 This document contains a lot of information very useful to Debian developers,
550 but it can not contain everything. Most of the other interesting documents
551 are linked from <url id="&url-devel-docs;" name="The Developers' Corner">.
552 Take the time to browse all the links, you will learn many more things.
555 <sect id="server-machines">Debian machines
557 Debian has several computers working as servers, most of which serve
558 critical functions in the Debian project. Most of the machines are used
559 for porting activities, and they all have a permanent connection to the
562 Most of the machines are available for individual developers to use,
563 as long as the developers follow the rules set forth in the
564 <url name="Debian Machine Usage Policies" id="&url-dmup;">.
566 Generally speaking, you can use these machines for Debian-related purposes
567 as you see fit. Please be kind to system administrators, and do not use
568 up tons and tons of disk space, network bandwidth, or CPU without first
569 getting the approval of the system administrators. Usually these machines are run by
572 Please take care to protect your Debian passwords and SSH keys installed on
573 Debian machines. Avoid login or upload methods which send passwords over
574 the Internet in the clear, such as telnet, FTP, POP etc.
576 Please do not put any material that doesn't relate to Debian on the Debian
577 servers, unless you have prior permission.
579 The current list of Debian machines is available at
580 <url id="&url-devel-machines;">. That web page contains machine names,
581 contact information, information about who can log in, SSH keys etc.
583 If you have a problem with the operation of a Debian server, and you
584 think that the system operators need to be notified of this problem,
585 the Debian system administrator team is reachable at
586 <email>debian-admin@lists.debian.org</email>.
588 If you have a problem with a certain service, not related to the system
589 administration (such as packages to be removed from the archive,
590 suggestions for the web site, etc.),
591 generally you'll report a bug against a ``pseudo-package''. See <ref
592 id="submit-bug"> for information on how to submit bugs.
594 <sect1 id="servers-bugs">The bugs server
596 <tt>&bugs-host;</tt> is the canonical location for the Bug Tracking
597 System (BTS). If you plan on doing some statistical analysis or
598 processing of Debian bugs, this would be the place to do it. Please
599 describe your plans on &email-debian-devel; before implementing
600 anything, however, to reduce unnecessary duplication of effort or
601 wasted processing time.
603 All Debian developers have accounts on <tt>&bugs-host;</tt>.
605 <sect1 id="servers-ftp-master">The ftp-master server
607 The <tt>ftp-master.debian.org</tt> server holds the canonical copy of the Debian
608 archive (excluding the non-US packages). Generally, package uploads
609 go to this server; see <ref id="upload">.
611 Problems with the Debian FTP archive generally need to be reported as
612 bugs against the <package>ftp.debian.org</package> pseudo-package or
613 an email to &email-ftpmaster;, but also see the procedures in
614 <ref id="archive-manip">.
616 <sect1 id="servers-non-us">The non-US server
618 The non-US server, <tt>non-us.debian.org</tt>,
619 holds the canonical copy of the non-US part of the Debian archive.
620 If you need to upload a package into one of the non-US sections, upload it
621 to this server; see <ref id="upload-non-us">.
623 Problems with the non-US package archive should generally be submitted as
624 bugs against the <package>nonus.debian.org</package> pseudo-package (notice
625 the lack of hyphen between "non" and "us" in the pseudo-package name
626 — that's for backwards compatibility). Remember to check whether or
627 not someone else has already reported the problem on the
628 <url id="http://&bugs-host;/nonus.debian.org" name="Bug Tracking System">.
630 <sect1 id="servers-www">The www-master server
632 The main web server is <tt>www-master.debian.org</tt>.
633 It holds the official web pages, the face
634 of Debian for most newbies.
636 If you find a problem with the Debian web server, you should generally
637 submit a bug against the pseudo-package,
638 <package>www.debian.org</package>. Remember to check whether or not someone
639 else has already reported the problem on the
640 <url id="http://&bugs-host;/www.debian.org" name="Bug Tracking System">.
642 <sect1 id="servers-people">The people web server
644 <tt>people.debian.org</tt> is the server used
645 for developers' own web pages about anything related to Debian.
647 If you have some Debian-specific information which you want to serve
648 on the web, you can do this by putting material in the
649 <file>public_html</file> directory under your home directory on
650 <tt>people.debian.org</tt>.
651 This will be accessible at the URL
652 <tt>http://people.debian.org/~<var>your-user-id</var>/</tt>.
654 You should only use this particular location because it will be backed up,
655 whereas on other hosts it won't.
657 Usually the only reason to use a different host is when you need to publish
658 materials subject to the U.S. export restrictions, in which case you can use
659 one of the other servers located outside the United States, such as the
660 aforementioned <tt>non-us.debian.org</tt>.
662 Send mail to &email-debian-devel; if you have any questions.
664 <sect1 id="servers-cvs">The CVS server
666 Our CVS server is located on <tt>cvs.debian.org</tt>.
668 If you need to use a publicly accessible CVS
669 server, for instance, to help coordinate work on a package between
670 many different developers, you can request a CVS area on the server.
672 Generally, <tt>cvs.debian.org</tt> offers a combination of local CVS
673 access, anonymous client-server read-only access, and full
674 client-server access through <prgn>ssh</prgn>. Also, the CVS area can
675 be accessed read-only via the Web at <url id="&url-cvsweb;">.
677 To request a CVS area, send a request via email to
678 &email-debian-admin;. Include the name of the requested CVS area,
679 the Debian account that should own the CVS root area, and why you need it.
682 <sect id="devel-db">The Developers Database
684 The Developers Database, at <url id="&url-debian-db;">, is an LDAP
685 directory for managing Debian developer attributes. You can use this
686 resource to search the list of Debian developers.
687 Part of this information is also available through
688 the finger service on Debian servers, try
689 <prgn>finger yourlogin@db.debian.org</prgn> to see what it reports.
691 Developers can <url name="log into the database" id="&url-debian-db-login;">
692 to change various information about themselves, such as:
694 <item>forwarding address for your debian.org email
695 <item>subscription to debian-private
696 <item>whether you are on vacation
697 <item>personal information such as your address, country,
698 the latitude and longitude of the place where you live
699 for use in <url name="the world map of Debian developers"
700 id="&url-worldmap;">, phone and fax numbers, IRC nickname
702 <item>password and preferred shell on Debian Project machines
705 Most of the information is not accessible to the public, naturally.
706 For more information please read the online documentation that you can find
707 at <url id="&url-debian-db-doc;">.
709 One can also submit their SSH keys to be used for authorization on the
710 official Debian machines, and even add new *.debian.net DNS entries.
711 Those features are documented at <url id="&url-debian-db-mail-gw;">.
714 <sect id="archive">The Debian archive
716 The &debian-formal; distribution consists of a lot of packages
717 (<file>.deb</file>'s, currently around &number-of-pkgs;) and a few
718 additional files (such as documentation and installation disk images).
720 Here is an example directory tree of a complete Debian archive:
722 &sample-dist-dirtree;
724 As you can see, the top-level directory contains two directories,
725 <file>dists/</file> and <file>pool/</file>. The latter is a “pool” in which the
726 packages actually are, and which is handled by the archive maintenance
727 database and the accompanying programs. The former contains the
728 distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>.
729 The <file>Packages</file> and <file>Sources</file> files in the
730 distribution subdirectories can reference files in the <file>pool/</file>
731 directory. The directory tree below each of the distributions is arranged
732 in an identical manner. What we describe below for <em>stable</em> is
733 equally applicable to the <em>unstable</em> and <em>testing</em>
736 <file>dists/stable</file> contains three directories, namely <file>main</file>,
737 <file>contrib</file>, and <file>non-free</file>.
739 In each of the areas, there is a directory for the source packages
740 (<file>source</file>) and a directory for each supported architecture
741 (<file>binary-i386</file>, <file>binary-m68k</file>, etc.).
743 The <file>main</file> area contains additional directories which hold
744 the disk images and some essential pieces of documentation required
745 for installing the Debian distribution on a specific architecture
746 (<file>disks-i386</file>, <file>disks-m68k</file>, etc.).
751 The <em>main</em> section of the Debian archive is what makes up the
752 <strong>official &debian-formal; distribution</strong>. The
753 <em>main</em> section is official because it fully complies with all
754 our guidelines. The other two sections do not, to different degrees;
755 as such, they are <strong>not</strong> officially part of
758 Every package in the main section must fully comply with the <url
759 id="&url-dfsg;" name="Debian Free Software Guidelines"> (DFSG) and
760 with all other policy requirements as described in the <url
761 id="&url-debian-policy;" name="Debian Policy Manual">. The DFSG is
762 our definition of “free software.” Check out the Debian Policy
765 Packages in the <em>contrib</em> section have to comply with the DFSG,
766 but may fail other requirements. For instance, they may depend on
769 Packages which do not conform to the DFSG are placed in the
770 <em>non-free</em> section. These packages are not considered as part
771 of the Debian distribution, though we support their use, and we
772 provide infrastructure (such as our bug-tracking system and mailing
773 lists) for non-free software packages.
775 The <url id="&url-debian-policy;" name="Debian Policy Manual">
776 contains a more exact definition of the three sections. The above
777 discussion is just an introduction.
779 The separation of the three sections at the top-level of the archive
780 is important for all people who want to distribute Debian, either via
781 FTP servers on the Internet or on CD-ROMs: by distributing only the
782 <em>main</em> and <em>contrib</em> sections, one can avoid any legal
783 risks. Some packages in the <em>non-free</em> section do not allow
784 commercial distribution, for example.
786 On the other hand, a CD-ROM vendor could easily check the individual
787 package licenses of the packages in <em>non-free</em> and include as
788 many on the CD-ROMs as he's allowed to. (Since this varies greatly from
789 vendor to vendor, this job can't be done by the Debian developers.)
791 Note also that the term "section" is also used to refer to categories
792 which simplify the organization and browsing of available packages, e.g.
793 <em>admin</em>, <em>net</em>, <em>utils</em> etc. Once upon a time, these
794 sections (subsections, rather) existed in the form of subdirectories within
795 the Debian archive. Nowadays, these exist only in the "Section" header
801 In the first days, the Linux kernel was only available for the Intel
802 i386 (or greater) platforms, and so was Debian. But when Linux became
803 more and more popular, the kernel was ported to other architectures,
806 The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola
807 680x0 (like Atari, Amiga and Macintoshes), MIPS, and PowerPC. The
808 Linux 2.2 kernel supports even more architectures, including ARM and
809 UltraSPARC. Since Linux supports these platforms, Debian decided that
810 it should, too. Therefore, Debian has ports underway; in fact, we
811 also have ports underway to non-Linux kernels. Aside from
812 <em>i386</em> (our name for Intel x86), there is <em>m68k</em>,
813 <em>alpha</em>, <em>powerpc</em>, <em>sparc</em>, <em>hurd-i386</em>,
814 <em>arm</em>, <em>ia64</em>, <em>hppa</em>, <em>s390</em>, <em>mips</em>,
815 <em>mipsel</em> and <em>sh</em> as of this writing.
817 &debian-formal; 1.3 is only available as <em>i386</em>. Debian 2.0
818 shipped for <em>i386</em> and <em>m68k</em> architectures. Debian 2.1
819 ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and
820 <em>sparc</em> architectures. Debian 2.2 added support for the
821 <em>powerpc</em> and <em>arm</em> architectures. Debian 3.0 adds
822 support of five new architectures: <em>ia64</em>, <em>hppa</em>,
823 <em>s390</em>, <em>mips</em> and <em>mipsel</em>.
825 Information for developers and users about the specific ports are
826 available at the <url id="&url-debian-ports;" name="Debian Ports web
833 There are two types of Debian packages, namely <em>source</em> and
834 <em>binary</em> packages.
836 Source packages consist of either two or three files: a <file>.dsc</file>
837 file, and either a <file>.tar.gz</file> file or both an
838 <file>.orig.tar.gz</file> and a <file>.diff.gz</file> file.
840 If a package is developed specially for Debian and is not distributed
841 outside of Debian, there is just one <file>.tar.gz</file> file which
842 contains the sources of the program. If a package is distributed
843 elsewhere too, the <file>.orig.tar.gz</file> file stores the so-called
844 <em>upstream source code</em>, that is the source code that's
845 distributed from the <em>upstream maintainer</em> (often the author of
846 the software). In this case, the <file>.diff.gz</file> contains the
847 changes made by the Debian maintainer.
849 The <file>.dsc</file> file lists all the files in the source package together
850 with checksums (<prgn>md5sums</prgn>) and some additional info about
851 the package (maintainer, version, etc.).
856 The directory system described in the previous chapter is itself
857 contained within <em>distribution directories</em>. Each
858 distribution is actually contained in the <file>pool</file> directory in the
859 top-level of the Debian archive itself.
861 To summarize, the Debian archive has a root directory within an FTP
862 server. For instance, at the mirror site,
863 <ftpsite>ftp.us.debian.org</ftpsite>, the Debian archive itself is
864 contained in <ftppath>/debian</ftppath>, which is a common location
865 (another is <file>/pub/debian</file>).
867 A distribution is comprised of Debian source and binary packages, and the
868 respective <file>Sources</file> and <file>Packages</file> index files, containing
869 the header information from all those packages. The former are kept in the
870 <file>pool/</file> directory, while the latter are kept in the <file>dists/</file>
871 directory of the archive (for backwards compatibility).
874 <sect2 id="sec-dists">Stable, testing, and unstable
876 There are always distributions called <em>stable</em> (residing in
877 <file>dists/stable</file>), one called <em>testing</em> (residing in
878 <file>dists/testing</file>), and one called <em>unstable</em> (residing in
879 <file>dists/unstable</file>). This reflects the development process of the
882 Active development is done in the <em>unstable</em> distribution
883 (that's why this distribution is sometimes called the <em>development
884 distribution</em>). Every Debian developer can update his or her
885 packages in this distribution at any time. Thus, the contents of this
886 distribution changes from day-to-day. Since no special effort is done
887 to make sure everything in this distribution is working properly, it is
888 sometimes literally unstable.
890 <qref id="testing">"testing"</qref> is generated automatically by taking
891 packages from unstable if they satisfy certain criteria. Those
892 criteria should ensure a good quality for packages within testing.
893 The update to testing is launched each day after the
894 new packages have been installed. See <ref id="testing">.
896 After a period of development, once the release manager deems fit, the
897 <em>testing</em> distribution is frozen, meaning that the policies
898 which control how packages move from <em>unstable</em> to <em>testing</em> are
899 tightened. Packages which are too buggy are removed. No changes are
900 allowed into <em>testing</em> except for bug fixes. After some time
901 has elapsed, depending on progress, the <em>testing</em> distribution
902 goes into a `deep freeze', when no changes are made to it except those
903 needed for the installation system. This is called a “test cycle”,
904 and it can last up to two weeks. There can be several test cycles,
905 until the distribution is prepared for release, as decided by the
906 release manager. At the end of the last test cycle, the
907 <em>testing</em> distribution is renamed to <em>stable</em>,
908 overriding the old <em>stable</em> distribution, which is removed at
909 that time (although it can be found at <tt>&archive-host;</tt>).
911 This development cycle is based on the assumption that the
912 <em>unstable</em> distribution becomes <em>stable</em> after passing a
913 period of being in <em>testing</em>. Even once a distribution is
914 considered stable, a few bugs inevitably remain — that's why the
915 stable distribution is updated every now and then. However, these
916 updates are tested very carefully and have to be introduced into the
917 archive individually to reduce the risk of introducing new bugs. You
918 can find proposed additions to <em>stable</em> in the
919 <file>proposed-updates</file> directory. Those packages in
920 <file>proposed-updates</file> that pass muster are periodically moved as a
921 batch into the stable distribution and the revision level of the
922 stable distribution is incremented (e.g., ‘3.0’ becomes
923 ‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and
926 Note that development under <em>unstable</em> continues during the
927 freeze period, since the <em>unstable</em> distribution remains in
928 place in parallel with <em>testing</em>.
931 <heading>More information about the testing distribution</heading>
933 The scripts that update the <em>testing</em> distribution are run each
934 day after the installation of the updated packages. They generate the
935 <file>Packages</file> files for the <em>testing</em> distribution, but
936 they do so in an intelligent manner trying to avoid any inconsistency
937 and trying to use only non-buggy packages.
939 The inclusion of a package from <em>unstable</em> is conditional on
943 The package must have been available in <em>unstable</em> for several days;
944 the precise number depends on the upload's urgency field. It
945 is 10 days for low urgency, 5 days for medium urgency and 2 days for high
946 urgency. Those delays may be doubled during a freeze;
948 It must have less release-critical bugs than the version available
951 It must be available on all architectures on which it has been
952 previously built. <ref id="madison"> may be of interest to
953 check that information;
955 It must not break any dependency of a package that is already available
958 The packages on which it depends must either be available in <em>testing</em>
959 or they must be accepted into <em>testing</em> at the same time (and they will
960 if they respect all the necessary criteria);
963 To find out whether a package is progressing into testing or not, see the
964 testing script output on the <url name="web page of the testing distribution"
965 id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn>
966 which is in the <package>devscripts</package> package. This utility can
967 easily be used in a <manref name="crontab" section="5"> to keep one
968 informed of the progression of their packages into <em>testing</em>.
970 The <file>update_excuses</file> file does not always give the precise reason
971 why the package is refused, one may have to find it on their own by looking
972 for what would break with the inclusion of the package. The
973 <url id="&url-testing-maint;" name="testing web page"> gives some more
974 information about the usual problems which may be causing such troubles.
976 Sometimes, some packages never enter <em>testing</em> because the set of
977 inter-relationship is too complicated and cannot be sorted out
978 by the scripts. In that case, the release manager must be
979 contacted, and he will force the inclusion of the packages.
981 In general, please refer to the <url name="testing web page"
982 id="&url-testing-maint;"> for more information. It also includes
983 answers to some of the frequently asked questions.
986 <sect2 id="experimental">Experimental
988 The <em>experimental</em> distribution is a special distribution.
989 It is not a full distribution in the same sense as `stable' and
990 `unstable' are. Instead, it is meant to be a temporary staging area
991 for highly experimental software where there's a good chance that the
992 software could break your system, or software that's just too unstable
993 even for the <em>unstable</em> distribution (but there is a reason to
994 package it nevertheless). Users who download and install
995 packages from <em>experimental</em> are expected to have been duly
996 warned. In short, all bets are off for the <em>experimental</em>
999 These are the <manref name="sources.list" section="5"> lines for
1000 <em>experimental</em>:
1002 deb http://ftp.<var>xy</var>.debian.org/debian/ ../project/experimental main
1003 deb-src http://ftp.<var>xy</var>.debian.org/debian/ ../project/experimental main
1006 If there is a chance that the software could do grave damage to a system,
1007 it is likely to be better to put it into <em>experimental</em>.
1008 For instance, an experimental compressed file system should probably go
1009 into <em>experimental</em>.
1011 Whenever there is a new upstream version of a package that introduces new
1012 features but breaks a lot of old ones, it should either not be uploaded, or
1013 be uploaded to <em>experimental</em>. A new, beta, version of some software
1014 which uses a completely different configuration can go into
1015 <em>experimental</em>, at the maintainer's discretion. If you are working
1016 on an incompatible or complex upgrade situation, you can also use
1017 <em>experimental</em> as a staging area, so that testers can get early
1020 Some experimental software can still go into <em>unstable</em>, with a few
1021 warnings in the description, but that isn't recommended because packages
1022 from <em>unstable</em> are expected to propagate to <em>testing</em> and
1023 thus to <em>stable</em>. You should not be afraid to use
1024 <em>experimental</em> since it does not cause any pain to the ftpmasters,
1025 the experimental packages are automatically removed once you upload
1026 the package in <em>unstable</em> with a higher version number.
1028 New software which isn't likely to damage your system can go directly into
1031 An alternative to <em>experimental</em> is to use your personal web space
1032 on <tt>people.debian.org</tt>.
1035 <sect1 id="codenames">Release code names
1037 Every released Debian distribution has a <em>code name</em>: Debian
1038 1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0,
1039 `hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; and Debian 3.0, `woody'. There is also
1040 a ``pseudo-distribution'', called `sid', which is the current
1041 `unstable' distribution; since packages are moved from `unstable' to
1042 `testing' as they approach stability, `sid' itself is never released.
1043 As well as the usual contents of a Debian distribution, `sid' contains
1044 packages for architectures which are not yet officially supported or
1045 released by Debian. These architectures are planned to be integrated
1046 into the mainstream distribution at some future date.
1048 Since Debian has an open development model (i.e., everyone can
1049 participate and follow the development) even the `unstable' and `testing'
1050 distributions are distributed to the Internet through the Debian FTP and
1051 HTTP server network. Thus, if we had called the directory which contains
1052 the release candidate version `testing', then we would have to rename it
1053 to `stable' when the version is released, which would cause all FTP
1054 mirrors to re-retrieve the whole distribution (which is quite large).
1056 On the other hand, if we called the distribution directories
1057 <em>Debian-x.y</em> from the beginning, people would think that Debian
1058 release <em>x.y</em> is available. (This happened in the past, where a
1059 CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development
1060 version. That's the reason why the first official Debian release was
1063 Thus, the names of the distribution directories in the archive are
1064 determined by their code names and not their release status (e.g.,
1065 `slink'). These names stay the same during the development period and
1066 after the release; symbolic links, which can be changed easily,
1067 indicate the currently released stable distribution. That's why the
1068 real distribution directories use the <em>code names</em>, while
1069 symbolic links for <em>stable</em>, <em>testing</em>, and
1070 <em>unstable</em> point to the appropriate release directories.
1073 <sect id="mirrors">Debian mirrors
1075 The various download archives and the web site have several mirrors
1076 available in order to relieve our canonical servers from heavy load.
1077 In fact, some of the canonical servers aren't public — a first tier
1078 of mirrors balances the load instead. That way, users always access
1079 the mirrors and get used to using them, which allows Debian to better
1080 spread its bandwidth requirements over several servers and networks,
1081 and basically makes users avoid hammering on one primary location.
1082 Note that the first tier of mirrors is as up-to-date as it can be since
1083 they update when triggered from the internal sites (we call this
1086 All the information on Debian mirrors, including a list of the available
1087 public FTP/HTTP servers, can be found at <url id="&url-debian-mirrors;">.
1088 This useful page also includes information and tools which can be helpful if
1089 you are interested in setting up your own mirror, either for internal or
1092 Note that mirrors are generally run by third-parties who are
1093 interested in helping Debian. As such, developers generally do not
1094 have accounts on these machines.
1097 <sect id="incoming-system">
1098 <heading>The Incoming system
1100 The Incoming system is responsible for collecting updated packages and
1101 installing them in the Debian archive. It consists of a set of
1102 directories and scripts that are installed both on <tt>&ftp-master-host;</tt>
1103 and <tt>&non-us-host;</tt>.
1105 Packages are uploaded by all the maintainers into a directory called
1106 <file>unchecked</file>. This directory is scanned every 15 minutes by
1107 the <prgn>katie</prgn> script, which verifies the integrity of the uploaded
1108 packages and their cryptographic signatures.
1109 If the package is considered ready to be installed, it
1110 is moved into the <file>accepted</file> directory. If this is the first upload of
1111 the package, it is moved in the <file>new</file> directory, where it waits
1112 for an approval of the ftpmasters. If the package contains files to be installed
1113 "by-hand" it is moved in the <file>byhand</file> directory, where it waits
1114 for a manual installation by the ftpmasters. Otherwise, if any error has been detected,
1115 the package is refused and is moved in the <file>reject</file> directory.
1117 Once the package is accepted the system sends a confirmation
1118 mail to the maintainer, closes all the bugs marked as fixed by the upload
1119 and the auto-builders may start recompiling it. The package is now publicly
1120 accessible at <url id="&url-incoming;"> (there is no
1121 such URL for packages in the non-US archive) until it is really installed
1122 in the Debian archive. This happens only once a day, the package
1123 is then removed from incoming and installed in the pool along with all
1124 the other packages. Once all the other updates (generating new
1125 <file>Packages</file> and <file>Sources</file> index files for example) have been
1126 made, a special script is called to ask all the primary mirrors to update
1129 The archive maintenance software will also send the OpenPGP/GnuPG signed
1130 <file>.changes</file> file that you uploaded to the appropriate mailing
1131 lists. If a package is released with the <tt>Distribution:</tt> set to
1132 `stable', the announcement is sent to &email-debian-changes;.
1133 If a package is released with <tt>Distribution:</tt> set to `unstable'
1134 or `experimental', the announcement will be posted to
1135 &email-debian-devel-changes; instead.
1137 All Debian developers have write access to the <file>unchecked</file>
1138 directory in order to upload their packages, they also have that access
1139 to the <file>reject</file> directory in order to remove their bad uploads
1140 or to move some files back in the <file>unchecked</file> directory. But
1141 all the other directories are only writable by the ftpmasters, that is
1142 why you can not remove an upload once it has been accepted.
1144 <sect1 id="delayed-incoming">Delayed incoming
1146 The <file>unchecked</file> directory has a special <file>DELAYED</file>
1147 subdirectory. It is itself subdivided in nine directories
1148 called <file>1-day</file> to <file>9-day</file>. Packages which are uploaded in
1149 one of those directories will be moved in the real unchecked
1150 directory after the corresponding number of days.
1151 This is done by a script that is run each day and which moves the
1152 packages between the directories. Those which are in "1-day" are
1153 installed in <file>unchecked</file> while the others are moved in the
1154 adjacent directory (for example, a package in <file>5-day</file> will
1155 be moved in <file>4-day</file>). This feature is particularly useful
1156 for people who are doing non-maintainer uploads. Instead of
1157 waiting before uploading a NMU, it is uploaded as soon as it is
1158 ready but in one of those <file>DELAYED/<var>x</var>-day</file> directories.
1159 That leaves the corresponding number of days for the maintainer
1160 to react and upload another fix themselves if they are not
1161 completely satisfied with the NMU. Alternatively they can remove
1164 The use of that delayed feature can be simplified with a bit
1165 of integration with your upload tool. For instance, if you use
1166 <prgn>dupload</prgn> (see <ref id="dupload">), you can add this
1167 snippet to your configuration file:
1169 $delay = ($ENV{DELAY} || 7);
1171 fqdn => "&ftp-master-host;",
1172 login => "yourdebianlogin",
1173 incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
1178 Once you've made that change, <prgn>dupload</prgn> can be used to
1179 easily upload a package in one of the delayed directories:
1180 <example>DELAY=5 dupload --to delayed <changes-file></example>
1184 <sect id="pkg-info">Package information
1187 <sect1 id="pkg-info-web">On the web
1189 Each package has several dedicated web pages.
1190 <tt>http://&packages-host;/<var>package-name</var></tt>
1191 displays each version of the package
1192 available in the various distributions. Each version links to a page
1193 which provides information, including the package description,
1194 the dependencies and package download links.
1196 The bug tracking system tracks bugs for each package.
1197 You can view the bugs of a given package at the URL
1198 <tt>http://&bugs-host;/<var>package-name</var></tt>.
1200 <sect1 id="madison">The <prgn>madison</prgn> utility
1202 <prgn>madison</prgn> is a command-line utility that is available
1203 on both <tt>&ftp-master-host;</tt> and <tt>&non-us-host;</tt>. It
1204 uses a single argument corresponding to a package name. In result
1205 it displays which version of the package is available for each
1206 architecture and distribution combination. An example will explain
1210 $ madison libdbd-mysql-perl
1211 libdbd-mysql-perl | 1.2202-4 | stable | source, alpha, arm, i386, m68k, powerpc, sparc
1212 libdbd-mysql-perl | 1.2216-2 | testing | source, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
1213 libdbd-mysql-perl | 1.2216-2.0.1 | testing | alpha
1214 libdbd-mysql-perl | 1.2219-1 | unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
1217 In this example, you can see that the version in <em>unstable</em> differs from
1218 the version in <em>testing</em> and that there has been a binary-only NMU of the
1219 package for the alpha architecture. Each time the package has been
1220 recompiled on most of the architectures.
1222 <sect id="pkg-tracking-system">The Package Tracking System
1224 The Package Tracking System (PTS) is an email-based tool to track
1225 the activity of a source package. This really means that you can
1226 get the same emails that the package maintainer gets, simply by
1227 subscribing to the package in the PTS.
1229 Each email sent through the PTS is classified under one of
1230 the keywords listed below. This will let you select the mails that
1231 you want to receive.
1233 By default you will get:
1237 All the bug reports and following discussions.
1239 <tag><tt>bts-control</tt>
1241 The email notifications from <email>control@bugs.debian.org</email>
1242 about bug report status changes.
1244 <tag><tt>upload-source</tt>
1246 The email notification from <prgn>katie</prgn> when an uploaded source
1247 package is accepted.
1249 <tag><tt>katie-other</tt>
1251 Other warning and error emails from <prgn>katie</prgn> (such as an
1252 override disparity for the section and/or the priority field).
1254 <tag><tt>default</tt>
1256 Any non-automatic email sent to the PTS by people who wanted to
1257 contact the subscribers of the package. This can be done by sending mail
1258 to <tt><var>sourcepackage</var>@&pts-host;</tt>. In order to prevent spam,
1259 all messages sent to these addresses must contain the <tt>X-PTS-Approved</tt>
1260 header with a non-empty value.
1262 <tag><tt>summary</tt>
1264 (This is a planned expansion.)
1265 The regular summary emails about the package's status (bug statistics,
1266 porting overview, progression in <em>testing</em>, ...).
1270 You can also decide to receive additional information:
1272 <tag><tt>upload-binary</tt>
1274 The email notification from <prgn>katie</prgn> when an uploaded binary
1275 package is accepted. In other words, whenever a build daemon or a porter
1276 uploads your package for another architecture, you can get an email to
1277 track how your package gets recompiled for all architectures.
1281 CVS commit notifications, if the package has a CVS repository and the
1282 maintainer has set up forwarding commit notifications to the PTS.
1286 Translations of descriptions or debconf templates
1287 submitted to the Debian Description Translation Project.
1290 <sect1 id="pts-commands">The PTS email interface
1292 You can control your subscription(s) to the PTS by sending
1293 various commands to <email>pts@qa.debian.org</email>.
1297 <tag><tt>subscribe <sourcepackage> [<email>]</tt>
1299 Subscribes <var>email</var> to communications related to the source package
1300 <var>sourcepackage</var>. Sender address is used if the second argument is
1301 not present. If <var>sourcepackage</var> is not a valid source package,
1302 you'll get a warning. However if it's a valid binary package, the PTS
1303 will subscribe you to the corresponding source package.
1305 <tag><tt>unsubscribe <sourcepackage> [<email>]</tt>
1307 Removes a previous subscription to the source package <var>sourcepackage</var>
1308 using the specified email address or the sender address if the second
1309 argument is left out.
1311 <tag><tt>which [<email>]</tt>
1313 Lists all subscriptions for the sender or the email address optionally
1316 <tag><tt>keyword [<email>]</tt>
1318 Tells you the keywords that you are accepting.
1319 For an explanation of keywords, <qref id="pkg-tracking-system">see
1320 above</qref>. Here's a quick summary:
1322 <item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
1323 <item><tt>bts-control</tt>: reply to mails sent to &email-bts-control;
1324 <item><tt>summary</tt>: automatic summary mails about the state of a package
1325 <item><tt>cvs</tt>: notification of CVS commits
1326 <item><tt>ddtp</tt>: translations of descriptions and debconf templates
1327 <item><tt>upload-source</tt>: announce of a new source upload that
1329 <item><tt>upload-binary</tt>: announce of a new binary-only upload (porting)
1330 <item><tt>katie-other</tt>: other mails from ftpmasters
1331 (override disparity, etc.)
1332 <item><tt>default</tt>: all the other mails (those which aren't "automatic")
1335 <tag><tt>keyword <sourcepackage> [<email>]</tt>
1337 Same as the previous item but for the given source package, since
1338 you may select a different set of keywords for each source package.
1340 <tag><tt>keyword [<email>] {+|-|=} <list of keywords></tt>
1342 Accept (+) or refuse (-) mails classified under the given keyword(s).
1343 Define the list (=) of accepted keywords.
1345 <tag><tt>keyword <sourcepackage> [<email>] {+|-|=} <list of keywords></tt>
1347 Same as previous item but overrides the keywords list for the
1348 indicated source package.
1350 <tag><tt>quit | thanks | --</tt>
1352 Stops processing commands. All following lines are ignored by
1356 <sect1 id="pts-mail-filtering">Filtering PTS mails
1358 Once you are subscribed to a package, you will get the mails sent to
1359 <tt><var>sourcepackage</var>@packages.qa.debian.org</tt>. Those mails
1360 have special headers appended to let you filter them in a special
1361 mailbox (e.g. with <prgn>procmail</prgn>). The added headers are
1362 <tt>X-Loop</tt>, <tt>X-PTS-Package</tt>, <tt>X-PTS-Keyword</tt> and
1363 <tt>X-Unsubscribe</tt>.
1365 Here is an example of added headers for a source upload notification
1366 on the <package>dpkg</package> package:
1368 X-Loop: dpkg@&pts-host;
1370 X-PTS-Keyword: upload-source
1371 X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org
1374 <sect1 id="pts-cvs-commit">Forwarding CVS commits in the PTS
1376 If you use a publicly accessible CVS repository for maintaining
1377 your Debian package you may want to forward the commit notification
1378 to the PTS so that the subscribers (and possible co-maintainers) can
1379 closely follow the package's evolution.
1381 Once you set up the CVS repository to generate commit notifications,
1382 you just have to make sure it sends a copy of those mails
1383 to <tt><var>sourcepackage</var>_cvs@&pts-host;</tt>. Only the people
1384 who accept the <em>cvs</em> keyword will receive these notifications.
1386 <sect1 id="pts-web">The PTS web interface
1388 The PTS has a web interface at <url id="http://&pts-host;/"> that puts
1389 together a lot of information about each source package. It features many useful
1390 links (BTS, QA stats, contact information, DDTP translation status,
1391 buildd logs) and gathers much more information from various places
1392 (30 latest changelog entries, testing status, ...). It's a very useful
1393 tool if you want to know what's going on with a specific source
1394 package. Furthermore there's a form that allows easy subscription to
1397 You can jump directly to the web page concerning a specific source package
1398 with a URL like <tt>http://&pts-host;/<var>sourcepackage</var></tt>.
1400 This web interface has been designed like a portal for the development of
1401 packages: you can add custom content on your packages' pages. You can
1402 add "static information" (news items that are meant to stay available
1403 indefinitely) and news items in the "latest news" section.
1405 Static news items can be used to indicate:
1407 <item>the availability of a project hosted on <qref id="alioth">Alioth</qref> for co-maintaining the package
1408 <item>a link to the upstream web site
1409 <item>a link to the upstream bug tracker
1410 <item>the existence of an IRC channel dedicated to the software
1411 <item>any other available resource that could be useful in the maintenance of the package
1413 Usual news items may be used to announce that:
1415 <item>beta packages are available for testing
1416 <item>final packages are expected for next week
1417 <item>the packaging is about to be redone from scratch
1418 <item>backports are available
1419 <item>the maintainer is on vacation (if they wish to publish this information)
1420 <item>a NMU is being worked on
1421 <item>something important will affect the package
1424 Both kinds of news are generated in a similar manner: you just have to send
1425 an email either to <email>pts-static-news@qa.debian.org</email> or to
1426 <email>pts-news@qa.debian.org</email>. The mail should indicate which
1427 package is concerned by having the name of the source package in a
1428 <tt>X-PTS-Package</tt> mail header or in a <tt>Package</tt> pseudo-header (like the
1429 BTS reports). If a URL is available in the <tt>X-PTS-Url</tt> mail header or in
1430 the <tt>Url</tt> pseudo-header, then the result is a link to that URL instead
1431 of a complete news item.
1433 Here are a few examples of valid mails used to generate news items in
1434 the PTS. The first one adds a link to the cvsweb interface of debian-cd
1435 in the "Static information" section:
1437 From: Raphael Hertzog <hertzog@debian.org>
1438 To: pts-static-news@qa.debian.org
1439 Subject: Browse debian-cd CVS repository with cvsweb
1442 Url: http://cvs.debian.org/debian-cd/
1445 The second one is an announcement sent to a mailing list which is also sent
1446 to the PTS so that it is published on the PTS web page of the package. Note the
1447 use of the BCC field to avoid answers sent to the PTS by mistake.
1449 From: Raphael Hertzog <hertzog@debian.org>
1450 To: debian-gtk-gnome@lists.debian.org
1451 Bcc: pts-news@qa.debian.org
1452 Subject: Galeon 2.0 backported for woody
1453 X-PTS-Package: galeon
1457 I'm glad to announce that galeon has been backported for woody. You'll find
1462 Think twice before adding a news item to the PTS because you won't be able
1463 to remove it later and you wan't be able to edit it either. The only thing
1464 that you can do is send a second news item that will deprecate the
1465 information contained in the previous one.
1467 <sect id="ddpo">Developer's packages overview
1469 A QA (quality assurance) web portal is available at <url
1470 id="&url-ddpo;"> which displays a table listing all the packages
1471 of a single developer (including those where the party is listed as
1472 a co-maintainer). The table gives a good summary about the developer's
1473 packages: number of bugs by severity, list of available versions in each
1474 distribution, testing status and much more including links to any other
1477 It is a good idea to look up your own data regularly so that
1478 you don't forget any open bug, and so that you don't forget which
1479 packages are under your responsibility.
1481 <sect id="alioth">Debian *Forge: Alioth
1483 Alioth is a fairly new Debian service, based on a slightly modified version
1484 of the GForge software (which evolved from SourceForge). This software
1485 offers developers access to easy-to-use tools such as bug trackers, patch
1486 manager, project/task managers, file hosting services, mailing lists, CVS
1487 repositories etc. All these tools are managed via a web interface.
1489 It is intended to provide facilities to free software projects backed or led
1490 by Debian, facilitate contributions from external developers to projects
1491 started by Debian, and help projects whose goals are the promotion of Debian
1494 For more information please visit <url id="&url-alioth;">.
1497 <chapt id="pkgs">Managing Packages
1499 This chapter contains information related to creating, uploading,
1500 maintaining, and porting packages.
1503 <sect id="newpackage">New packages
1505 If you want to create a new package for the Debian distribution, you
1506 should first check the <url id="&url-wnpp;" name="Work-Needing and
1507 Prospective Packages (WNPP)"> list. Checking the WNPP list ensures that
1508 no one is already working on packaging that software, and that effort is
1509 not duplicated. Read the <url id="&url-wnpp;" name="WNPP web pages"> for
1512 Assuming no one else is already working on your prospective package,
1513 you must then submit a bug report (<ref id="submit-bug">) against the
1514 pseudo-package <package>wnpp</package>
1515 describing your plan to create a new package, including, but not
1516 limiting yourself to, a description of the package, the license of the
1517 prospective package and the current URL where it can be downloaded
1520 You should set the subject of the bug to ``ITP: <var>foo</var>
1521 -- <var>short description</var>'', substituting the name of the new
1522 package for <var>foo</var>. The severity of the bug report must be set
1523 to <em>wishlist</em>. If you feel it's necessary, send a copy to
1524 &email-debian-devel; by putting the address in the <tt>X-Debbugs-CC:</tt> header
1525 of the message (no, don't use <tt>CC:</tt>, because that way the message's subject
1526 won't indicate the bug number).
1528 Please include a <tt>Closes: bug#<var>nnnnn</var></tt> entry on the
1529 changelog of the new package in order for the bug report to be
1530 automatically closed once the new package is installed on the archive
1531 (<ref id="upload-bugfix">).
1533 There are a number of reasons why we ask maintainers to announce their
1537 It helps the (potentially new) maintainer to tap into the experience
1538 of people on the list, and lets them know if anyone else is working
1541 It lets other people thinking about working on the package know that
1542 there already is a volunteer, so efforts may be shared.
1544 It lets the rest of the maintainers know more about the package than
1545 the one line description and the usual changelog entry ``Initial release''
1546 that gets posted to <tt>debian-devel-changes</tt>.
1548 It is helpful to the people who live off unstable (and form our first
1549 line of testers). We should encourage these people.
1551 The announcements give maintainers and other interested parties a
1552 better feel of what is going on, and what is new, in the project.
1556 <sect id="changelog-entries">Recording changes in the package
1558 Changes that you make to the package need to be recorded in the
1559 <file>debian/changelog</file>. These changes should provide a concise
1560 description of what was changed, why (if it's in doubt), and note if
1561 any bugs were closed. They also record when the package was
1562 completed. This file will be installed in
1563 <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>, or
1564 <file>/usr/share/doc/<var>package</var>/changelog.gz</file> for native
1567 The <file>debian/changelog</file> file conforms to a certain structure,
1568 with a number of different fields. One field of note, the
1569 <em>distribution</em>, is described in <ref id="distribution">. More
1570 information about the structure of this file can be found in
1571 the Debian Policy section titled "<file>debian/changelog</file>".
1573 Changelog entries can be used to automatically close Debian bugs when
1574 the package is installed into the archive. See <ref
1575 id="upload-bugfix">.
1577 It is conventional that the changelog entry notating of a package that
1578 contains a new upstream version of the software looks like this:
1580 * new upstream version
1583 There are tools to help you create entries and finalize the
1584 <file>changelog</file> for release — see <ref id="devscripts">
1585 and <ref id="dpkg-dev-el">.
1587 See also <ref id="bpp-debian-changelog">.
1590 <sect id="sanitycheck">Testing the package
1592 Before you upload your package, you should do basic testing on it. At
1593 a minimum, you should try the following activities (you'll need to
1594 have an older version of the same Debian package around):
1597 Install the package and make sure the software works, or upgrade the
1598 package from an older version to your new version if a Debian package
1599 for it already exists.
1601 Run <prgn>lintian</prgn> over the package. You can run
1602 <prgn>lintian</prgn> as follows: <tt>lintian -v
1603 <var>package-version</var>.changes</tt>. This will check the source
1604 package as well as the binary package. If you don't understand the
1605 output that <prgn>lintian</prgn> generates, try adding the <tt>-i</tt>
1606 switch, which will cause <prgn>lintian</prgn> to output a very verbose
1607 description of the problem.
1609 Normally, a package should <em>not</em> be uploaded if it causes lintian
1610 to emit errors (they will start with <tt>E</tt>).
1612 For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
1614 Optionally run <ref id="debdiff"> to analyze changes from an older version,
1617 Downgrade the package to the previous version (if one exists) — this
1618 tests the <file>postrm</file> and <file>prerm</file> scripts.
1620 Remove the package, then reinstall it.
1624 <sect id="sourcelayout">Layout of the source package
1626 There are two types of Debian source packages:
1628 <item>the so-called <em>native</em> packages, where there is no
1629 distinction between the original sources and the patches
1631 <item>the (more common) packages where there's an original source
1632 tarball file accompanied by another file that contains the
1633 patches applied for Debian
1636 For the native packages, the source package includes a Debian source control
1637 file (<tt>.dsc</tt>) and the source tarball (<tt>.tar.gz</tt>). A source
1638 package of a non-native package includes a Debian source control file, the
1639 original source tarball (<tt>.orig.tar.gz</tt>) and the Debian patches
1640 (<tt>.diff.gz</tt>).
1642 Whether a package is native or not is determined when it is built by
1643 <manref name="dpkg-buildpackage" section="1">. The rest of this section
1644 relates only to non-native packages.
1646 The first time a version is uploaded which corresponds to a particular
1647 upstream version, the original source tar file should be uploaded and
1648 included in the <file>.changes</file> file. Subsequently, this very same
1649 tar file should be used to build the new diffs and <file>.dsc</file>
1650 files, and will not need to be re-uploaded.
1652 By default, <prgn>dpkg-genchanges</prgn> and
1653 <prgn>dpkg-buildpackage</prgn> will include the original source tar
1654 file if and only if the Debian revision part of the source version
1655 number is 0 or 1, indicating a new upstream version. This behavior
1656 may be modified by using <tt>-sa</tt> to always include it or
1657 <tt>-sd</tt> to always leave it out.
1659 If no original source is included in the upload, the original
1660 source tar-file used by <prgn>dpkg-source</prgn> when constructing the
1661 <file>.dsc</file> file and diff to be uploaded <em>must</em> be
1662 byte-for-byte identical with the one already in the archive.
1665 <sect id="distribution">Picking a distribution
1667 Each upload needs to specify which distribution the package is intended
1668 for. The package build process extracts this information from the first
1669 line of the <file>debian/changelog</file> file and places it in the
1670 <tt>Distribution</tt> field of the <tt>.changes</tt> file.
1672 There are several possible values for this field: `stable', `unstable',
1673 `testing-proposed-updates' and `experimental'. Normally, packages are
1674 uploaded into <em>unstable</em>.
1676 Actually, there are two other possible distributions: `stable-security' and
1677 `testing-security', but read <ref id="bug-security"> for more information on
1680 It is technically possible to upload a package into several distributions
1681 at the same time but it usually doesn't make sense to use that feature
1682 because the dependencies of the package may vary with the distribution.
1683 In particular, it never makes sense to combine the <em>experimental</em>
1684 distribution with anything else (see <ref id="experimental">).
1686 <sect1 id="upload-stable">
1687 <heading>Special case: uploads to the <em>stable</em> distribution</heading>
1689 Uploading to <em>stable</em> means that the package will be placed into the
1690 <file>stable-proposed-updates</file> directory of the Debian archive for further
1691 testing before it is actually included in <em>stable</em>.
1693 Extra care should be taken when uploading to <em>stable</em>. Basically, a
1694 package should only be uploaded to stable if one of the following happens:
1696 <item>a truly critical functionality problem
1697 <item>the package becomes uninstallable
1698 <item>a released architecture lacks the package
1701 In the past, uploads to <em>stable</em> were used to address security
1702 problems as well. However, this practice is deprecated, as uploads
1703 used for Debian security advisories are automatically copied to the
1704 appropriate <file>proposed-updates</file> archive when the advisory is
1705 released. See <ref id="bug-security"> for detailed information on
1706 handling security problems.
1708 It is discouraged to change anything else in the package that isn't
1709 important, because even trivial fixes can cause bugs later on.
1711 Packages uploaded to <em>stable</em> need to be compiled on systems running
1712 <em>stable</em>, so that their dependencies are limited to the libraries
1713 (and other packages) available in <em>stable</em>; for example, a package
1714 uploaded to <em>stable</em> that depends on a library package that only
1715 exists in unstable will be rejected. Making changes to dependencies of other
1716 packages (by messing with <tt>Provides</tt> or shlibs files), possibly making
1717 those other packages uninstallable, is strongly discouraged.
1719 The Release Team (which can be reached at &email-debian-release;) will
1720 regularly evaluate the uploads in <em>stable-proposed-updates</em> and decide if
1721 your package can be included in <em>stable</em>. Please be clear (and
1722 verbose, if necessary) in your changelog entries for uploads to
1723 <em>stable</em>, because otherwise the package won't be considered for
1726 <sect1 id="upload-t-p-u">
1727 <heading>Special case: uploads to <em>testing-proposed-updates</em></heading>
1729 The testing distribution is fed with packages from unstable according to the rules
1730 explained in <ref id="testing">. However, the release manager may stop the testing
1731 scripts when he wants to freeze the distribution. In that case, you may want to
1732 upload to <em>testing-proposed-updates</em> to provide fixed packages during the freeze.
1734 Keep in mind that packages uploaded there are not automatically processed, they
1735 have to go through the hands of the release manager. So you'd better have a good
1736 reason to upload there. In order to know what a good reason is in the
1737 release manager's eyes, you should read the instructions that he regularly
1738 gives on &email-debian-devel-announce;.
1740 You should not upload to <em>testing-proposed-updates</em> when you can update your
1741 packages through <em>unstable</em>. If you can't (for example because you have a
1742 newer development version in unstable), you may use it but it is recommended to ask
1743 the authorization of the release manager before.
1746 <sect id="upload">Uploading a package
1748 <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
1750 To upload a package, you need a personal account on
1751 <ftpsite>&ftp-master-host;</ftpsite>, which you should have as an
1752 official maintainer. If you use <prgn>scp</prgn> or <prgn>rsync</prgn>
1753 to transfer the files, place them into &us-upload-dir;;
1754 if you use anonymous FTP to upload, place them into
1757 If you want to use feature described in <ref id="delayed-incoming">,
1758 you'll have to upload to <tt>ftp-master</tt>. It is the only upload
1759 point that supports delayed incoming.
1761 Please note that you should transfer
1762 the changes file last. Otherwise, your upload may be rejected because the
1763 archive maintenance software will parse the changes file and see that not
1764 all files have been uploaded. If you don't want to bother with transferring
1765 the changes file last, you can simply copy your files to a temporary
1766 directory on <tt>ftp-master</tt> and then move them to
1769 <em>Note:</em> Do not upload to <tt>ftp-master</tt> cryptographic
1770 packages which belong to <em>contrib</em> or <em>non-free</em>. Uploads of
1771 such software should go to <tt>non-us</tt> (see <ref
1772 id="upload-non-us">). Furthermore packages containing code that is
1773 patent-restricted by the United States government can not be uploaded to
1774 <tt>ftp-master</tt>; depending on the case they may still be uploaded to
1775 <file>non-US/non-free</file> (it's in non-free because of distribution issues
1776 and not because of the license of the software). If you can't upload it to
1777 <tt>ftp-master</tt>, then neither can you upload it to the overseas upload
1778 queues on <tt>chiark</tt> or <tt>erlangen</tt>. If you are not sure
1779 whether U.S. patent controls or cryptographic controls apply to your
1780 package, post a message to &email-debian-devel; and ask.
1782 You may also find the Debian packages <ref id="dupload"> or
1783 <ref id="dput"> useful
1784 when uploading packages. These handy programs help automate the
1785 process of uploading packages into Debian.
1787 After uploading your package, you can check how the archive
1788 maintenance software will process it by running <prgn>dinstall</prgn>
1789 on your changes file:
1790 <example>dinstall -n foo.changes</example>
1792 Note that <prgn>dput</prgn> can do this for you automatically.
1794 <sect1 id="upload-non-us">Uploading to <tt>non-US</tt>
1796 As discussed above, export controlled software should not be uploaded
1797 to <tt>ftp-master</tt>. Instead, upload the package to
1798 <ftpsite>non-us.debian.org</ftpsite>, placing the files in
1799 &non-us-upload-dir; (again, both <ref id="dupload"> and <ref
1800 id="dput"> can do this for you if invoked properly). By default,
1801 you can use the same account/password that works on
1802 <tt>ftp-master</tt>. If you use anonymous FTP to upload, place the
1803 files into &upload-queue;.
1805 You can check your upload the same way it's done on <tt>ftp-master</tt>,
1807 <example>dinstall -n foo.changes</example>
1809 Note that U.S. residents or citizens are subject to restrictions on
1810 export of cryptographic software. As of this writing, U.S. citizens
1811 are allowed to export some cryptographic software, subject to
1812 notification rules by the U.S. Department of Commerce. However, this
1813 restriction has been waived for software which is already available
1814 outside the U.S. Therefore, any cryptographic software which belongs
1815 in the <em>main</em> section of the Debian archive and does not depend
1816 on any package outside of <em>main</em> (e.g., does not depend on
1817 anything in <em>non-US/main</em>) can be uploaded to <tt>ftp-master</tt>
1818 or its queues, described above.
1820 Debian policy does not prevent upload to non-US by U.S. residents or
1821 citizens, but care should be taken in doing so. It is recommended that
1822 developers take all necessary steps to ensure that they are not
1823 breaking current US law by doing an upload to non-US, <em>including
1824 consulting a lawyer</em>.
1826 For packages in <em>non-US/main</em>, <em>non-US/contrib</em>,
1827 developers should at least follow the <url id="&url-u.s.-export;"
1828 name="procedure outlined by the US Government">. Maintainers of
1829 <em>non-US/non-free</em> packages should further consult the <url
1830 id="&url-notification-of-export;" name="rules on notification of
1831 export"> of non-free software.
1833 This section is for information only and does not constitute legal
1834 advice. Again, it is strongly recommended that U.S. citizens and
1835 residents consult a lawyer before doing uploads to non-US.
1838 <sect1>Uploads via <tt>chiark</tt>
1840 If you have a slow network connection to <tt>ftp-master</tt>, there are
1841 alternatives. One is to upload files to <file>Incoming</file> via a
1842 upload queue in Europe on <tt>chiark</tt>. For details connect to
1843 <url id="&url-chiark-readme;">.
1845 <em>Note:</em> Do not upload packages containing software that is
1846 export-controlled by the United States government to the queue on
1847 <tt>chiark</tt>. Since this upload queue goes to <tt>ftp-master</tt>, the
1848 prescription found in <ref id="upload-ftp-master"> applies here as well.
1850 The program <prgn>dupload</prgn> comes with support for uploading to
1851 <tt>chiark</tt>; please refer to the documentation that comes with the
1852 program for details.
1855 <sect1>Uploads via <tt>erlangen</tt>
1857 Another upload queue is available in Germany: just upload the files
1858 via anonymous FTP to <url id="&url-upload-erlangen;">.
1860 The upload must be a complete Debian upload, as you would put it into
1861 <tt>ftp-master</tt>'s <file>Incoming</file>, i.e., a <file>.changes</file> files
1862 along with the other files mentioned in the <file>.changes</file>. The
1863 queue daemon also checks that the <file>.changes</file> is correctly
1864 signed with GnuPG or OpenPGP by a Debian developer, so that no bogus files can find
1865 their way to <tt>ftp-master</tt> via this queue. Please also make sure that
1866 the <tt>Maintainer</tt> field in the <file>.changes</file> contains
1867 <em>your</em> e-mail address. The address found there is used for all
1868 replies, just as on <tt>ftp-master</tt>.
1870 There's no need to move your files into a second directory after the
1871 upload, as on <tt>chiark</tt>. And, in any case, you should get a
1872 mail reply from the queue daemon explaining what happened to your
1873 upload. Hopefully it should have been moved to <tt>ftp-master</tt>, but in
1874 case of errors you're notified, too.
1876 <em>Note:</em> Do not upload packages containing software that is
1877 export-controlled by the United States government to the queue on
1878 <tt>erlangen</tt>. Since this upload queue goes to <tt>ftp-master</tt>, the
1879 prescription found in <ref id="upload-ftp-master"> applies here as well.
1881 The program <prgn>dupload</prgn> comes with support for uploading to
1882 <tt>erlangen</tt>; please refer to the documentation that comes with
1883 the program for details.
1886 <sect1>Other upload queues
1888 Another upload queue is available which is based in the US, and is a
1889 good backup when there are problems reaching <tt>ftp-master</tt>. You can
1890 upload files, just as in <tt>erlangen</tt>, to <url
1891 id="&url-upload-samosa;">.
1893 An upload queue is available in Japan: just upload the files via
1894 anonymous FTP to <url id="&url-upload-jp;">.
1897 <sect1 id="upload-notification">
1898 <heading>Notification that a new package has been installed</heading>
1900 The Debian archive maintainers are responsible for handling package
1901 uploads. For the most part, uploads are automatically handled on a
1902 daily basis by the archive maintenance tools, <prgn>katie</prgn>.
1903 Specifically, updates to existing packages to
1904 the `unstable' distribution are handled automatically. In other cases,
1905 notably new packages, placing the uploaded package into the
1906 distribution is handled manually. When uploads are handled manually,
1907 the change to the archive may take up to a month to occur. Please be
1910 In any case, you will receive an email notification indicating that the
1911 package has been added to the archive, which also indicates which bugs will
1912 be closed by the upload. Please examine this notification carefully,
1913 checking if any bugs you meant to close didn't get triggered.
1915 The installation notification also includes information on what
1916 section the package was inserted into. If there is a disparity, you
1917 will receive a separate email notifying you of that. Read on below.
1919 Note also that if you upload via queues, the queue daemon software will
1920 also send you a notification by email.
1922 <sect id="override-file">Determining section and priority of a package
1924 The <file>debian/control</file> file's <tt>Section</tt> and
1925 <tt>Priority</tt> fields do not actually specify where the file will
1926 be placed in the archive, nor its priority. In order to retain the
1927 overall integrity of the archive, it is the archive maintainers who
1928 have control over these fields. The values in the
1929 <file>debian/control</file> file are actually just hints.
1931 The archive maintainers keep track of the canonical sections and
1932 priorities for packages in the <em>override file</em>. If there is a
1933 disparity between the <em>override file</em> and the package's fields
1934 as indicated in <file>debian/control</file>, then you will receive an
1935 email noting the divergence when the package is installed into the
1936 archive. You can either correct your <file>debian/control</file> file
1937 for your next upload, or else you may wish to make a change in the
1938 <em>override file</em>.
1940 To alter the actual section that a package is put in, you need to
1941 first make sure that the <file>debian/control</file> in your package
1942 is accurate. Next, send an email &email-override; or submit a bug
1943 against <package>ftp.debian.org</package> requesting that the section
1944 or priority for your package be changed from the old section or
1945 priority to the new one. Be sure to explain your reasoning.
1947 For more information about <em>override files</em>, see <manref
1948 name="dpkg-scanpackages" section="8"> and
1949 <url id="&url-bts-devel;#maintincorrect">.
1951 Note also that the term "section" is used for the separation of packages
1952 according to their licensing, e.g. <em>main</em>, <em>contrib</em> and
1953 <em>non-free</em>. This is described in another section, <ref id="archive">.
1956 <sect id="bug-handling">Handling bugs
1958 Every developer has to be able to work with the Debian <url name="bug
1959 tracking system" id="&url-bts;">. This includes knowing how to file bug
1960 reports properly (see <ref id="submit-bug">), how to update them and
1961 reorder them, and how to process and close them.
1963 The bug tracking system's features interesting to developers are described
1964 in the <url id="&url-bts-devel;" name="BTS documentation for developers">.
1965 This includes closing bugs, sending followup messages, assigning severities
1966 and tags, marking bugs as forwarded and other issues.
1968 Operations such as reassigning bugs to other packages, merging separate
1969 bug reports about the same issue, or reopening bugs when they are
1970 prematurely closed, are handled using the so-called control mail server.
1971 All of the commands available in this server are described in the
1972 <url id="&url-bts-control;" name="BTS control server documentation">.
1974 <sect1 id="bug-monitoring">Monitoring bugs
1976 If you want to be a good maintainer, you should periodically check the
1977 <url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
1978 packages. The BTS contains all the open bugs against your packages.
1979 You can check them by browsing this page:
1980 <tt>http://&bugs-host;/<var>yourlogin</var>@debian.org</tt>.
1982 Maintainers interact with the BTS via email addresses at
1983 <tt>&bugs-host;</tt>. Documentation on available commands can be
1984 found at <url id="&url-bts;">, or, if you have installed the
1985 <package>doc-debian</package> package, you can look at the local files
1988 Some find it useful to get periodic reports on open bugs. You can add
1989 a cron job such as the following if you want to get a weekly email
1990 outlining all the open bugs against your packages:
1992 # ask for weekly reports of bugs in my packages
1995 Replace <var>address</var> with your official Debian
1998 <sect1 id="bug-answering">Responding to bugs
2000 When responding to bugs, make sure that any discussion you have about
2001 bugs is sent both to the original submitter of the bug, and to the bug
2002 itself (e.g., <email>123@&bugs-host;</email>). If you're writing a new
2003 mail and you don't remember the submitter email address, you can
2004 use the <email>123-submitter@&bugs-host;</email> email to
2005 contact the submitter <em>and</em> to record your mail within the
2006 bug log (that means you don't need to send a copy of the mail to
2007 <email>123@&bugs-host;</email>).
2009 If you get a bug which mentions "FTBFS", that means "Fails to build
2010 from source". Porters frequently use this acronym.
2012 Once you've dealt with a bug report (e.g. fixed it), mark it as
2013 <em>done</em> (close it) by sending an explanation message to
2014 <email>123-done@&bugs-host;</email>. If you're fixing a bug by
2015 changing and uploading the package, you can automate bug closing as
2016 described in <ref id="upload-bugfix">.
2018 You should <em>never</em> close bugs via the bug server <tt>close</tt>
2019 command sent to &email-bts-control;. If you do so, the original
2020 submitter will not receive any information about why the bug was
2023 <sect1 id="bug-housekeeping">Bug housekeeping
2025 As a package maintainer, you will often find bugs in other packages or
2026 have bugs reported against your packages which are actually bugs in
2027 other packages. The bug tracking system's features interesting to developers
2028 are described in the <url id="&url-bts-devel;" name="BTS documentation for
2029 Debian developers">. Operations such as reassigning, merging, and tagging
2030 bug reports are described in the <url id="&url-bts-control;" name="BTS
2031 control server documentation">. This section contains
2032 some guidelines for managing your own bugs, based on the collective
2033 Debian developer experience.
2035 Filing bugs for problems that you find in other packages is one of
2036 the "civic obligations" of maintainership, see <ref id="submit-bug">
2037 for details. However, handling the bugs in your own packages is
2038 even more important.
2040 Here's a list of steps that you may follow to handle a bug report:
2043 Decide whether the report corresponds to a real bug or not. Sometimes
2044 users are just calling a program in the wrong way because they haven't
2045 read the documentation. If you diagnose this, just close the bug with
2046 enough information to let the user correct his problem (give pointers
2047 to the good documentation and so on). If the same report comes up
2048 again and again you may ask yourself if the documentation is good
2049 enough or if the program shouldn't detect its misuse in order to
2050 give an informative error message. This is an issue that may need
2051 to be brought to the upstream author.
2053 If the bug submitter disagree with your decision to close the bug,
2054 they may reopen it until you find an agreement on how to handle it.
2055 If you don't find any, you may want to tag the bug <tt>wontfix</tt>
2056 to let people know that the bug exists but that it won't be corrected.
2057 If this situation is unacceptable, you (or the submitter) may want to
2058 require a decision of the technical committee by reassigning the bug
2059 to <package>tech-ctte</package> (you may use the clone command of
2060 the BTS if you wish to keep it reported against your package). Before
2061 doing so, please read the <url id="&url-tech-ctte;" name="recommended procedure">.
2063 If the bug is real but it's caused by another package, just reassign
2064 the bug the right package. If you don't know which package it should
2065 be reassigned to, you may either ask for help on &email-debian-devel; or
2066 reassign it to <package>debian-policy</package> to let them decide which
2067 package is in fault.
2069 Sometimes you also have to adjust the severity of the bug so that it
2070 matches our definition of the severity. That's because people tend to
2071 inflate the severity of bugs to make sure their bugs are fixed quickly.
2072 Some bugs may even be dropped to wishlist severity when the requested
2073 change is just cosmetic.
2075 The bug submitter may have forgotten to provide some information, in that
2076 case you have to ask him the information required. You may use the
2077 <tt>moreinfo</tt> tag to mark the bug as such. Moreover if you can't
2078 reproduce the bug, you tag it <tt>unreproducible</tt>. Anyone who
2079 can reproduce the bug is then invited to provide more information
2080 on how to reproduce it. After a few months, if this information has not
2081 been sent by someone, the bug may be closed.
2083 If the bug is related to the packaging, you just fix it. If you are not
2084 able to fix it yourself, then tag the bug as <tt>help</tt>. You can
2085 also ask for help on &email-debian-devel; or &email-debian-qa;. If it's an
2086 upstream problem, you have to forward it to the upstream author.
2087 Forwarding a bug is not enough, you have to check at each release if
2088 the bug has been fixed or not. If it has, you just close it, otherwise
2089 you have to remind the author about it. If you have the required skills
2090 you can prepare a patch that fixes the bug and that you send at the
2091 same time to the author. Make sure to send the patch in the BTS and to
2092 tag the bug as <tt>patch</tt>.
2094 If you have fixed a bug in your local copy, or if a fix has been
2095 committed to the CVS repository, you may tag the bug as
2096 <tt>pending</tt> to let people know that the bug is corrected and that
2097 it will be closed with the next upload (add the <tt>closes:</tt> in
2098 the <file>changelog</file>). This is particularly useful if you
2099 are several developers working on the same package.
2101 Once a corrected package is available in the <em>unstable</em>
2102 distribution, you can close the bug. This can be done automatically,
2103 read <ref id="upload-bugfix">.
2106 <sect1 id="upload-bugfix">When bugs are closed by new uploads
2108 As bugs and problems are fixed your packages, it is your
2109 responsibility as the package maintainer to close the bug. However,
2110 you should not close the bug until the package which fixes the bug has
2111 been accepted into the Debian archive. Therefore, once you get
2112 notification that your updated package has been installed into the
2113 archive, you can and should close the bug in the BTS.
2115 However, it's possible to avoid having to manually close bugs after the
2116 upload — just list the fixed bugs in your <file>debian/changelog</file>
2117 file, following a certain syntax, and the archive maintenance software
2118 will close the bugs for you. For example:
2121 acme-cannon (3.1415) unstable; urgency=low
2123 * Frobbed with options (closes: Bug#98339)
2124 * Added safety to prevent operator dismemberment, closes: bug#98765,
2126 * Added man page. Closes: #98725.
2129 Technically speaking, the following Perl regular expression describes
2130 how bug closing changelogs are identified:
2132 /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
2135 We prefer the <tt>closes: #<var>XXX</var></tt> syntax, as it is the
2136 most concise entry and the easiest to integrate with the text of the
2137 <file>changelog</file>.
2139 If you happen to mistype a bug number or forget a bug in the changelog
2140 entries, don't hesitate to undo any damage the error caused. To reopen
2141 wrongly closed bugs, send an <tt>reopen <var>XXX</var></tt> command to
2142 the bug tracking system's control address, &email-bts-control;. To
2143 close any remaining bugs that were fixed by your upload, email the
2144 <file>.changes</file> file to <email>XXX-done@&bugs-host;</email>,
2145 where <var>XXX</var> is your bug number.
2147 Bear in mind that it is not obligatory to close bugs using the
2148 changelog as described above. If you simply want to close bugs that
2149 don't have anything to do with an upload you made, do it by emailing
2150 an explanation to <email>XXX-done@&bugs-host;</email>. Do
2151 <strong>not</strong> close bugs in the changelog entry of a version if
2152 the changes in that version of the package doesn't have any bearing on
2155 For general information on how to write your changelog entries, see
2156 <ref id="bpp-debian-changelog">.
2159 <sect1 id="bug-security">Handling security-related bugs
2161 Due to their sensitive nature, security-related bugs must be handled
2162 carefully. The Debian Security Team exists to coordinate this
2163 activity, keeping track of outstanding security problems, helping
2164 maintainers with security problems or fix them themselves, sending
2165 security advisories, and maintaining security.debian.org.
2167 <!-- information about the security database goes here once it's ready -->
2171 When you become aware of a security-related bug in a Debian package,
2172 whether or not you are the maintainer, collect pertinent information
2173 about the problem, and promptly contact the security team at
2174 &email-security-team; as soon as possible. Useful information
2175 includes, for example:
2178 <item>What versions of the package are known to be affected by the
2179 bug. Check each version that is present in a supported Debian
2180 release, as well as testing and unstable.
2182 <item>The nature of the fix, if any is available (patches are
2185 <item>Any fixed packages that you have prepared yourself (send only
2186 the <tt>.diff.gz</tt> and <tt>.dsc</tt> files and read <ref
2187 id="bug-security-building"> first)
2189 <item>Any assistance you can provide to help with testing (exploits,
2190 regression testing, etc.)
2192 <item>Any information needed for the advisory (see <ref
2193 id="bug-security-advisories">)
2197 <sect2 id="bug-security-confidentiality">Confidentiality
2199 Unlike most other activities within Debian, information about security
2200 issues must sometimes be kept private for a time.
2201 This allows software distributors to coordinate their disclosure in
2202 order to minimize their users' exposure. Whether this is the
2203 case depends on the nature of the problem and corresponding fix, and
2204 whether it is already a matter of public knowledge.
2207 There are a few ways a developer can learn of a security problem:
2210 <item>he notices it on a public forum (mailing list, web site, etc.)
2211 <item>someone files a bug report
2212 <item>someone informs him via private email
2215 In the first two cases, the information is public and it is important
2216 to have a fix as soon as possible. In the last case, however, it
2217 might not be public information. In that case there are a few
2218 possible options for dealing with the problem:
2221 <item>If the security exposure is minor, there is sometimes no need
2222 to keep the problem a secret and a fix should be made and released.
2224 <item>If the problem is severe, it is preferable to share the
2226 other vendors and coordinate a release. The security team keeps
2227 contacts with the various organizations and individuals and can take
2232 In all cases if the person who reports the problem asks that it not
2233 be disclosed, such requests should be honored, with the obvious
2234 exception of informing the security team in order that a fix may be
2235 produced for a stable release of Debian. When sending confidential
2236 information to the security team, be sure to mention this fact.
2239 Please note that if secrecy is needed you may not upload a fix to
2240 unstable (or anywhere else, such as a public CVS repository). It is
2241 not sufficient to obfuscate the details of the change, as the code
2242 itself is public, and can (and will) be examined by the general public.
2245 There are two reasons for releasing information even though secrecy is
2246 requested: the problem has been known for a while, or that the problem
2247 or exploit has become public.
2249 <sect2 id="bug-security-advisories">Security Advisories
2251 Security advisories are only issued for the current, released stable
2252 distribution, and <em>not</em> for testing or unstable. When released,
2254 are sent to the &email-debian-security-announce;
2256 mailing list and posted on <url
2257 id="&url-debian-security-advisories;" name="the security web page">.
2258 Security advisories are written and posted by the security
2259 team. However they certainly do not mind if a
2260 maintainer can supply some of the information for them, or write part
2261 of the text. Information that should be in an advisory includes:
2264 <item>A description of the problem and its scope, including:
2266 <item>The type of problem (privilege escalation, denial of
2268 <item>What privileges may be gained, and by whom (if any)
2269 <item>How it can be exploited
2270 <item>Whether it is remotely or locally exploitable
2271 <item>How the problem was fixed
2274 This information allows users to assess the threat to their systems.
2276 <item>Version numbers of affected packages
2277 <item>Version numbers of fixed packages
2278 <item>Information on where to obtain the updated packages
2279 (usually from the Debian security archive)
2280 <item>References to upstream advisories, <url
2281 id="http://cve.mitre.org" name="CVE"> identifiers, and any other
2282 information useful in cross-referencing the vulnerability
2285 <sect2 id="bug-security-building">
2286 <heading>Preparing packages to address security issues</heading>
2288 One way that you can assist the security team in their duties is to
2289 provide them with fixed packages suitable for a security advisory for
2293 When an update is made to the stable release, care must be taken to
2294 avoid changing system behavior or introducing new bugs. In order to
2295 do this, make as few changes as possible to fix the bug. Users and
2296 administrators rely on the exact behavior of a release once it is
2297 made, so any change that is made might break someone's system. This
2298 is especially true of libraries: make sure you never change the API or
2299 ABI, no matter how small the change.
2301 This means that moving to a new upstream version is not a good
2302 solution. Instead, the relevant changes should be back-ported to the
2303 version present in the current stable Debian release. Generally,
2304 upstream maintainers are willing to help if needed. If not, the
2305 Debian security team may be able to help.
2307 In some cases, it is not possible to back-port a security fix, for
2308 example when large amounts of source code need to be modified or
2309 rewritten. If this happens, it may be necessary to move to a new
2310 upstream version. However, this is only done in extreme situations,
2311 and you must always coordinate that with the security team beforehand.
2313 Related to this is another important guideline: always test your
2314 changes. If you have an exploit available, try it and see if it
2315 indeed succeeds on the unpatched package and fails on the fixed
2316 package. Test other, normal actions as well, as sometimes a security
2317 fix can break seemingly unrelated features in subtle ways.
2319 Review and test your changes as much as possible. Check the
2320 differences from the previous version repeatedly
2321 (<prgn>interdiff</prgn> from the <package>patchutils</package> package
2322 and <prgn>debdiff</prgn> from <package>devscripts</package> are useful
2323 tools for this, see <ref id="debdiff">).
2325 When packaging the fix, keep the following points in mind:
2328 <item>Make sure you target the right distribution in your
2329 <file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
2330 testing this is <tt>testing-security</tt>, and for the previous
2331 stable release, this is <tt>oldstable-security</tt>. Do not target
2332 <var>distribution</var>-proposed-updates or <tt>stable</tt>!
2334 <item>Make descriptive, meaningful changelog entries. Others will
2335 rely on them to determine whether a particular bug was fixed.
2336 Always include an external reference, preferably a CVE
2337 identifier, so that it can be cross-referenced. Include the same
2338 information in the changelog for unstable, so that it is clear that
2339 the same bug was fixed, as this is very helpful when verifying
2340 that the bug is fixed in the next stable release. If a CVE
2341 identifier has not yet been assigned, the security team will
2342 request one so that it can be included in the package and in the advisory.
2344 <item>Make sure the version number is proper. It must be greater
2345 than the current package, but less than package versions in later
2346 distributions. If in doubt, test it with <tt>dpkg
2347 --compare-versions</tt>. Be careful not to re-use a version
2348 number that you have already used for a previous upload. For
2349 <em>testing</em>, there must be
2350 a higher version in <em>unstable</em>. If there is none yet (for example,
2351 if <em>testing</em> and <em>unstable</em> have the same version) you must upload a
2352 new version to unstable first.
2354 <item>Do not make source-only uploads if your package has any
2355 binary-all packages (do not use the <tt>-S</tt> option to
2356 <prgn>dpkg-buildpackage</prgn>). The <prgn>buildd</prgn> infrastructure will
2357 not build those. This point applies to normal package uploads as
2360 <item>If the upstream source has been uploaded to
2361 security.debian.org before (by a previous security update), build
2362 the upload without the upstream source (<tt>dpkg-buildpackage
2363 -sd</tt>). Otherwise, build with full source
2364 (<tt>dpkg-buildpackage -sa</tt>).
2366 <item>Be sure to use the exact same <file>*.orig.tar.gz</file> as used in the
2367 normal archive, otherwise it is not possible to move the security
2368 fix into the main archives later.
2370 <item>Be sure to build the package on a clean
2371 system which only has packages installed from the distribution you
2372 are building for. If you do not have such a system yourself, you
2373 can use a debian.org machine (see <ref id="server-machines">)
2374 or setup a chroot (see <ref id="pbuilder"> and
2375 <ref id="debootstrap">).
2378 <sect2 id="bug-security-upload">Uploading the fixed package
2380 Do <strong>NOT</strong> upload a package to the security upload queue
2381 (oldstable-security, stable-security, etc.) without
2382 prior authorization from the security team. If the package does not
2383 exactly meet the team's requirements, it will cause many problems and
2384 delays in dealing with the unwanted upload.
2386 Do <strong>NOT</strong> upload your fix to proposed-updates without
2387 coordinating with the security team. Packages from
2388 security.debian.org will be copied into the proposed-updates directory
2389 automatically. If a package with the same or a higher version number
2390 is already installed into the archive, the security update will be
2391 rejected by the archive system. That way, the stable distribution
2392 will end up without a security update for this package instead.
2394 Once you have created and tested the new package and it has been
2395 approved by the security team, it needs to be uploaded so that it can
2396 be installed in the archives. For security uploads, the place to
2398 <tt>ftp://security.debian.org/pub/SecurityUploadQueue/</tt> .
2401 Once an upload to the security queue has been accepted, the package
2402 will automatically be rebuilt for all architectures and stored for
2403 verification by the security team.
2406 Uploads which are waiting for acceptance or verification are only
2407 accessible by the security team. This is necessary since there might
2408 be fixes for security problems that cannot be disclosed yet.
2411 If a member of the security team accepts a package, it will be
2412 installed on security.debian.org as well as the proper
2413 <var>distribution</var>-proposed-updates on ftp-master or in the non-US
2416 <sect id="archive-manip">
2417 <heading>Moving, removing, renaming, adopting, and orphaning
2420 Some archive manipulation operations are not automated in the Debian
2421 upload process. These procedures should be manually followed by
2422 maintainers. This chapter gives guidelines in what to do in these
2425 <sect1 id="moving-pkgs">Moving packages
2427 Sometimes a package will change its section. For instance, a
2428 package from the `non-free' section might be GPL'd in a later version,
2429 in which case, the package should be moved to `main' or
2430 `contrib'.<footnote> See the <url id="&url-debian-policy;"
2431 name="Debian Policy Manual"> for guidelines on what section a package
2435 If you need to change the section for one of your packages, change the
2436 package control information to place the package in the desired
2437 section, and re-upload the package (see the <url id="&url-debian-policy;"
2438 name="Debian Policy Manual"> for details). If your new section is
2439 valid, it will be moved automatically. If it does not, then contact
2440 the ftpmasters in order to understand what happened.
2442 If, on the other hand, you need to change the <em>subsection</em> of
2443 one of your packages (e.g., ``devel'', ``admin''), the procedure is
2444 slightly different. Correct the subsection as found in the control
2445 file of the package, and re-upload that. Also, you'll need to get the
2446 override file updated, as described in <ref id="override-file">.
2449 <sect1 id="removing-pkgs">Removing packages
2451 If for some reason you want to completely remove a package (say, if it
2452 is an old compatibility library which is no longer required), you
2453 need to file a bug against <tt>ftp.debian.org</tt> asking that the
2454 package be removed. Make sure you indicate which distribution the
2455 package should be removed from. Normally, you can only have packages
2456 removed from <em>unstable</em> and <em>experimental</em>. Packages
2457 are not removed from <em>testing</em> directly. Rather, they will be
2458 removed automatically after the package has been removed from
2459 <em>unstable</em> and no package in <em>testing</em> depends on it.
2461 You also have to detail the reasons justifying that request. This is to
2462 avoid unwanted removals and to keep a trace of why a package has been
2463 removed. For example, you can provide the name of the package that
2464 supersedes the one to be removed.
2466 Usually you only ask the removal of a package maintained by yourself.
2467 If you want to remove another package, you have to get the approval
2468 of its last maintainer.
2470 If in doubt concerning whether a package is disposable, email
2471 &email-debian-devel; asking for opinions. Also of interest is the
2472 <prgn>apt-cache</prgn> program from the <package>apt</package>
2473 package. When invoked as <tt>apt-cache showpkg
2474 <var>package</var></tt>, the program will show details for
2475 <var>package</var>, including reverse depends.
2477 Once the package has been removed, the package's bugs should be handled.
2478 They should either be reassigned to another package in the case where
2479 the actual code has evolved into another package (e.g. <tt>libfoo12</tt>
2480 was removed because <tt>libfoo13</tt> supersedes it) or closed if the
2481 software is simply no more part of Debian.
2483 <sect2>Removing packages from <file>Incoming</file>
2485 In the past, it was possible to remove packages from <file>incoming</file>.
2486 However, with the introduction of the new incoming system, this is no longer
2487 possible. Instead, you have to upload a new revision of your package with
2488 a higher version as the package you want to replace. Both versions will be
2489 installed in the archive but only the higher version will actually be
2490 available in <em>unstable</em> since the previous version will immediately
2491 be replaced by the higher. However, if you do proper testing of your
2492 packages, the need to replace a package should not occur too often anyway.
2494 <sect1>Replacing or renaming packages
2496 Sometimes you made a mistake naming the package and you need to rename
2497 it. In this case, you need to follow a two-step process. First, set
2498 your <file>debian/control</file> file to replace and conflict with the
2499 obsolete name of the package (see the <url id="&url-debian-policy;"
2500 name="Debian Policy Manual"> for details). Once you've uploaded
2501 the package and the package has moved into the archive, file a bug
2502 against <tt>ftp.debian.org</tt> asking to remove the package with the
2503 obsolete name. Do not forget to properly reassign the package's bugs
2506 At other times, you may make a mistake in constructing your package and
2507 wish to replace it. The only way to do this is to increase the version
2508 number and upload a new version. The old version will be expired in
2509 the usual manner. Note that this applies to each part of your package,
2510 including the sources: if you wish to replace the upstream source tarball
2511 of your package, you will need to upload it with a different version. An
2512 easy possibility is to replace <file>foo_1.00.orig.tar.gz</file> with
2513 <file>foo_1.00+0.orig.tar.gz</file>. This restriction gives each file
2514 on the ftp site a unique name, which helps to ensure consistency across the
2517 <sect1 id="orphaning">Orphaning a package
2519 If you can no longer maintain a package, you need to inform the others
2520 about that, and see that the package is marked as orphaned.
2521 You should set the package maintainer to <tt>Debian QA Group
2522 &orphan-address;</tt> and submit a bug report
2523 against the pseudo package <package>wnpp</package>. The bug report should be
2524 titled <tt>O: <var>package</var> -- <var>short description</var></tt>
2525 indicating that the package is now orphaned. The severity of the bug
2526 should be set to <em>normal</em>. If you feel it's necessary, send a copy
2527 to &email-debian-devel; by putting the address in the X-Debbugs-CC: header
2528 of the message (no, don't use CC:, because that way the message's subject
2529 won't indicate the bug number).
2531 If the package is especially crucial to Debian, you should instead submit
2532 a bug against <package>wnpp</package> and title it <tt>RFA: <var>package</var> --
2533 <var>short description</var></tt> and set its severity to
2534 <em>important</em>. <tt>RFA</tt> stands for <em>Request For Adoption</em>.
2535 Definitely copy the message to debian-devel in this case, as described
2538 Read instructions on the <url id="&url-wnpp;" name="WNPP web pages">
2539 for more information.
2541 <sect1 id="adopting">Adopting a package
2543 A list of packages in need of a new maintainer is available at in the
2544 <url name="Work-Needing and Prospective Packages list (WNPP)"
2545 id="&url-wnpp;">. If you wish to take over maintenance of any of the
2546 packages listed in the WNPP, please take a look at the aforementioned
2547 page for information and procedures.
2549 It is not OK to simply take over a package that you feel is neglected
2550 — that would be package hijacking. You can, of course, contact the
2551 current maintainer and ask them if you may take over the package.
2552 If you have reason to believe a maintainer has gone AWOL
2553 (absent without leave), see <ref id="mia-qa">.
2555 Generally, you may not take over the package without the assent of the
2556 current maintainer. Even if they ignore you, that is still not grounds to
2557 take over a package. Complaints about maintainers should be brought up on
2558 the developers' mailing list. If the discussion doesn't end with a positive
2559 conclusion, and the issue is of a technical nature, consider bringing it to
2560 the attention of the technical committee (see the <url name="technical
2561 committee web page" id="&url-tech-ctte;"> for more information).
2563 If you take over an old package, you probably want to be listed as the
2564 package's official maintainer in the bug system. This will happen
2565 automatically once you upload a new version with an updated
2566 <tt>Maintainer:</tt> field, although it can take a few hours after the
2567 upload is done. If you do not expect to upload a new version for a while,
2568 you can use <ref id="pkg-tracking-system"> to get the bug reports. However,
2569 make sure that the old maintainer has no problem with the fact that
2570 they will continue to receive the bugs during that time.
2573 <sect id="porting">Porting and being ported
2575 Debian supports an ever-increasing number of architectures. Even if
2576 you are not a porter, and you don't use any architecture but one, it
2577 is part of your duty as a maintainer to be aware of issues of
2578 portability. Therefore, even if you are not a porter, you should read
2579 most of this chapter.
2581 Porting is the act of building Debian packages for architectures that
2582 is different from the original architecture of the package
2583 maintainer's binary package. It is a unique and essential activity.
2584 In fact, porters do most of the actual compiling of Debian packages.
2585 For instance, for a single <em>i386</em> binary package, there must be
2586 a recompile for each architecture, which amounts to
2587 &number-of-arches; more builds.
2590 <sect1 id="kind-to-porters">Being kind to porters
2592 Porters have a difficult and unique task, since they are required to
2593 deal with a large volume of packages. Ideally, every source package
2594 should build right out of the box. Unfortunately, this is often not
2595 the case. This section contains a checklist of ``gotchas'' often
2596 committed by Debian maintainers — common problems which often stymie
2597 porters, and make their jobs unnecessarily difficult.
2599 The first and most important watchword is to respond quickly to bug or
2600 issues raised by porters. Please treat porters with courtesy, as if
2601 they were in fact co-maintainers of your package (which in a way, they
2602 are). Please be tolerant of succinct or even unclear bug reports,
2603 doing your best to hunt down whatever the problem is.
2605 By far, most of the problems encountered by porters are caused by
2606 <em>packaging bugs</em> in the source packages. Here is a checklist
2607 of things you should check or be aware of.
2611 Make sure that your <tt>Build-Depends</tt> and
2612 <tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
2613 are set properly. The best way to validate this is to use the
2614 <package>debootstrap</package> package to create an unstable chroot
2615 environment (see <ref id="debootstrap">).
2616 Within that chrooted environment, install the
2617 <package>build-essential</package> package and any package
2618 dependencies mentioned in <tt>Build-Depends</tt> and/or
2619 <tt>Build-Depends-Indep</tt>. Finally, try building your package
2620 within that chrooted environment. These steps can be automated
2621 by the use of the <prgn>pbuilder</prgn> program which is provided by
2622 the package of the same name (see <ref id="pbuilder">).
2624 If you can't set up a proper chroot, <prgn>dpkg-depcheck</prgn> may be
2625 of assistance (see <ref id="dpkg-depcheck">).
2627 See the <url id="&url-debian-policy;" name="Debian Policy
2628 Manual"> for instructions on setting build dependencies.
2630 Don't set architecture to a value other than ``all'' or ``any'' unless
2631 you really mean it. In too many cases, maintainers don't follow the
2632 instructions in the <url id="&url-debian-policy;" name="Debian Policy
2633 Manual">. Setting your architecture to ``i386'' is usually incorrect.
2635 Make sure your source package is correct. Do <tt>dpkg-source -x
2636 <var>package</var>.dsc</tt> to make sure your source package unpacks
2637 properly. Then, in there, try building your package from scratch with
2638 <prgn>dpkg-buildpackage</prgn>.
2640 Make sure you don't ship your source package with the
2641 <file>debian/files</file> or <file>debian/substvars</file> files.
2642 They should be removed by the `clean' target of
2643 <file>debian/rules</file>.
2645 Make sure you don't rely on locally installed or hacked configurations
2646 or programs. For instance, you should never be calling programs in
2647 <file>/usr/local/bin</file> or the like. Try not to rely on programs
2648 be setup in a special way. Try building your package on another
2649 machine, even if it's the same architecture.
2651 Don't depend on the package you're building already being installed (a
2652 sub-case of the above issue).
2654 Don't rely on the compiler being a certain version, if possible. If
2655 not, then make sure your build dependencies reflect the restrictions,
2656 although you are probably asking for trouble, since different
2657 architectures sometimes standardize on different compilers.
2659 Make sure your debian/rules contains separate ``binary-arch'' and
2660 ``binary-indep'' targets, as the Debian Policy Manual requires.
2661 Make sure that both targets work independently, that is, that you can
2662 call the target without having called the other before. To test this,
2663 try to run <tt>dpkg-buildpackage -B</tt>.
2667 <sect1 id="porter-guidelines">Guidelines for porter uploads
2669 If the package builds out of the box for the architecture to be ported
2670 to, you are in luck and your job is easy. This section applies to
2671 that case; it describes how to build and upload your binary package so
2672 that it is properly installed into the archive. If you do have to
2673 patch the package in order to get it to compile for the other
2674 architecture, you are actually doing a source NMU, so consult <ref
2675 id="nmu-guidelines"> instead.
2677 For a porter upload, no changes are being made to the source. You do
2678 not need to touch any of the files in the source package. This
2679 includes <file>debian/changelog</file>.
2681 The way to invoke <prgn>dpkg-buildpackage</prgn> is as
2682 <tt>dpkg-buildpackage -B -m<var>porter-email</var></tt>. Of course,
2683 set <var>porter-email</var> to your email address. This will do a
2684 binary-only build of only the architecture-dependent portions of the
2685 package, using the `binary-arch' target in <file>debian/rules</file>.
2687 <sect2 id="binary-only-nmu">
2688 <heading>Recompilation or binary-only NMU</heading>
2690 Sometimes the initial porter upload is problematic because the environment
2691 in which the package was built was not good enough (outdated or obsolete
2692 library, bad compiler, ...). Then you may just need to recompile it in
2693 an updated environment. However, you have to bump the version number in
2694 this case, so that the old bad package can be replaced in the Debian archive
2695 (<prgn>katie</prgn> refuses to install new packages if they don't have a
2696 version number greater than the currently available one). Despite the
2697 required modification of the changelog, these are called binary-only NMUs
2698 — there is no need in this case to trigger all other architectures
2699 to consider themselves out of date or requiring recompilation.
2701 Such recompilations require special ``magic'' version numbering, so that
2702 the archive maintenance tools recognize that, even though there is a
2703 new Debian version, there is no corresponding source update. If you
2704 get this wrong, the archive maintainers will reject your upload (due
2705 to lack of corresponding source code).
2707 The ``magic'' for a recompilation-only NMU is triggered by using the
2708 third-level number on the Debian part of the version. For instance,
2709 if the latest version you are recompiling against was version
2710 ``2.9-3'', your NMU should carry a version of ``2.9-3.0.1''. If the
2711 latest version was ``3.4-2.1'', your NMU should have a version number
2715 <sect2 id="source-nmu-when-porter">
2716 <heading>When to do a source NMU if you are a porter</heading>
2718 Porters doing a source NMU generally follow the guidelines found in
2719 <ref id="nmu">, just like non-porters. However, it is expected that
2720 the wait cycle for a porter's source NMU is smaller than for a
2721 non-porter, since porters have to cope with a large quantity of
2723 Again, the situation varies depending on the distribution they are
2727 FIXME: commented out until I can work out how to upload to testing directly
2729 Crucial fixes (i.e., changes need to get a source
2730 package to compile for a released-targeted architecture) can be
2731 uploaded with <em>no</em> waiting period for the `frozen' distribution.
2734 However, if you are a porter doing an NMU for `unstable', the above
2735 guidelines for porting should be followed, with two variations.
2736 Firstly, the acceptable waiting period — the time between when the
2737 bug is submitted to the BTS and when it is OK to do an NMU — is seven
2738 days for porters working on the unstable distribution. This period
2739 can be shortened if the problem is critical and imposes hardship on
2740 the porting effort, at the discretion of the porter group. (Remember,
2741 none of this is Policy, just mutually agreed upon guidelines.)
2743 Secondly, porters doing source NMUs should make sure that the bug they
2744 submit to the BTS should be of severity `serious' or greater. This
2745 ensures that a single source package can be used to compile every
2746 supported Debian architecture by release time. It is very important
2747 that we have one version of the binary and source package for all
2748 architecture in order to comply with many licenses.
2750 Porters should try to avoid patches which simply kludge around bugs in
2751 the current version of the compile environment, kernel, or libc.
2752 Sometimes such kludges can't be helped. If you have to kludge around
2753 compilers bugs and the like, make sure you <tt>#ifdef</tt> your work
2754 properly; also, document your kludge so that people know to remove it
2755 once the external problems have been fixed.
2757 Porters may also have an unofficial location where they can put the
2758 results of their work during the waiting period. This helps others
2759 running the port have the benefit of the porter's work, even during
2760 the waiting period. Of course, such locations have no official
2761 blessing or status, so buyer, beware.
2764 <sect1 id="porter-automation">
2765 <heading>Porting infrastructure and automation</heading>
2767 There is infrastructure and several tools to help automate the package
2768 porting. This section contains a brief overview of this automation and
2769 porting to these tools; see the package documentation or references for
2770 full information.</p>
2773 <heading>Mailing lists and web pages</heading>
2775 Web pages containing the status of each port can be found at <url
2776 id="&url-debian-ports;">.
2778 Each port of Debian has a mailing list. The list of porting mailing
2779 lists can be found at <url id="&url-debian-port-lists;">. These lists
2780 are used to coordinate porters, and to connect the users of a given
2781 port with the porters.</p>
2785 <heading>Porter tools</heading>
2787 Descriptions of several porting tools can be found in <ref
2788 id="tools-porting">.</p>
2792 <heading><package>buildd</package></heading>
2794 The <package>buildd</package> system is used as a distributed,
2795 client-server build distribution system. It is usually used in
2796 conjunction with <em>auto-builders</em>, which are ``slave'' hosts
2797 which simply check out and attempt to auto-build packages which need
2798 to be ported. There is also an email interface to the system, which
2799 allows porters to ``check out'' a source package (usually one which
2800 cannot yet be auto-built) and work on it.
2802 <package>buildd</package> is not yet available as a package; however,
2803 most porting efforts are either using it currently or planning to use
2804 it in the near future. The actual automated builder is packaged as
2805 <package>sbuild</package>, see its description in <ref id="sbuild">.
2806 The complete <package>buildd</package> system also collects a number of as yet unpackaged
2807 components which are currently very useful and in use continually,
2808 such as <prgn>andrea</prgn> and
2809 <prgn>wanna-build</prgn>.
2811 Some of the data produced by <package>buildd</package> which is
2812 generally useful to porters is available on the web at <url
2813 id="&url-buildd;">. This data includes nightly updated information
2814 from <prgn>andrea</prgn> (source dependencies) and
2815 <package>quinn-diff</package> (packages needing recompilation).
2817 We are quite proud of this system, since it has so
2818 many possible uses. Independent development groups can use the system for
2819 different sub-flavors of Debian, which may or may not really be of
2820 general interest (for instance, a flavor of Debian built with <prgn>gcc</prgn>
2821 bounds checking). It will also enable Debian to recompile entire
2822 distributions quickly.
2826 <sect id="nmu">Non-Maintainer Uploads (NMUs)
2828 Under certain circumstances it is necessary for someone other than the
2829 official package maintainer to make a release of a package. This is
2830 called a non-maintainer upload, or NMU.
2832 Debian porters, who compile packages for different architectures,
2833 occasionally do binary-only NMUs as part of their porting activity
2834 (see <ref id="porting">). Another reason why NMUs are done is when a
2835 Debian developers needs to fix another developers' packages in order to
2836 address serious security problems or crippling bugs, especially during
2837 the freeze, or when the package maintainer is unable to release a fix
2838 in a timely fashion.
2840 This chapter contains information providing guidelines for when and
2841 how NMUs should be done. A fundamental distinction is made between
2842 source and binary-only NMUs, which is explained in the next section.
2844 <sect1 id="nmu-terms">Terminology
2846 There are two new terms used throughout this section: ``binary-only NMU''
2847 and ``source NMU''. These terms are used with specific technical
2848 meaning throughout this document. Both binary-only and source NMUs are
2849 similar, since they involve an upload of a package by a developer who
2850 is not the official maintainer of that package. That is why it's a
2851 <em>non-maintainer</em> upload.
2853 A source NMU is an upload of a package by a developer who is not the
2854 official maintainer, for the purposes of fixing a bug in the package.
2855 Source NMUs always involves changes to the source (even if it is just
2856 a change to <file>debian/changelog</file>). This can be either a
2857 change to the upstream source, or a change to the Debian bits of the
2858 source. Note, however, that source NMUs may also include
2859 architecture-dependent packages, as well as an updated Debian diff.
2861 A binary-only NMU is a recompilation and upload of a binary package
2862 for a given architecture. As such, it is usually part of a porting
2863 effort. A binary-only NMU is a non-maintainer uploaded binary version
2864 of a package, with no source changes required. There are many cases
2865 where porters must fix problems in the source in order to get them to
2866 compile for their target architecture; that would be considered a
2867 source NMU rather than a binary-only NMU. As you can see, we don't
2868 distinguish in terminology between porter NMUs and non-porter NMUs.
2870 Both classes of NMUs, source and binary-only, can be lumped by the
2871 term ``NMU''. However, this often leads to confusion, since most
2872 people think ``source NMU'' when they think ``NMU''. So it's best to
2873 be careful. In this chapter, if we use the unqualified term ``NMU'',
2874 we refer to any type of non-maintainer upload NMUs, whether source and
2875 binary, or binary-only.
2878 <sect1 id="nmu-who">Who can do an NMU
2880 Only official, registered Debian maintainers can do binary or source
2881 NMUs. An official maintainer is someone who has their key in the
2882 Debian key ring. Non-developers, however, are encouraged to download
2883 the source package and start hacking on it to fix problems; however,
2884 rather than doing an NMU, they should just submit worthwhile patches
2885 to the Bug Tracking System. Maintainers almost always appreciate
2886 quality patches and bug reports.
2889 <sect1 id="nmu-when">When to do a source NMU
2891 Guidelines for when to do a source NMU depend on the target
2892 distribution, i.e., stable, unstable, or experimental. Porters have
2893 slightly different rules than non-porters, due to their unique
2894 circumstances (see <ref id="source-nmu-when-porter">).
2896 When a security bug is detected, the security team may do an NMU.
2897 Please refer to <ref id="bug-security"> for more information.
2899 During the release cycle (see <ref id="sec-dists">), NMUs which fix
2900 serious or higher severity bugs are encouraged and accepted. Even
2901 during this window, however, you should endeavor to reach the current
2902 maintainer of the package; they might be just about to upload a fix
2903 for the problem. As with any source NMU, the guidelines found in <ref
2904 id="nmu-guidelines"> need to be followed. Special exceptions are made
2905 for <ref id="qa-bsp">.
2907 Uploading bug fixes to unstable by non-maintainers should only be done
2908 by following this protocol:
2912 Make sure that the package's bugs that the NMU is meant to address are all
2913 filed in the Debian Bug Tracking System (BTS).
2914 If they are not, submit them immediately.
2916 Wait a few days the response from the maintainer. If you don't get
2917 any response, you may want to help him by sending the patch that fixes
2918 the bug. Don't forget to tag the bug with the "patch" keyword.
2920 Wait a few more days. If you still haven't got an answer from the
2921 maintainer, send him a mail announcing your intent to NMU the package.
2922 Prepare an NMU as described in <ref id="nmu-guidelines">, test it
2923 carefully on your machine (cf. <ref id="sanitycheck">).
2924 Double check that your patch doesn't have any unexpected side effects.
2925 Make sure your patch is as small and as non-disruptive as it can be.
2927 Upload your package to incoming in <file>DELAYED/7-day</file> (cf.
2928 <ref id="delayed-incoming">), send the final patch to the maintainer via
2929 the BTS, and explain to them that they have 7 days to react if they want
2932 Follow what happens, you're responsible for any bug that you introduced
2933 with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS)
2934 to stay informed of the state of the package after your NMU.
2937 At times, the release manager or an organized group of developers can
2938 announce a certain period of time in which the NMU rules are relaxed.
2939 This usually involves shortening the period during which one is to wait
2940 before uploading the fixes, and shortening the DELAYED period. It is
2941 important to notice that even in these so-called "bug squashing party"
2942 times, the NMU'er has to file bugs and contact the developer first,
2945 <sect1 id="nmu-guidelines">How to do a source NMU
2947 The following applies to porters insofar as they are playing the dual
2948 role of being both package bug-fixers and package porters. If a
2949 porter has to change the Debian source archive, automatically their
2950 upload is a source NMU and is subject to its rules. If a porter is
2951 simply uploading a recompiled binary package, the rules are different;
2952 see <ref id="porter-guidelines">.
2954 First and foremost, it is critical that NMU patches to source should
2955 be as non-disruptive as possible. Do not do housekeeping tasks, do
2956 not change the name of modules or files, do not move directories; in
2957 general, do not fix things which are not broken. Keep the patch as
2958 small as possible. If things bother you aesthetically, talk to the
2959 Debian maintainer, talk to the upstream maintainer, or submit a bug.
2960 However, aesthetic changes must <em>not</em> be made in a non-maintainer
2964 <sect2 id="nmu-version">Source NMU version numbering
2966 Whenever you have made a change to a package, no matter how trivial,
2967 the version number needs to change. This enables our packing system
2970 If you are doing a non-maintainer upload (NMU), you should add a new
2971 minor version number to the <var>debian-revision</var> part of the
2972 version number (the portion after the last hyphen). This extra minor
2973 number will start at `1'. For example, consider the package `foo',
2974 which is at version 1.1-3. In the archive, the source package control
2975 file would be <file>foo_1.1-3.dsc</file>. The upstream version is
2976 `1.1' and the Debian revision is `3'. The next NMU would add a new
2977 minor number `.1' to the Debian revision; the new source control file
2978 would be <file>foo_1.1-3.1.dsc</file>.
2980 The Debian revision minor number is needed to avoid stealing one of
2981 the package maintainer's version numbers, which might disrupt their
2982 work. It also has the benefit of making it visually clear that a
2983 package in the archive was not made by the official maintainer.
2985 If there is no <var>debian-revision</var> component in the version
2986 number then one should be created, starting at `0.1'. If it is
2987 absolutely necessary for someone other than the usual maintainer to
2988 make a release based on a new upstream version then the person making
2989 the release should start with the <var>debian-revision</var> value
2990 `0.1'. The usual maintainer of a package should start their
2991 <var>debian-revision</var> numbering at `1'.
2994 <sect2 id="nmu-changelog">
2995 <heading>Source NMUs must have a new changelog entry</heading>
2997 A non-maintainer doing a source NMU must create a changelog entry,
2998 describing which bugs are fixed by the NMU, and generally why the NMU
2999 was required and what it fixed. The changelog entry will have the
3000 non-maintainer's email address in the log entry and the NMU version
3003 By convention, source NMU changelog entries start with the line
3005 * Non-maintainer upload
3009 <sect2 id="nmu-patch">Source NMUs and the Bug Tracking System
3011 Maintainers other than the official package maintainer should make as
3012 few changes to the package as possible, and they should always send a
3013 patch as a unified context diff (<tt>diff -u</tt>) detailing their
3014 changes to the Bug Tracking System.
3016 What if you are simply recompiling the package? If you just need to
3017 recompile it for a single architecture, then you may do a binary-only
3018 NMU as described in <ref id="binary-only-nmu"> which doesn't require any
3019 patch to be sent. If you want the package to be recompiled for all
3020 architectures, then you do a source NMU as usual and you will have to
3023 If the source NMU (non-maintainer upload) fixes some existing bugs,
3024 these bugs should be tagged <em>fixed</em> in the Bug Tracking
3025 System rather than closed. By convention, only the official package
3026 maintainer or the original bug submitter are allowed to close bugs.
3027 Fortunately, Debian's archive system recognizes NMUs and thus marks
3028 the bugs fixed in the NMU appropriately if the person doing the NMU
3029 has listed all bugs in the changelog with the <tt>Closes:
3030 bug#<var>nnnnn</var></tt> syntax (see <ref id="upload-bugfix"> for
3031 more information describing how to close bugs via the changelog).
3032 Tagging the bugs <em>fixed</em> ensures that everyone knows that the
3033 bug was fixed in an NMU; however the bug is left open until the
3034 changes in the NMU are incorporated officially into the package by
3035 the official package maintainer.
3037 Also, after doing an NMU, you have to open a new bug and include a
3038 patch showing all the changes you have made. Alternatively you can send
3039 that information to the existing bugs that are fixed by your NMU.
3040 The normal maintainer will either apply the patch or employ an alternate
3041 method of fixing the problem. Sometimes bugs are fixed independently
3042 upstream, which is another good reason to back out an NMU's patch.
3043 If the maintainer decides not to apply the NMU's patch but to release a
3044 new version, the maintainer needs to ensure that the new upstream version
3045 really fixes each problem that was fixed in the non-maintainer release.
3047 In addition, the normal maintainer should <em>always</em> retain the
3048 entry in the changelog file documenting the non-maintainer upload.
3051 <sect2 id="nmu-build">Building source NMUs
3053 Source NMU packages are built normally. Pick a distribution using the
3054 same rules as found in <ref id="distribution">, follow the other
3055 prescriptions in <ref id="upload">.
3057 Make sure you do <em>not</em> change the value of the maintainer in
3058 the <file>debian/control</file> file. Your name as given in the NMU entry of
3059 the <file>debian/changelog</file> file will be used for signing the
3062 <sect1 id="ack-nmu">Acknowledging an NMU
3064 If one of your packages has been NMU'ed, you have to incorporate the
3065 changes in your copy of the sources. This is easy, you just have
3066 to apply the patch that has been sent to you. Once this is done, you
3067 have to close the bugs that have been tagged fixed by the NMU. You
3068 can either close them manually by sending the required mails to the
3069 BTS or by adding the required <tt>closes: #nnnn</tt> in the changelog
3070 entry of your next upload.
3072 In any case, you should not be upset by the NMU. An NMU is not a
3073 personal attack against the maintainer. It is a proof that
3074 someone cares enough about the package and that they were willing to help
3075 you in your work, so you should be thankful. You may also want to
3076 ask them if they would be interested to help you on a more frequent
3077 basis as co-maintainer or backup maintainer
3078 (see <ref id="collaborative-maint">).
3081 <sect id="collaborative-maint">
3082 <heading>Collaborative maintenance</heading>
3084 "Collaborative maintenance" is a term describing the sharing of Debian
3085 package maintenance duties by several people. This collaboration is
3086 almost always a good idea, since it generally results in higher quality and
3087 faster bug fix turnaround time. It is strongly recommended that
3088 packages in which a priority of <tt>Standard</tt> or which are part of
3089 the base set have co-maintainers.</p>
3091 Generally there is a primary maintainer and one or more
3092 co-maintainers. The primary maintainer is the whose name is listed in
3093 the <tt>Maintainer</tt> field of the <file>debian/control</file> file.
3094 Co-maintainers are all the other maintainers.</p>
3096 In its most basic form, the process of adding a new co-maintainer is
3101 Setup the co-maintainer with access to the sources you build the
3102 package from. Generally this implies you are using a network-capable
3103 version control system, such as <prgn>CVS</prgn> or
3104 <prgn>Subversion</prgn>.</p>
3108 Add the co-maintainer's correct maintainer name and address to the
3109 <tt>Uploaders</tt> field in the global part of the
3110 <file>debian/control</file> file.
3112 Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org>
3118 Using the PTS (<ref id="pkg-tracking-system">), the co-maintainers
3119 should subscribe themselves to the appropriate source package.</p>
3123 Collaborative maintenance can often be further eased with the use of
3124 tools on Alioth (see <ref id="alioth">).
3128 <chapt id="best-pkging-practices">
3129 <heading>Best Packaging Practices</heading>
3131 Debian's quality is largely due to the <url id="&url-debian-policy;"
3132 name="Debian Policy">, which defines explicit baseline requirements
3133 which all Debian packages must fulfill. Yet there is also a shared
3134 history of experience which goes beyond the Debian Policy, an
3135 accumulation of years of experience in packaging. Many very
3136 talented people have created great tools, tools which help you, the
3137 Debian maintainer, create and maintain excellent packages.
3139 This chapter provides some best practices for Debian developers. All
3140 recommendations are merely that, and are not requirements or policy.
3141 These are just some subjective hints, advice and pointers collected
3142 from Debian developers. Feel free to pick and choose whatever works
3145 <sect id="bpp-debian-rules">
3146 <heading>Best practices for <file>debian/rules</file></heading>
3148 The following recommendations apply to the <file>debian/rules</file>
3149 file. Since <file>debian/rules</file> controls the build process and
3150 selects the files which go into the package (directly or indirectly),
3151 it's usually the file maintainers spend the most time on.
3153 <sect1 id="helper-scripts">Helper scripts
3155 The rationale for using helper scripts in <file>debian/rules</file> is
3156 that lets maintainers use and share common logic among many packages.
3157 Take for instance the question of installing menu entries: you need to
3158 put the file into <file>/usr/lib/menu</file>, and add commands to the
3159 maintainer scripts to register and unregister the menu entries. Since
3160 this is a very common thing for packages to do, why should each
3161 maintainer rewrite all this on their own, sometimes with bugs? Also,
3162 supposing the menu directory changed, every package would have to be
3165 Helper scripts take care of these issues. Assuming you comply with
3166 the conventions expected by the helper script, the helper takes care
3167 of all the details. Changes in policy can be made in the helper
3168 script, then packages just need to be rebuilt with the new version of
3169 the helper and no other changes.
3171 <ref id="tools"> contains a couple of different helpers. The most
3172 common and best (in our opinion) helper system is
3173 <package>debhelper</package>. Previous helper systems, such as
3174 <package>debmake</package>, were "monolithic": you couldn't pick and
3175 choose which part of the helper you found useful, but had to use the
3176 helper to do everything. <package>debhelper</package>, however, is a
3177 number of separate little <prgn>dh_*</prgn> programs. For instance,
3178 <prgn>dh_installman</prgn> installs and compresses man pages,
3179 <prgn>dh_installmenu</prgn> installs menu files, and so on. Thus, it
3180 offers enough flexibility to be able to use the little helper scripts,
3181 where useful, in conjunction with hand-crafted commands in
3182 <file>debian/rules</file>.
3184 You can get started with <package>debhelper</package> by reading
3185 <manref name="debhelper" section="1">, and looking at the examples
3186 that come with the package. <prgn>dh_make</prgn>, from the
3187 <package>dh-make</package> package (see <ref id="dh-make">), can be
3188 used to convert a "vanilla" source package to a
3189 <package>debhelper</package>ized package. This shortcut, though,
3190 should not convince you that you do not need to bother understanding
3191 the individual <prgn>dh_*</prgn> helpers. If you are going to use a
3192 helper, you do need to take the time to learn to use that helper, to
3193 learn its expectations and behavior.
3195 Some people feel that vanilla <file>debian/rules</file> files are
3196 better, since you don't have to learn the intricacies of any helper
3197 system. This decision is completely up to you. Use what works for
3198 you. Many examples of vanilla <file>debian/rules</file> files are
3199 available at <url id="&url-rules-files;">.
3202 <sect1 id="multiple-patches">
3203 <heading>Separating your patches into multiple files</heading>
3205 Big, complex packages may have many bugs that you need to deal with.
3206 If you correct a number of bug directly in the source, if you're not
3207 careful, it can get hard to differentiate the various patches that you
3208 applied. It can get quite messy when you have to update the package
3209 to a new upstream version which integrates some of the fixes (but not
3210 all). You can't take the total set of diffs (e.g., from
3211 <file>.diff.gz</file>) and work out which patch sets to back out as a
3212 unit as bugs are fixed upstream.
3214 Unfortunately, the packaging system as such currently doesn't provide for
3215 separating the patches into several files. Nevertheless, there are ways to
3216 separate patches: the patch files are shipped within the Debian patch file
3217 (<file>.diff.gz</file>), usually within the <file>debian/</file> directory.
3218 The only difference is that they aren't applied immediately by dpkg-source,
3219 but by the <tt>build</tt> rule of <file>debian/rules</file>. Conversely,
3220 they are reverted in the <tt>clean</tt> rule.
3222 <prgn>dbs</prgn> is one of the more popular approaches to this. It does all
3223 of the above, and provides a facility for creating new and updating old
3224 patches. See the package <package>dbs</package> for more information and
3225 <package>hello-dbs</package> for an example.
3227 <prgn>dpatch</prgn> also provides these facilities, but it's intented to be
3228 even easier to use. See the package <package>dpatch</package> for
3229 documentation and examples (in <file>/usr/share/doc/dpatch</file>).
3232 <sect1 id="multiple-binary">Multiple binary packages
3234 A single source package will often build several binary packages,
3235 either to provide several flavors of the same software (e.g.,
3236 the <package>vim</package> source package) or to make several small
3237 packages instead of a big one (e.g., if the user can install only the
3238 subset she needs, and thus save some disk space).
3240 The second case can be easily managed in <file>debian/rules</file>.
3241 You just need to move the appropriate files from the build directory
3242 into the package's temporary trees. You can do this using
3243 <prgn>install</prgn> or <prgn>dh_install</prgn>
3244 from <package>debhelper</package>. Be sure to check the different
3245 permutations of the various packages, ensuring that you have the
3246 inter-package dependencies set right in <file>debian/control</file>.
3248 The first case is a bit more difficult since it involves multiple
3249 recompiles of the same software but with different configuration
3250 options. The <package>vim</package> source package is an example of how to manage
3251 this using an hand-crafted <file>debian/rules</file> file.
3253 <!-- &FIXME; Find a good debhelper example with multiple configure/make
3259 <sect id="bpp-debian-control">
3260 <heading>Best practices for <file>debian/control</file></heading>
3262 The following practices are relevant to the
3263 <file>debian/control</file> file. They supplement the <url
3264 id="&url-debian-policy;ch-binary.html#s-descriptions"
3265 name="Policy on package descriptions">.
3267 The description of the package, as defined by the corresponding field
3268 in the <file>control</file> file, contains both the package synopsis
3269 and the long description for the package. <ref id="bpp-desc-basics">
3270 describes common guidelines for both parts of the package description.
3271 Following that, <ref id="bpp-pkg-synopsis"> provides guidelines
3272 specific to the synopsis, and <ref id="bpp-pkg-desc"> contains
3273 guidelines specific to the description.
3275 <sect1 id="bpp-desc-basics">
3276 <heading>General guidelines for package descriptions</heading>
3278 The package description should be written for the average likely user,
3279 the average person who will use and benefit from the package. For
3280 instance, development packages are for developers, and can be
3281 technical in their language. More general-purpose applications, such
3282 as editors, should be written for a less technical user.
3284 Our review of package descriptions lead us to conclude that most
3285 package descriptions are technical, that is, are not written to make
3286 sense for non-technical users. Unless your package really is only for
3287 technical users, this is a problem.
3289 How do you write for non-technical users? Avoid jargon. Avoid
3290 referring to other applications or frameworks that the user might not
3291 be familiar with — "GNOME" or "KDE" is fine, since users are
3292 probably familiar with these terms, but "GTK+" is
3293 probably not. Try not to assume any knowledge at all. If you must
3294 use technical terms, introduce them.
3296 Be objective. Package descriptions are not the place for advocating
3297 your package, no matter how much you love it. Remember that the
3298 reader may not care about the same things you care about.
3300 References to the names of any other software packages, protocol names,
3301 standards, or specifications should use their canonical forms, if one
3302 exists. For example, use "X Window System", "X11", or "X"; not "X
3303 Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk".
3304 Use "GNOME", not "Gnome". Use "PostScript", not "Postscript" or
3307 If you are having problems writing your description, you may wish to
3308 send it along to &email-debian-l10n-english; and request feedback.
3312 <sect1 id="bpp-pkg-synopsis">
3313 <heading>The package synopsis, or short description</heading>
3315 The synopsis line (the short description) should be concise. It
3316 must not repeat the package's name (this is policy).
3318 It's a good idea to think of the synopsis as an appositive clause, not
3319 a full sentence. An appositive clause is defined in WordNet as a
3320 grammatical relation between a word and a noun phrase that follows,
3321 e.g., "Rudolph the red-nosed reindeer". The appositive clause here is
3322 "red-nosed reindeer". Since the synopsis is a clause, rather than a
3323 full sentence, we recommend that it neither start with a capital nor
3324 end with a full stop (period). It should also not begin with an
3325 article, either definite ("the") or indefinite ("a" or "an").
3327 It might help to imagine that the synopsis is combined with the
3328 package name in the following way:
3330 <example><var>package-name</var> is a <var>synopsis</var>.</example>
3332 Alternatively, it might make sense to think of it as
3334 <example><var>package-name</var> is <var>synopsis</var>.</example>
3336 or, if the package name itself is a plural (such as
3339 <example><var>package-name</var> are <var>synopsis</var>.</example>
3341 This way of forming a sentence from the package name and synopsis
3342 should be considered as a heuristic and not a strict rule. There are
3343 some cases where it doesn't make sense to try to form a sentence.
3346 <sect1 id="bpp-pkg-desc">
3347 <heading>The long description</heading>
3349 The long description is the primary information available to the user
3350 about a package before they install it. It should provide all the
3351 information needed to let the user decide whether to install the
3352 package. Assume that the user has already read the package synopsis.
3354 The long description should consist of full and complete sentences.
3356 The first paragraph of the long description should answer the
3357 following questions: what does the package do? what task does it help
3358 the user accomplish? It is important to describe this in a
3359 non-technical way, unless of course the audience for the package is
3360 necessarily technical.
3362 The following paragraphs should answer the following questions: Why do
3363 I as a user need this package? What other features does the package
3364 have? What outstanding features and deficiencies are there compared
3365 to other packages (e.g., "if you need X, use Y instead")? Is this
3366 package related to other packages in some way that is not handled by
3367 the package manager (e.g., "this is the client to the foo server")?
3369 Be careful to avoid spelling and grammar mistakes. Ensure that you
3370 spell-check it. <prgn>ispell</prgn> has a special <tt>-g</tt> option
3371 for <file>debian/control</file> files:
3373 <example>ispell -d american -g debian/control</example>
3377 <sect1 id="bpp-upstream-info">
3378 <heading>Upstream home page</heading>
3380 We recommend that you add the URL for the package's home page to the
3381 package description in <file>debian/control</file>. This information
3382 should be added at the
3383 end of description, using the following format:
3386 Homepage: http://some-project.some-place.org/</example>
3388 Note the spaces prepending the line, which serves to break the lines
3389 correctly. To see an example of how this displays, see <url
3390 id="&url-eg-desc-upstream-info;">.
3392 If there is no home page for the software, this should naturally be
3395 Note that we expect this field will eventually be replaced by a proper
3396 <file>debian/control</file> field understood by <prgn>dpkg</prgn> and
3397 <tt>&packages-host;</tt>. If you don't want to bother migrating the
3398 home page from the description to this field, you should probably wait
3399 until that is available.</p>
3404 <sect id="bpp-debian-changelog">
3405 <heading>Best practices for <file>debian/changelog</file></heading>
3407 The following practices supplement the <url name="Policy on changelog
3408 files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
3410 <sect1 id="bpp-changelog-do">
3411 <heading>Writing useful changelog entries</heading>
3413 The changelog entry for a package revision documents changes in that
3414 revision, and only them. Concentrate on describing significant and
3415 user-visible changes that were made since the last version.
3417 Focus on <em>what</em> was changed — who, how and when are
3418 usually less important. Having said that, remember to politely
3419 attribute people who have provided notable help in making the package
3420 (e.g., those who have sent in patches).
3422 There's no need to elaborate the trivial and obvious changes. You can
3423 also aggregate several changes in one entry. On the other hand, don't
3424 be overly terse if you have undertaken a major change. Be especially
3425 clear if there are changes that affect the behaviour of the program.
3426 For further explanations, use the <file>README.Debian</file> file.
3428 Use common English so that the majority of readers can comprehend it.
3429 Avoid abbreviations, "tech-speak" and jargon when explaining changes
3430 that close bugs, especially for bugs filed by users that did not
3431 strike you as particularly technically savvy. Be polite, don't swear.
3433 It is sometimes desirable to prefix changelog entries with the names
3434 of the files that were changed. However, there's no need to
3435 explicitly list each and every last one of the changed files,
3436 especially if the change was small or repetitive. You may use
3439 When referring to bugs, don't assume anything. Say what the problem
3440 was, how it was fixed, and append the "closes: #nnnnn" string. See
3441 <ref id="upload-bugfix"> for more information.
3444 <sect1 id="bpp-changelog-misconceptions">
3445 <heading>Common misconceptions about changelog entries</heading>
3447 The changelog entries should <strong>not</strong> document generic
3448 packaging issues ("Hey, if you're looking for foo.conf, it's in
3449 /etc/blah/."), since administrators and users are supposed to be at
3450 least remotely acquainted with how such things are generally arranged
3451 on Debian systems. Do, however, mention if you change the location of
3452 a configuration file.
3454 The only bugs closed with a changelog entry should be those that are
3455 actually fixed in the same package revision. Closing unrelated bugs
3456 in the changelog is bad practice. See <ref id="upload-bugfix">.
3458 The changelog entries should <strong>not</strong> be used for random
3459 discussion with bug reporters ("I don't see segfaults when starting
3460 foo with option bar; send in more info"), general statements on life,
3461 the universe and everything ("sorry this upload took me so long, but I
3462 caught the flu"), or pleas for help ("the bug list on this package is
3463 huge, please lend me a hand"). Such things usually won't be noticed
3464 by their target audience, but may annoy people who wish to read
3465 information about actual changes in the package. See <ref
3466 id="bug-answering"> for more information on how to use the bug
3469 It is an old tradition to acknowledge bugs fixed in non-maintainer
3470 uploads in the first changelog entry of the proper maintainer upload,
3471 for instance, in a changelog entry like this:
3473 * Maintainer upload, closes: #42345, #44484, #42444.
3475 This will close the NMU bugs tagged "fixed" when the package makes
3476 it into the archive. The bug for the fact that an NMU was done can be
3477 closed the same way. Of course, it's also perfectly acceptable to
3478 close NMU-fixed bugs by other means; see <ref id="bug-answering">.
3481 <sect1 id="bpp-changelog-errors">
3482 <heading>Common errors in changelog entries</heading>
3484 The following examples demonstrate some common errors or example of
3485 bad style in changelog entries.
3489 * Fixed all outstanding bugs.
3491 This doesn't tell readers anything too useful, obviously.
3495 * Applied patch from Jane Random.
3497 What was the patch about?
3501 * Late night install target overhaul.
3503 Overhaul which accomplished what? Is the mention of late night
3504 supposed to remind us that we shouldn't trust that code?
3508 * Fix vsync FU w/ ancient CRTs.
3510 Too many acronyms, and it's not overly clear what the, uh, fsckup (oops,
3511 a curse word!) was actually about, or how it was fixed.
3515 * This is not a bug, closes: #nnnnnn.
3517 First of all, there's absolutely no need to upload the package to
3518 convey this information; instead, use the bug tracking system.
3519 Secondly, there's no explanation as to why the report is not a bug.
3523 * Has been fixed for ages, but I forgot to close; closes: #54321.
3525 If for some reason you didn't mention the bug number in a previous changelog
3526 entry, there's no problem, just close the bug normally in the BTS. There's
3527 no need to touch the changelog file, presuming the description of the fix is
3528 already in (this applies to the fixes by the upstream authors/maintainers as
3529 well, you don't have to track bugs that they fixed ages ago in your
3534 * Closes: #12345, #12346, #15432
3536 Where's the description? If you can't think of a descriptive message,
3537 start by inserting the title of each different bug.
3542 <sect1 id="pkg-mgmt-cvs">Managing a package with CVS
3544 &FIXME; presentation of cvs-buildpackage, updating sources
3545 via CVS (debian/rules refresh).
3546 <url id="http://www.debian.org/devel/cvs_packages">
3550 <sect id="bpp-debian-maint-scripts">
3551 <heading>Best practices for maintainer scripts</heading>
3553 Maintainer scripts include the files <file>debian/postinst</file>,
3554 <file>debian/preinst</file>, <file>debian/prerm</file> and
3555 <file>debian/postrm</file>. These scripts take care of any package
3556 installation or deinstallation setup which isn't handled merely by the
3557 creation or removal of files and directories. The following
3558 instructions supplement the <url id="&url-debian-policy;" name="Debian
3561 Maintainer scripts must be idempotent. That means that you need to
3562 make sure nothing bad will happen if the script is called twice where
3563 it would usually be called once.
3565 Standard input and output may be redirected (e.g. into pipes) for
3566 logging purposes, so don't rely on them being a tty.
3568 All prompting or interactive configuration should be kept to a
3569 minimum. When it is necessary, you should use the
3570 <package>debconf</package> package for the interface. Remember that
3571 prompting in any case can only be in the <tt>configure</tt> stage of
3572 the <file>postinst</file> script.
3574 Keep the maintainer scripts as simple as possible. We suggest you use
3575 pure POSIX shell scripts. Remember, if you do need any bash features,
3576 the maintainer script must have a bash sh-bang line. POSIX shell or
3577 Bash are preferred to Perl, since they enable
3578 <package>debhelper</package> to easily add bits to the scripts.
3580 If you change your maintainer scripts, be sure to test package
3581 removal, double installation, and purging. Be sure that a purged
3582 package is completely gone, that is, it must remove any files created,
3583 directly or indirectly, in any maintainer script.
3585 If you need to check for the existence of a command, you should use
3587 <example>if [ -x /usr/sbin/install-docs ]; then ...</example>
3589 If you don't wish to hard-code the path of the command in your
3590 maintainer script, the following POSIX-compliant shell function may
3595 You can use this function to search <tt>$PATH</tt> for a command name,
3596 passed as an argument. It returns true (zero) if the command was
3597 found, and false if not. This is really the most portable way, since
3598 <tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
3601 While <prgn>which</prgn> is an acceptable alternative, since
3602 it is from the required <package>debianutils</package> package, it's
3603 not on the root partition. That is, it's in <file>/usr/bin</file> rather
3604 than <file>/bin</file>, so one can't use it in scripts which are run
3605 before the <file>/usr</file> partition is mounted. Most scripts won't have
3606 this problem, though.
3610 <sect id="bpp-config-mgmt">
3611 <heading>Configuration management with <package>debconf</package></heading>
3613 <package>Debconf</package> is a configuration management system which
3614 can be used by all the various packaging scripts
3615 (<file>postinst</file> mainly) to request feedback from the user
3616 concerning how to configure the package. Direct user interactions must
3617 now be avoided in favor of <package>debconf</package>
3618 interaction. This will enable non-interactive installations in the
3621 Debconf is a great tool but it is often poorly used. Many common mistakes
3622 are listed in the <manref name="debconf-devel" section="7"> man page.
3623 It is something that you must read if you decide to use debconf.
3627 <sect id="bpp-i18n">
3628 <heading>Internationalization</heading>
3630 <sect1 id="bpp-i18n-debconf">
3631 <heading>Handling debconf translations</heading>
3633 Like porters, translators have a difficult task. They work on many
3634 packages and must collaborate with many different
3635 maintainers. Moreover, most of the time, they are not native English
3636 speakers, so you may need to be particularly patient with them.
3638 The goal of <package>debconf</package> was to make packages
3639 configuration easier for maintainers and for users. Originally,
3640 translation of debconf templates was handled with
3641 <prgn>debconf-mergetemplate</prgn>. However, that technique is now
3642 deprecated; the best way to accomplish <package>debconf</package>
3643 internationalization is by using the <package>po-debconf</package>
3644 package. This method is easier both for maintainer and translators;
3645 transition scripts are provided.
3647 Using <package>po-debconf</package>, the translation is stored in
3648 <file>po</file> files (drawing from <prgn>gettext</prgn> translation
3649 techniques). Special template files contain the original messages and
3650 mark which fields are translatable. When you change the value of a
3651 translatable field, by calling <prgn>debconf-updatepo</prgn>, the
3652 translation is marked as needing attention from the translators. Then,
3653 at build time, the <prgn>dh_installdebconf</prgn> program takes care
3654 of all the needed magic to add the template along with the up-to-date
3655 translations into the binary packages. Refer to the <manref
3656 name="po-debconf" section="7"> manual page for details.
3659 <sect1 id="bpp-i18n-docs">
3660 <heading>Internationalized documentation</heading>
3662 Internationalizing documentation is crucial for users, but a lot of
3663 labor. There's no way to eliminate all that work, but you can make things
3664 easier for translators.
3666 If you maintain documentation of any size, its easier for translators
3667 if they have access to a source control system. That lets translators
3668 see the differences between two versions of the documentation, so, for
3669 instance, they can see what needs to be retranslated. It is
3670 recommended that the translated documentation maintain a note about
3671 what source control revision the translation is based on. An
3672 interesting system is provided by <url id="&url-i18n-doc-check;"
3673 name="doc-check"> in the <package>boot-floppies</package> package,
3674 which shows an overview of the translation status for any given
3675 language, using structured comments for the current revision of the
3676 file to be translated and, for a translated file, the revision of the
3677 original file the translation is based on. You might wish to adapt
3678 and provide that in your CVS area.
3680 If you maintain XML or SGML documentation, we suggest that you isolate
3681 any language-independent information and define those as entities in a
3682 separate file which is included by all the different
3683 translations. This makes it much easier, for instance, to keep URLs
3684 up-to-date across multiple files.
3688 <sect id="bpp-common-situations">
3689 <heading>Common packaging situations</heading>
3692 <sect1 id="bpp-kernel">Kernel modules/patches
3694 &FIXME; Heavy use of kernel-package. provide files in
3695 /etc/modutils/ for module configuration.
3698 <sect1 id="bpp-autotools">
3699 <heading>Packages using
3700 <prgn>autoconf</prgn>/<prgn>automake</prgn></heading>
3702 Keeping <prgn>autoconf</prgn>'s <file>config.sub</file> and
3703 <file>config.guess</file> files up-to-date is critical for porters,
3704 especially on more volatile architectures. Some very good packaging
3705 practices for any package using <prgn>autoconf</prgn> and/or
3706 <prgn>automake</prgn> have been synthesized in
3707 &file-bpp-autotools; from the <package>autotools-dev</package>
3708 package. You're strongly encouraged to read this file and
3709 to follow the given recommendations.
3712 <sect1 id="bpp-libraries">Libraries
3714 Libraries are always difficult to package for various reasons. The policy
3715 imposes many constraints to ease their maintenance and to make sure
3716 upgrades are as simple as possible when a new upstream version comes out.
3717 A breakage in a library can result in dozens of dependent packages
3720 Good practices for library packaging have been grouped in
3721 <url id="&url-libpkg-guide;" name="the library packaging guide">.
3724 <sect1 id="bpp-docs">Documentation
3726 Be sure to follow the <url id="&url-debian-policy;ch-docs.html"
3727 name="Policy on documentation">.</p>
3729 If your package contains documentation built from XML or SGML, we
3730 recommend you not ship the XML or SGML source in the binary
3731 package(s). If users want the source of the documentation, they
3732 should retrieve the source package.</p>
3734 Policy specifies that documentation should be shipped in HTML format.
3735 We also recommend shipping documentation in PDF and plain text format if
3736 convenient and quality output is possible. However, it is generally
3737 not appropriate to ship plain text versions of documentation whose source
3740 Major shipped manuals should register themselves with
3741 <package>doc-base</package> on installation. See the
3742 <package>doc-base</package> package documentation for more
3746 <sect1 id="bpp-other">Specific types of packages
3748 Several specific types of packages have special sub-policies and
3749 corresponding packaging rules and practices:
3752 Perl related packages have a <url name="Perl policy"
3753 id="&url-perl-policy;">, some examples of packages following that
3754 policy are <package>libdbd-pg-perl</package> (binary perl module) or
3755 <package>libmldbm-perl</package> (arch independent perl module).
3757 Python related packages have their python policy; see
3758 &file-python-policy; in the <package>python</package> package.
3760 Emacs related packages have the <url id="&url-emacs-policy;"
3761 name="emacs policy">.
3763 Java related packages have their <url id="&url-java-policy;"
3764 name="java policy">.
3766 Ocaml related packages have their own policy, found in
3767 &file-ocaml-policy; from the <package>ocaml</package> package. A good
3768 example is the <package>camlzip</package> source package.
3770 Packages providing XML or SGML DTDs should conform to the
3771 recommendations found in the <package>sgml-base-doc</package>
3774 Lisp packages should register themselves with
3775 <package>common-lisp-controller</package>, about which see
3776 &file-lisp-controller;.
3781 <sect1 id="custom-config-files">Custom configuration files
3783 &FIXME; speak of "ucf", explain solution with a template,
3784 explain conf.d directories
3786 <sect1 id="config-with-db">Use of an external database
3788 &FIXME; The software may require a database that you need to setup.
3789 But the database may be local or distant. Thus you can't depend
3790 on a database server but just on the corresponding library.
3792 sympa may be an example package
3795 <sect1 id="bpp-archindepdata">
3796 <heading>Architecture-independent data</heading>
3798 It is not uncommon to have a large amount of architecture-independent
3799 data packaged with a program. For example, audio files, a collection
3800 of icons, wallpaper patterns, or other graphic files. If the size of
3801 this data is negligible compared to the size of the rest of the
3802 package, it's probably best to keep it all in a single package.
3804 However, if the size of the data is considerable, consider splitting
3805 it out into a separate, architecture-independent package ("_all.deb").
3806 By doing this, you avoid needless duplication of the same data into
3807 eleven or more .debs, one per each architecture. While this
3808 adds some extra overhead into the <file>Packages</file> files, it
3809 saves a lot of disk space on Debian mirrors. Separating out
3810 architecture-independent data also reduces processing time of
3811 <prgn>lintian</prgn> or <prgn>linda</prgn> (see <ref id="tools-lint">)
3812 when run over the entire Debian archive.
3819 <chapt id="beyond-pkging">
3820 <heading>Beyond Packaging</heading>
3822 Debian is about a lot more than just packaging software and
3823 maintaining those packages. This chapter contains information about
3824 ways, often really critical ways, to contribute to Debian beyond
3825 simply creating and maintaining packages.
3827 As a volunteer organization, Debian relies on the discretion of its
3828 members in choosing what they want to work on and in choosing
3829 the most critical thing to spend their time on.
3831 <sect id="submit-bug">
3832 <heading>Bug reporting</heading>
3834 We encourage you to file bugs as you find them in Debian packages. In
3835 fact, Debian developers are often the first line testers. Finding and
3836 reporting bugs in other developers' packages improves the quality of
3839 Read the <url name="instructions for reporting bugs"
3840 id="&url-bts-report;"> in the Debian <url name="bug tracking system"
3843 Try to submit the bug from a normal user account at which you are
3844 likely to receive mail, so that people can reach you if they need
3845 further information about the bug. Do not submit bugs as root.
3847 You can use a tool like <manref name="reportbug" section="1"> to
3848 submit bugs. It can automate and generally ease the process.
3850 Make sure the bug is not already filed against a package.
3851 Each package has a bug list easily reachable at
3852 <tt>http://&bugs-host;/<var>packagename</var></tt>
3853 Utilities like <manref name="querybts" section="1"> can also
3854 provide you with this information (and <prgn>reportbug</prgn>
3855 will usually invoke <prgn>querybts</prgn> before sending, too).
3857 Try to direct your bugs to the proper location. When for example
3858 your bug is about a package that overwrites files from another package,
3859 check the bug lists for <em>both</em> of those packages in order to
3860 avoid filing duplicate bug reports.
3862 For extra credit, you can go through other packages, merging bugs
3863 which are reported more than once, or tagging bugs `fixed'
3864 when they have already been fixed. Note that when you are
3865 neither the bug submitter nor the package maintainer, you should
3866 not actually close the bug (unless you secure permission from the
3869 From time to time you may want to check what has been going on
3870 with the bug reports that you submitted. Take this opportunity to
3871 close those that you can't reproduce anymore. To find
3872 out all the bugs you submitted, you just have to visit
3873 <tt>http://&bugs-host;/from:<var><your-email-addr></var></tt>.
3875 <sect1 id="submit-many-bugs">Reporting lots of bugs at once
3877 Reporting a great number of bugs for the same problem on a great
3878 number of different packages — i.e., more than 10 — is a deprecated
3879 practice. Take all possible steps to avoid submitting bulk bugs at
3880 all. For instance, if checking for the problem can be automated, add
3881 a new check to <package>lintian</package> so that an error or warning
3884 If you report more than 10 bugs on the same topic at once, it is
3885 recommended that you send a message to &email-debian-devel; describing
3886 your intention before submitting the report. This will allow other
3887 developers to verify that the bug is a real problem. In addition, it
3888 will help prevent a situation in which several maintainers start
3889 filing the same bug report simultaneously.
3891 Note that when sending lots of bugs on the same subject, you should
3892 send the bug report to <email>maintonly@&bugs-host;</email> so
3893 that the bug report is not forwarded to the bug distribution mailing
3897 <sect id="qa-effort">Quality Assurance effort
3899 <sect1 id="qa-daily-work">Daily work
3901 Even though there is a dedicated group of people for Quality
3902 Assurance, QA duties are not reserved solely for them. You can
3903 participate in this effort by keeping your packages as bug-free as
3904 possible, and as lintian-clean (see <ref id="lintian">) as
3905 possible. If you do not find that possible, then you should consider
3906 orphaning some of your packages (see <ref
3907 id="orphaning">). Alternatively, you may ask the help of other people
3908 in order to catch up the backlog of bugs that you have (you can ask
3909 for help on &email-debian-qa; or &email-debian-devel;). At the same
3910 time, you can look for co-maintainers (see <ref id="collaborative-maint">).
3912 <sect1 id="qa-bsp">Bug squashing parties
3914 From time to time the QA group organizes bug squashing parties to get rid of
3915 as many problems as possible. They are announced on &email-debian-devel-announce;
3916 and the announce explains what area will be focused on during the party:
3917 usually they focus on release critical bugs but it may happen that they
3918 decide to help finish a major upgrade going on (like a new perl version
3919 which requires recompilation of all the binary modules).
3921 The rules for non-maintainer uploads differ during the parties because
3922 the announce of the party is considered like a prior notice for NMU. If
3923 you have packages that may be affected by the party (because they have
3924 release critical bugs for example), you should send an update to each of
3925 the corresponding bug to explain their current status and what you expect
3926 from the party. If you don't want an NMU, or if you're only interested in a
3927 patch, or if you will deal yourself with the bug, please explain that in
3930 People participating in the party have special rules for NMU, they can
3931 NMU without prior notice if they upload their NMU to
3932 DELAYED/3-day at least. All other NMU rules applies as usually, they
3933 should send the patch of the NMU in the BTS (in one of the open bugs
3934 fixed by the NMU or in a new bug tagged fixed). They should
3935 also respect the maintainer's wishes if he expressed some.
3937 If someone doesn't feel confident with an NMU, he should just send a patch
3938 to the BTS. It's far better than a broken NMU.
3941 <sect id="contacting-maintainers">Contacting other maintainers
3943 During your lifetime within Debian, you will have to contact other
3944 maintainers for various reasons. You may want to discuss a new
3945 way of cooperating between a set of related packages, or you may
3946 simply remind someone that a new upstream version is available
3947 and that you need it.
3949 Looking up the email address of the maintainer for the package can be
3950 distracting. Fortunately, there is a simple email alias,
3951 <tt><package>@&packages-host;</tt>, which provides a way to
3952 email the maintainer, whatever their individual email address (or
3953 addresses) may be. Replace <tt><package></tt> with the name of
3954 a source or a binary package.
3956 You may also be interested in contacting the persons who are
3957 subscribed to a given source package via <ref id="pkg-tracking-system">.
3958 You can do so by using the <tt><package-name>@&pts-host;</tt>
3962 <sect id="mia-qa">Dealing with inactive and/or unreachable maintainers
3964 If you notice that a package is lacking maintenance, you should
3965 make sure that the maintainer is active and will continue to work on
3966 their packages. It is possible that they are not active any more, but
3967 haven't registered out of the system, so to speak. On the other hand,
3968 it is also possible that they just need a reminder.
3970 The first step is to politely contact the maintainer, and wait for a
3971 response, for a reasonable time. It is quite hard to define "reasonable
3972 time", but it is important to take into account that real life is sometimes
3973 very hectic. One way to handle this would be send a reminder after two
3976 If the maintainer doesn't reply within four weeks (a month), one can
3977 assume that a response will probably not happen. If that happens, you
3978 should investigate further, and try to gather as much useful information
3979 about the maintainer in question as possible. This includes:
3982 <item>The "echelon" information available through the
3983 <url id="&url-debian-db;" name="developers' LDAP database">,
3984 which indicates when's the last time a developer has posted to
3985 a Debian mailing list. (This includes uploads via
3986 debian-*-changes lists.) Also, remember to check whether the
3987 maintainer is marked as "on vacation" in the database.
3989 <item>The number of packages this maintainer is responsible for,
3990 and the condition of those packages. In particular, are there
3991 any RC bugs that have been open for ages? Furthermore, how
3992 many bugs are there in general? Another important piece of
3993 information is whether the packages have been NMUed, and if
3996 <item>Is there any activity of the maintainer outside of Debian?
3997 For example, they might have posted something recently to
3998 non-Debian mailing lists or news groups.
4001 One big problem are packages which were sponsored -- the maintainer is not
4002 an official Debian developer. The echelon information is not available for
4003 sponsored people, for example, so you need to find and contact the Debian
4004 developer who has actually uploaded the package. Given that they signed the
4005 package, they're responsible for the upload anyhow, and should know what
4006 happened to the person they sponsored.
4008 It is also allowed to post a query to &email-debian-devel;, asking if anyone
4009 is aware of the whereabouts of the missing maintainer.
4011 Once you have gathered all of this, you can contact &email-debian-qa;.
4012 People on this alias will use the information you provided in order to
4013 decide how to proceed. For example, they might orphan one or all of the
4014 packages of the maintainer. If a packages has been NMUed, they might prefer
4015 to contact the NMUer before orphaning the package -- perhaps the person who
4016 has done the NMU is interested in the package.
4018 One last word: please remember to be polite. We are all volunteers and
4019 cannot dedicate all of our time to Debian. Also, you are not aware of the
4020 circumstances of the person who is involved. Perhaps they might be
4021 seriously ill or might even had died -- you do not know who may be on the
4022 receiving side -- imagine how a relative will feel if they read the e-mail
4023 of the deceased and find a very impolite, angry and accusing message!)
4025 On the other hand, although we are volunteers, we do have a responsibility.
4026 So you can stress the importance of the greater good -- if a maintainer does
4027 not have the time or interest anymore, they should "let go" and give the
4028 package to someone with more time.
4031 <sect id="newmaint">
4032 <heading>Interacting with prospective Debian developers</heading>
4034 Debian's success depends on its ability to attract and retain new and
4035 talented volunteers. If you are an experienced developer, we
4036 recommend that you get involved with the process of bringing in new
4037 developers. This section describes how to help new prospective
4041 <sect1 id="sponsoring">Sponsoring packages
4043 Sponsoring a package means uploading a package for a maintainer who is not
4044 able to do it on their own, a new maintainer applicant. Sponsoring a package
4045 also means accepting responsibility for it.
4047 If you wish to volunteer as a sponsor, you can sign up at <url
4048 id="&url-sponsors;">.
4050 New maintainers usually have certain difficulties creating Debian packages
4051 — this is quite understandable. That is why the sponsor is there, to check
4052 the package and verify that it is good enough for inclusion in Debian.
4053 (Note that if the sponsored package is new, the ftpmasters will also have to
4054 inspect it before letting it in.)
4056 Sponsoring merely by signing the upload or just recompiling is
4057 <strong>definitely not recommended</strong>. You need to build the source
4058 package just like you would build a package of your own. Remember that it
4059 doesn't matter that you left the prospective developer's name both in the
4060 changelog and the control file, the upload can still be traced to you.
4062 If you are an application manager for a prospective developer, you can also
4063 be their sponsor. That way you can also verify how the applicant is
4064 handling the 'Tasks and Skills' part of their application.
4066 <sect1>Managing sponsored packages
4068 By uploading a sponsored package to Debian, you are certifying that
4069 the package meets minimum Debian standards. That implies that you
4070 must build and test the package on your own system before uploading.
4072 You can not simply upload a binary <file>.deb</file> from the sponsoree. In
4073 theory, you should only ask for the diff file and the location of the
4074 original source tarball, and then you should download the source and apply
4075 the diff yourself. In practice, you may want to use the source package
4076 built by your sponsoree. In that case, you have to check that they haven't
4077 altered the upstream files in the <file>.orig.tar.gz</file> file that
4080 Do not be afraid to write the sponsoree back and point out changes
4081 that need to be made. It often takes several rounds of back-and-forth
4082 email before the package is in acceptable shape. Being a sponsor
4083 means being a mentor.
4085 Once the package meets Debian standards, build and sign it with
4086 <example>dpkg-buildpackage -k<var>KEY-ID</var></example>
4087 before uploading it to the incoming directory.
4089 The Maintainer field of the <file>control</file> file and the
4090 <file>changelog</file> should list the person who did the packaging, i.e., the
4091 sponsoree. The sponsoree will therefore get all the BTS mail about the
4094 If you prefer to leave a more evident trace of your sponsorship job, you
4095 can add a line stating it in the most recent changelog entry.
4097 You are encouraged to keep tabs on the package you sponsor using
4098 <ref id="pkg-tracking-system">.
4100 <sect1>Advocating new developers
4102 See the page about <url id="&url-newmaint-advocate;"
4103 name="advocating a prospective developer"> at the Debian web site.
4105 <sect1>Handling new maintainer applications
4107 Please see <url id="&url-newmaint-amchecklist;" name="Checklist for
4108 Application Managers"> at the Debian web site.
4112 <appendix id="tools">Overview of Debian Maintainer Tools
4114 This section contains a rough overview of the tools available to
4115 maintainers. The following is by no means complete or definitive, but
4116 just a guide to some of the more popular tools.
4118 Debian maintainer tools are meant to help convenience developers and
4119 free their time for critical tasks. As Larry Wall says, there's more
4120 than one way to do it.
4122 Some people prefer to use high-level package maintenance tools and
4123 some do not. Debian is officially agnostic on this issue; any tool
4124 which gets the job done is fine. Therefore, this section is not meant
4125 to stipulate to anyone which tools they should use or how they should
4126 go about with their duties of maintainership. Nor is it meant to
4127 endorse any particular tool to the exclusion of a competing tool.
4129 Most of the descriptions of these packages come from the actual
4130 package descriptions themselves. Further information can be found in
4131 the package documentation itself. You can also see more info with the
4132 command <tt>apt-cache show <package-name></tt>.</p>
4134 <sect id="tools-core">
4135 <heading>Core tools</heading>
4137 The following tools are pretty much required for any maintainer.</p>
4139 <sect1 id="dpkg-dev">
4140 <heading><package>dpkg-dev</package>
4142 <package>dpkg-dev</package> contains the tools (including
4143 <prgn>dpkg-source</prgn>) required to unpack, build and upload Debian
4144 source packages. These utilities contain the fundamental, low-level
4145 functionality required to create and manipulated packages; as such,
4146 they are required for any Debian maintainer.
4148 <sect1 id="debconf">
4149 <heading><package>debconf</package></heading>
4151 <package>debconf</package> provides a consistent interface to
4152 configuring packages interactively. It is user interface
4153 independent, allowing end-users to configure packages with a
4154 text-only interface, an HTML interface, or a dialog interface. New
4155 interfaces can be added modularly.
4157 You can find documentation for this package in the
4158 <package>debconf-doc</package> package.
4160 Many feel that this system should be used for all packages requiring
4161 interactive configuration; see <ref id="bpp-config-mgmt">.
4162 <package>debconf</package> is not currently required by Debian Policy,
4163 but that may change in the future.
4166 <sect1 id="fakeroot">
4167 <heading><package>fakeroot</package>
4169 <package>fakeroot</package> simulates root privileges. This enables
4170 you to build packages without being root (packages usually want to
4171 install files with root ownership). If you have
4172 <package>fakeroot</package> installed, you can build packages as a
4173 user: <tt>dpkg-buildpackage -rfakeroot</tt>.
4177 <sect id="tools-lint">
4178 <heading>Package lint tools</heading>
4180 According to the Free On-line Dictionary of Computing (FOLDOC), `lint'
4181 is "a Unix C language processor which carries out more thorough checks
4182 on the code than is usual with C compilers." Package lint tools help
4183 package maintainers by automatically finding common problems and
4184 policy violations with their packages.</p>
4186 <sect1 id="lintian">
4187 <heading><package>lintian</package></heading>
4189 <package>lintian</package> dissects Debian packages and emits
4191 and policy violations. It contains automated checks for many aspects
4192 of Debian policy as well as some checks for common errors.
4194 You should periodically get the newest <package>lintian</package> from
4195 `unstable' and check over all your packages. Notice that the <tt>-i</tt>
4196 option provides detailed explanations of what each error or warning means,
4197 what is its basis in Policy, and commonly how you can fix the problem.
4199 Refer to <ref id="sanitycheck"> for more information on how and when
4202 You can also see a summary of all problems reported by Lintian on your
4203 packages at <url id="&url-lintian;">. Those reports contain the latest
4204 <prgn>lintian</prgn> output on the whole development distribution
4209 <heading><package>linda</package></heading>
4211 <package>linda</package> is another package linter. It is similar to
4212 <package>lintian</package> but has a different set of checks. Its
4213 written in Python rather than Perl.</p>
4216 <sect1 id="debdiff">
4217 <heading><package>debdiff</package></heading>
4219 <prgn>debdiff</prgn> (from the <package>devscripts</package> package, <ref id="devscripts">)
4220 compares file lists and control files of two packages. It is a simple
4221 regression test, as it will help you notice if the number of binary
4222 packages has changed since the last upload, or if something's changed
4223 in the control file. Of course, some of the changes it reports will be
4224 all right, but it can help you prevent various accidents.
4226 You can run it over a pair of binary packages:
4228 debdiff package_1-1_arch.deb package_2-1_arch.deb
4231 Or even a pair of changes files:
4233 debdiff package_1-1_arch.changes package_2-1_arch.changes
4236 For more information please see <manref name="debdiff" section="1">.
4242 <sect id="tools-helpers">
4243 <heading>Helpers for <file>debian/rules</file></heading>
4245 Package building tools make the process of writing
4246 <file>debian/rules</file> files easier. See <ref id="helper-scripts">
4247 for more information on why these might or might not be desired.
4249 <sect1 id="debhelper">
4250 <heading><package>debhelper</package></heading>
4252 <package>debhelper</package> is a collection of programs that can be
4253 used in <file>debian/rules</file> to automate common tasks related to
4254 building binary Debian packages. Programs are included to install
4255 various files into your package, compress files, fix file permissions,
4256 integrate your package with the Debian menu system.
4258 Unlike some approaches, <package>debhelper</package> is broken into
4259 several small, granular commands which act in a consistent manner. As
4260 such, it allows a greater granularity of control than some of the
4261 other "debian/rules tools".
4263 There are a number of little <package>debhelper</package> add-on
4264 packages, too transient to document. You can see the list of most of
4265 them by doing <tt>apt-cache search ^dh-</tt>.
4268 <sect1 id="debmake">
4269 <heading><package>debmake</package>
4271 <package>debmake</package>, a pre-cursor to
4272 <package>debhelper</package>, is a less granular
4273 <file>debian/rules</file> assistant. It includes two main programs:
4274 <prgn>deb-make</prgn>, which can be used to help a maintainer convert
4275 a regular (non-Debian) source archive into a Debian source package;
4276 and <prgn>debstd</prgn>, which incorporates in one big shot the same
4277 sort of automated functions that one finds in
4278 <package>debhelper</package>.
4280 The consensus is that <package>debmake</package> is now deprecated in
4281 favor of <package>debhelper</package>. However, it's not a bug to use
4282 <package>debmake</package>.
4285 <sect1 id="dh-make">
4286 <heading><package>dh-make</package>
4288 The <package/dh-make/ package contains <prgn/dh_make/, a program that
4289 creates a skeleton of files necessary to build a Debian package out of
4290 a source tree. As the name suggests, <prgn/dh_make/ is a rewrite of
4291 <package/debmake/ and its template files use dh_* programs from
4292 <package/debhelper/.
4294 While the rules files generated by <prgn/dh_make/ are in general a
4295 sufficient basis for a working package, they are still just the groundwork:
4296 the burden still lies on the maintainer to finely tune the generated files
4297 and make the package entirely functional and Policy-compliant.
4301 <heading><package>yada</package>
4303 <package>yada</package> is another packaging helper tool. It uses a
4304 <file>debian/packages</file> file to auto-generate
4305 <file>debian/rules</file> and other necessary files in the
4306 <file>debian/</file> subdirectory.
4308 Note that <package>yada</package> is called "essentially unmaintained"
4309 by it's own maintainer, Charles Briscoe-Smith. As such, it can be
4310 considered deprecated.
4314 <heading><package>equivs</package>
4316 <package>equivs</package> is another package for making packages. It
4317 is often suggested for local use if you need to make a package simply
4318 to fulfill dependencies. It is also sometimes used when making
4319 ``meta-packages'', which are packages whose only purpose is to depend
4320 on other packages.</p>
4326 <sect id="tools-builders">
4327 <heading>Package builders</heading>
4329 The following packages help with the package building process, general
4330 driving <prgn>dpkg-buildpackage</prgn> as well as handling supporting
4333 <sect1 id="cvs-buildpackage">
4334 <heading><package>cvs-buildpackage</package>
4336 <package>cvs-buildpackage</package> provides the capability to inject
4337 or import Debian source packages into a CVS repository, build a Debian
4338 package from the CVS repository, and helps in integrating upstream
4339 changes into the repository.
4341 These utilities provide an infrastructure to facilitate the use of CVS
4342 by Debian maintainers. This allows one to keep separate CVS branches
4343 of a package for <em>stable</em>, <em>unstable</em> and possibly
4344 <em>experimental</em> distributions, along with the other benefits of
4345 a version control system.
4348 <sect1 id="debootstrap">
4349 <heading><package>debootstrap</package></heading>
4351 The <package>debootstrap</package> package and script allows you to
4352 "bootstrap" a Debian base system into any part of your file-system.
4353 By "base system", we mean the bare minimum of packages required to
4354 operate and install the rest of the system.
4356 Having a system like this can be useful in many ways. For instance,
4357 you can <prgn>chroot</prgn> into it if you want to test your build
4358 depends. Or, you can test how your package behaves when installed
4359 into a bare base system. Chroot builders use this package, see below.
4362 <sect1 id="pbuilder">
4363 <heading><package>pbuilder</package></heading>
4365 <package>pbuilder</package> constructs a chrooted system, and builds a
4366 package inside the chroot. It is very useful to check that a package's
4367 build-dependencies are correct, and to be sure that unnecessary and
4368 wrong build dependencies will not exist in the resulting package.</p>
4370 A related package is <package>pbuilder-uml</package>, which goes even
4371 further build doing the build within User-mode-linux.</p>
4375 <heading><package>sbuild</package></heading>
4377 <package>sbuild</package> is another automated builder. It can use
4378 chrooted environments as well. It can be used stand-alone, or as part
4379 of a networked, distributed build environment. As the latter, it is
4380 part of the system used by porters to build binary packages for all
4381 the available architectures. See <ref id="buildd"> for more
4382 information, and <url id="&url-buildd;"> to see the system in
4387 <sect id="uploaders">
4388 <heading>Package uploaders</heading>
4390 The following packages help automate or simplify the process of
4391 uploading packages into the official archive.</p>
4393 <sect1 id="dupload">
4394 <heading><package>dupload</package></heading>
4396 <package>dupload</package> is a package and a script to automatically
4397 upload Debian packages to the Debian archive, to log the upload, and
4398 to send mail about the upload of a package. You can configure it for
4399 new upload locations or methods.
4403 <heading><package>dput</package></heading>
4405 The <package>dput</package> package and script does much the same
4406 thing as <package>dupload</package>, but in a different way. It has
4407 some features over <package>dupload</package>, such as the ability to
4408 check the GnuPG signature and checksums before uploading, and the
4409 possibility of running <prgn>dinstall</prgn> in dry-run mode after the
4414 <sect id="tools-maint-automate">
4415 <heading>Maintenance automation</heading>
4417 The following tools help automate different maintenance tasks, from
4418 adding changelog entries or signature lines, looking up bugs in Emacs,
4419 to making use of the newest and official use of
4420 <file>config.sub</file>.</p>
4422 <sect1 id="devscripts">
4423 <heading><package>devscripts</package></heading>
4425 <package>devscripts</package> is a package containing wrappers
4426 and tools which are very helpful for maintaining your Debian
4427 packages. Example scripts include <prgn>debchange</prgn> and
4428 <prgn>dch</prgn>, which manipulate your <file>debian/changelog</file>
4429 file from the command-line, and <prgn>debuild</prgn>, which is a
4430 wrapper around <prgn>dpkg-buildpackage</prgn>. The <prgn>bts</prgn>
4431 utility is also very helpful to update the state of bug reports on the
4432 command line. <prgn>uscan</prgn> can be used to watch for new upstream
4433 versions of your packages. The <prgn>debrsign</prgn> can be used to
4434 remotely sign a package prior to upload, which is nice when the
4435 machine you build the package on is different from where your GPG keys
4438 See the <manref name="devscripts" section="1"> manual page for a
4439 complete list of available scripts.</p>
4442 <sect1 id="autotools-dev">
4443 <heading><package>autotools-dev</package></heading>
4445 Contains best practices for people maintaining packages that use
4446 <prgn>autoconf</prgn> and/or <prgn>automake</prgn>. Also contains
4447 canonical <file>config.sub</file> and <file>config.guess</file> files
4448 which are known to work on all Debian ports.</p>
4451 <sect1 id="dpkg-repack">
4452 <heading><package>dpkg-repack</package></heading>
4454 <prgn>dpkg-repack</prgn> creates Debian package file out of a package
4455 that has already been installed. If any changes have been made to the
4456 package while it was unpacked (e.g., files in <file>/etc</file> were
4457 modified), the new package will inherit the changes.</p>
4459 This utility can make it easy to copy packages from one computer to
4460 another, or to recreate packages that are installed on your system
4461 but no longer available elsewhere, or to store the current state of a
4462 package before you upgrade it.</p>
4466 <heading><package>alien</package></heading>
4468 <prgn>alien</prgn> converts binary packages between various packaging
4469 formats, including Debian, RPM (RedHat), LSB (Linux Standard Base),
4470 Solaris and Slackware packages.</p>
4473 <sect1 id="debsums">
4474 <heading><package>debsums</package></heading>
4476 <prgn>debsums</prgn> checks installed packages against their MD5 sums.
4477 Note that not all packages have MD5 sums, since they aren't required
4481 <sect1 id="dpkg-dev-el">
4482 <heading><package>dpkg-dev-el</package></heading>
4484 <package>dpkg-dev-el</package> is an Emacs lisp package which provides
4485 assistance when editing some of the files in the <file>debian</file>
4486 directory of your package. For instance, when editing
4487 <file>debian/changelog</file>, there are handy functions for
4488 finalizing a version and listing the package's current bugs.</p>
4491 <sect1 id="dpkg-depcheck">
4492 <heading><package>dpkg-depcheck</package></heading>
4494 <prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package>
4495 package, <ref id="devscripts">)
4496 runs a command under <prgn>strace</prgn> to determine all the packages that
4497 were used by the said command.
4499 For Debian packages, this is useful when you have to compose a
4500 <tt>Build-Depends</tt> line for your new package: running the build
4501 process through <prgn>dpkg-depcheck</prgn> will provide you with a
4502 good first approximation of the build-dependencies. For example:
4504 dpkg-depcheck -b debian/rules build
4507 <prgn>dpkg-depcheck</prgn> can also be used to check for run-time
4508 dependencies, especially if your package uses exec(2) to run other
4511 For more information please see <manref name="dpkg-depcheck" section="1">.
4517 <sect id="tools-porting">
4518 <heading>Porting tools</heading>
4520 The following tools are helpful for porters and for
4521 cross-compilation.</p>
4523 <sect1 id="quinn-diff">
4524 <heading><package>quinn-diff</package>
4526 <package>quinn-diff</package> is used to locate the differences from
4527 one architecture to another. For instance, it could tell you which
4528 packages need to be ported for architecture <var>Y</var>, based on
4529 architecture <var>X</var>.
4531 <sect1 id="dpkg-cross">
4532 <heading><package>dpkg-cross</package>
4534 <package>dpkg-cross</package> is a tool for installing libraries and
4535 headers for cross-compiling in a way similar to
4536 <package>dpkg</package>. Furthermore, the functionality of
4537 <prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
4538 enhanced to support cross-compiling.
4542 <sect id="tools-doc">
4543 <heading>Documentation and information</heading>
4545 The following packages provide information for maintainers or help
4546 with building documentation.
4548 <sect1 id="debiandoc-sgml">
4549 <heading><package>debiandoc-sgml</package></heading>
4551 <package>debiandoc-sgml</package> provides the DebianDoc SGML DTD,
4552 which is commonly used for Debian documentation. This manual, for
4553 instance, is written in DebianDoc. It also provides scripts for
4554 building and styling the source to various output formats.</p>
4556 Documentation for the DTD can be found in the
4557 <package>debiandoc-sgml-doc</package> package.</p>
4560 <sect1 id="debian-keyring">
4561 <heading><package>debian-keyring</package></heading>
4563 Contains the public GPG and PGP keys of Debian developers. See <ref
4564 id="key-maint"> and the package documentation for more
4568 <sect1 id="debview">
4569 <heading><package>debview</package></heading>
4571 <package>debview</package> provides an Emacs mode for viewing Debian
4572 binary packages. This lets you examine a package without unpacking
4577 <!-- FIXME: add the following
4580 dbs (referred to above)
4581 dpatch (referred to above)
4598 debaux: too new, unmaintained?
4599 dh-make-perl: too new, unmaintained?
4606 <!-- Keep this comment at the end of the file
4611 sgml-minimize-attributes:nil
4612 sgml-always-quote-attributes:t
4614 sgml-indent-data:nil
4615 sgml-parent-document:nil
4616 sgml-exposed-tags:nil
4617 sgml-declaration:nil
4618 sgml-local-catalogs:nil
4619 sgml-local-ecat-files:nil