chiark / gitweb /
c833b914c7db91939e45c1150f49472ae6d2b764
[developers-reference.git] / developers-reference.sgml
1 <!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
2   <!-- include version information so we don't have to hard code it
3        within the document -->
4   <!entity % versiondata SYSTEM "version.ent"> %versiondata;
5   <!-- common, language independant entities -->
6   <!entity % commondata  SYSTEM "common.ent" > %commondata;
7   <!-- CVS revision of this document -->
8   <!entity cvs-rev "$Revision: 1.85 $">
9
10   <!-- if you are translating this document, please notate the RCS
11        revision of the developers reference here -->
12   <!--
13     <!entity cvs-en-rev "X.YY">
14     -->
15 ]>
16 <debiandoc>
17 <!--
18  TODO:
19   - bugs in upstream versions should be reported upstream!
20   - add information on how to get accounts on different architectures
21   - talk about CVS access, other ways to submit problems
22   - add information on how you can contribute w/o being an official
23     developer
24   - "official port maintainer" ? (cf. glibc-pre2.1)
25  -->
26
27   <book>
28
29       <title>Debian Developer's Reference
30       <author>Adam Di Carlo, current maintainer <email>aph@debian.org</email>
31       <author>Christian Schwarz <email>schwarz@debian.org</email>
32       <author>Ian Jackson <email>ijackson@gnu.ai.mit.edu</email>
33       <version>ver. &version;, &date-en;
34
35       <copyright>
36         <copyrightsummary>
37 copyright &copy;1998 &ndash 2001 Adam Di Carlo</copyrightsummary>
38         <copyrightsummary>
39 copyright &copy;1997, 1998 Christian Schwarz</copyrightsummary>
40         <p>
41 This manual is free software; you may redistribute it and/or modify it
42 under the terms of the GNU General Public License as published by the
43 Free Software Foundation; either version 2, or (at your option) any
44 later version.
45         <p>
46 This is distributed in the hope that it will be useful, but
47 <em>without any warranty</em>; without even the implied warranty of
48 merchantability or fitness for a particular purpose.  See the GNU
49 General Public License for more details.
50         <p>
51 A copy of the GNU General Public License is available as &file-GPL; in
52 the &debian-formal; distribution or on the World Wide Web at <url
53 id="&url-gpl;" name="the GNU website">.  You can also obtain it by
54 writing to the &fsf-addr;.
55
56     <toc detail="sect2">
57
58     <chapt id="scope">Scope of This Document
59       <p>
60 The purpose of this document is to provide an overview of the
61 recommended procedures and the available resources for Debian
62 developers.
63       <p>
64 The procedures discussed within include how to become a maintainer
65 (<ref id="new-maintainer">); how to upload new packages (<ref
66 id="upload">); how and when to do ports and interim releases of other
67 maintainers' packages (<ref id="nmu">); how to move, remove, or orphan
68 packages (<ref id="archive-manip">); and how to handle bug reports
69 (<ref id="bug-handling">).
70       <p>
71 The resources discussed in this reference include the mailing lists
72 and servers (<ref id="servers">); a discussion of the structure of the
73 Debian archive (<ref id="archive">); explanation of the different
74 servers which accept package uploads (<ref id="upload-ftp-master">); and a
75 discussion of resources which can help maintainers with the quality of
76 their packages (<ref id="tools">).
77       <p>
78 It should be clear that this reference does not discuss the technical
79 details of the Debian package nor how to generate Debian packages.
80 Nor does this reference detail the standards to which Debian software
81 must comply.  All of such information can be found in the <url
82 id="&url-debian-policy;" name="Debian Policy Manual">.
83       <p>
84 Furthermore, this document is <em>not an expression of formal
85 policy</em>.  It contains documentation for the Debian system and
86 generally agreed-upon best practices.  Thus, it is what is called a
87 ``normative'' document.
88
89
90     <chapt id="new-maintainer">Applying to Become a Maintainer
91         
92       <sect>Getting started
93         <p>
94 So, you've read all the documentation, you understand what everything
95 in the <package>hello</package> example package is for, and you're about to
96 Debianize your favourite piece of software.  How do you actually
97 become a Debian developer so that your work can be incorporated into
98 the Project?
99         <p>
100 Firstly, subscribe to &email-debian-devel; if you haven't already.
101 Send the word <tt>subscribe</tt> in the <em>Subject</em> of an email
102 to &email-debian-devel-req;.  In case of problems, contact the list
103 administrator at &email-listmaster;.  More information on available
104 mailing lists can be found in <ref id="mailing-lists">.
105         <p>
106 You should subscribe and lurk (that is, read without posting) for a
107 bit before doing any coding, and you should post about your intentions
108 to work on something to avoid duplicated effort.
109         <p>
110 Another good list to subscribe to is &email-debian-mentors;.  See <ref
111 id="mentors"> for details.  The IRC channel <tt>#debian</tt> on the
112 Linux People IRC network (e.g., <tt>irc.debian.org</tt>) can also be
113 helpful.
114
115         <p>
116 When you know how you want to contribute to &debian-formal;, you
117 should get in contact with existing Debian maintainers who are working
118 on similar tasks.  That way, you can learn from experienced developers.
119 For example, if you are interested in packaging existing software for
120 Debian you should try to get a sponsor.  A sponsor will work together
121 with you on your package and upload it to the Debian archive once he
122 is happy with the packaging work you have done.  You can find a sponsor
123 by mailing the &email-debian-mentors; mailing list, describing your
124 package and yourself and asking for a sponsor (see <ref id="sponsoring">
125 for more information on sponsoring).  On the other hand, if you are
126 interested in porting Debian to alternative architectures or kernels
127 you can subscribe to port specific mailing lists and ask there how to
128 get started.  Finally, if you are interested in documentation or
129 Quality Assurance (QA) work you can join maintainers already working on
130 these tasks and submit patches and improvements.
131  
132
133       <sect id="registering">Registering as a Debian developer
134         <p>
135 Before you decide to register with &debian-formal;, you will need to
136 read all the information available at the <url id="&url-newmaint;"
137 name="New Maintainer's Corner">.  It describes exactly the
138 preparations you have to do before you can register to become a Debian
139 developer.
140
141 For example, before you apply, you have to to read the <url
142 id="&url-social-contract;" name="Debian Social Contract">.
143 Registering as a developer means that you agree with and pledge to
144 uphold the Debian Social Contract; it is very important that
145 maintainers are in accord with the essential ideas behind
146 &debian-formal;.  Reading the <url id="&url-gnu-manifesto;" name="GNU
147 Manifesto"> would also be a good idea.
148         <p>
149 The process of registering as a developer is a process of verifying
150 your identity and intentions, and checking your technical skills.  As
151 the number of people working on &debian-formal; has grown to over
152 &number-of-maintainers; people and our systems are used in several
153 very important places we have to be careful about being compromised.
154 Therefore, we need to verify new maintainers before we can give them
155 accounts on our servers and let them upload packages.
156         <p>
157 Before you actually register you should have shown that you can do
158 competent work and will be a good contributor.  You can show this by
159 submitting patches through the Bug Tracking System or having a package
160 sponsored by an existing maintainer for a while.  Also, we expect that
161 contributors are interested in the whole project and not just in
162 maintaining their own packages.  If you can help other maintainers by
163 providing further information on a bug or even a patch, then do so!
164         <p>
165 Registration requires that you are familiar with Debian's philosophy
166 and technical documentation.  Furthermore, you need a GPG key which
167 has been signed by an existing Debian maintainer.  If your GPG key
168 is not signed yet, you should try to meet a Debian maintainer in
169 person to get your key signed.  There's a <url id="&url-gpg-coord;"
170 name="GPG Key Signing Coordination page"> which should help you find
171 a maintainer close to you (If you cannot find a Debian maintainer
172 close to you, there's an alternative way to pass the ID check.  You
173 can send in a photo ID signed with your GPG key.  Having your GPG
174 key signed is the preferred way, however.  See the
175 <url id="&url-newmaint-id;" name="identification page"> for more
176 information about these two options.)
177
178         <p>
179 If you do not have an OpenPGP key yet, generate one. Every developer
180 needs a OpenPGP key in order to sign and verify package uploads. You
181 should read the manual for the software you are using, since it has
182 much important information which is critical to its security.  Many
183 more security failures are due to human error than to software failure
184 or high-powered spy techniques.  See <ref id="key-maint"> for more
185 information on maintaining your public key.
186         <p>
187 Debian uses the <prgn>GNU Privacy Guard</prgn> (package
188 <package>gnupg</package> version 1 or better) as its baseline standard.
189 You can use some other implementation of OpenPGP as well.  Note that
190 OpenPGP is a open standard based on <url id="&url-rfc2440;" name="RFC
191 2440">.
192         <p>
193 The recommended public key algorithm for use in Debian development
194 work is the DSA (sometimes call ``DSS'' or ``DH/ElGamal'').  Other key
195 types may be used however.  Your key length must be at least 1024
196 bits; there is no reason to use a smaller key, and doing so would be
197 much less secure.  Your key must be signed with at least your own user
198 ID; this prevents user ID tampering.  <prgn>gpg</prgn> does this
199 automatically.
200         <p>
201 If your public key isn't on public key servers such as &pgp-keyserv;,
202 please read the documentation available locally in &file-keyservs;.
203 That document contains instructions on how to put your key on the
204 public key servers.  The New Maintainer Group will put your public key
205 on the servers if it isn't already there.
206         <p>
207 Due to export restrictions by the United States government some Debian
208 packages, including <package>gnupg</package>, are located on ftp sites
209 outside of the United States. You can find the current locations of
210 those packages at <url id="&url-readme-non-us;">.
211         <p>
212 Some countries restrict the use of cryptographic software by their
213 citizens.  This need not impede one's activities as a Debian package
214 maintainer however, as it may be perfectly legal to use cryptographic
215 products for authentication, rather than encryption purposes (as is
216 the case in France).  &debian-formal; does not require the use of
217 cryptography <em>qua</em> cryptography in any manner.  If you live in a
218 country where use of cryptography even for authentication is forbidden
219 then please contact us so we can make special arrangements.
220         <p>
221 To apply as a new maintainer, you need an existing Debian maintainer
222 to verify your application (an <em>advocate</em>).  After you have
223 contributed to Debian for a while, and you want to apply to become a
224 registered developer, an existing developer with whom you
225 have worked over the past months has to express his belief that you
226 can contribute to Debian successfully.
227         <p>
228 When you have found an advocate, have your GPG key signed and have
229 already contributed to Debian for a while, you're ready to apply.
230 You can simply register on our <url id="&url-newmaint-apply;"
231 name="application page">.  After you have signed up, your advocate
232 has to confirm your application.  When your advocate has completed
233 this step you will be assigned an Application Manager who will
234 go with you through the necessary steps of the New Maintainer process.
235 You can always check your status on the <url id="&url-newmaint-db;"
236 name="applications status board">.
237         <p>
238 For more details, please consult <url id="&url-newmaint;" name="New
239 Maintainer's Corner"> at the Debian web site.  Make sure that you
240 are familiar with the necessary steps of the New Maintainer process
241 before actually applying.  If you are well prepared, you can save
242 a lot of timer later on.
243
244
245       <sect id="mentors">Debian Mentors
246         <p>
247 The mailing list &email-debian-mentors; has been set up for novice
248 maintainers who seek help with initial packaging and other
249 developer-related issues.  Every new developer is invited to subscribe
250 to that list (see <ref id="mailing-lists"> for details).
251         <p>
252 Those who prefer one-on-one help (e.g., via private email) should also
253 post to that list and an experienced developer will volunteer to help.
254
255
256     <chapt id="developer-duties">Debian Developer's Duties
257
258       <sect id="user-maint">Maintaining Your Debian Information
259         <p>
260 There's a LDAP database containing many informations concerning all
261 developers, you can access it at <url id="&url-debian-db;">. You can
262 update your password (this password is propagated to most of the machines
263 that are accessible to you), your address, your country, the latitude and
264 longitude of the point where you live, phone and fax numbers, your
265 preferred shell, your IRC nickname, your web page and the email that
266 you're using as alias for your debian.org email. Most of the information
267 is not accessible to the public, for more details about this
268 database, please read its online documentation that you can find
269 at <url id="&url-debian-db-doc;">.
270         <p>
271 You have to keep the information available there up to date.
272
273       <sect id="key-maint">Maintaining Your Public Key
274         <p>
275 Be very careful with your private keys.  Do not place them on any
276 public servers or multiuser machines, such as
277 <tt>master.debian.org</tt>.  Back your keys up; keep a copy offline.
278 Read the documentation that comes with your software; read the <url
279 id="&url-pgp-faq;" name="PGP FAQ">.
280         <p>
281 If you add signatures to your public key, or add user identities, you
282 can update the debian keyring by sending your key to the key server at
283 <tt>&keyserver-host;</tt>.  If you need to add a completely new key,
284 or remove an old key, send mail to &email-debian-keyring;.  The same
285 key extraction routines discussed in <ref id="registering"> apply.
286         <p>
287 You can find a more in-depth discussion of Debian key maintenance in
288 the documentation for the <package>debian-keyring</package> package.
289
290       <sect id="inform-vacation">Going On Vacation Gracefully
291         <p>
292 Most developers take vacations, and usually this means that they can't
293 work for Debian and they can't be reached by email if any problem occurs.
294 The other developers need to know that you're on vacation so that they'll
295 do whatever is needed when such a problem occurs. Usually this means that
296 other developers are allowed to NMU (see <ref id="nmu">) your package if a
297 big problem (release critical bugs, security update, ...) occurs while
298 you're on vacation.
299         <p>
300 In order to inform the other developers, there's two things that you should do.
301 First send a mail to &email-debian-private; giving the period of time when
302 you will be on vacation.  You can also give some special instructions on what to
303 do if any problem occurs. Be aware that some people don't care for vacation
304 notices and don't want to read them; you should prepend "[VAC] " to the
305 subject of your message so that it can be easily filtered.
306         <p>
307 Next you should update your information
308 available in the Debian LDAP database and mark yourself as ``on vacation''
309 (this information is only accessible to debian developers). Don't forget
310 to remove the ``on vacation'' flag when you come back!
311
312       <sect id="upstream-coordination">Coordination With Upstream Developers
313         <p>
314 A big part of your job as Debian maintainer will be to stay in contact
315 with the upstream developers.  Debian users will sometimes report bugs
316 to the Bug Tracking System that are not specific to Debian.  You
317 must forward these bug reports to the upstream developers so that
318 they can be fixed in a future release.  It's not your job to fix
319 non-Debian specific bugs.  However, if you are able to do so, you are
320 encouraged to contribute to upstream development of the package by
321 providing a fix for the bug.  Debian users and developers will often
322 submit patches to fix upstream bugs, and you should evaluate and
323 forward these patches upstream.
324         <p>
325 If you need to modify the upstream sources in order to build a policy
326 conformant package, then you should propose a nice fix to the upstream
327 developers which can be included there, so that you won't have to
328 modify the sources of the next upstream version. Whatever changes you
329 need, always try not to fork from the upstream sources.
330
331       <sect id="rc-bugs">Managing Release Critical Bugs
332         <p>
333 Release Critical Bugs (RCB) are all bugs that have severity
334 <em>critical</em>, <em>grave</em> or <em>serious</em>.
335 Those bugs can delay the Debian release
336 and/or can justify the removal of a package at freeze time. That's why
337 these bugs need to be corrected as quickly as possible.  You must be
338 aware that some developers who are part of the <url
339 id="&url-debian-qa;" name="Debian Quality Assurance"> effort are
340 following those bugs and try to help you whenever they are able. But if
341 you can't fix such bugs within 2 weeks, you should either ask for help
342 by sending a mail to the Quality Assurance (QA) group
343 &email-debian-qa;, or explain your difficulties and present a plan to fix
344 them by sending a mail to the proper bug report. Otherwise, people
345 from the QA group may want to do a Non-Maintainer Upload (see
346 <ref id="nmu">) after trying to contact you (they might not wait as long as
347 usual before they do their NMU if they have seen no recent activity from you
348 in the BTS).
349
350       <sect id="qa-effort">Quality Assurance Effort
351         <p>
352 Even though there is a dedicated group of people for Quality
353 Assurance, QA duties are not reserved solely for them. You can
354 participate in this effort by keeping your packages as bug-free as
355 possible, and as lintian-clean (see <ref id="lintian-reports">) as
356 possible. If you do not find that possible, then you should consider
357 orphaning some of your packages (see <ref
358 id="orphaning">). Alternatively, you may ask the help of other people
359 in order to catch up the backlog of bugs that you have (you can ask
360 for help on &email-debian-qa; or &email-debian-devel;).
361
362     <sect id="mia-qa">Dealing with unreachable maintainers
363       <p>
364 If you notice that a package is lacking maintenance, you should
365 make sure the maintainer is active and will continue to work on
366 his packages. Try contacting him yourself.
367       <p>
368 If you do not get a reply after a few weeks you should collect all 
369 useful information about this maintainer. Start by logging into 
370 the <url id="&url-debian-db;" name="Debian Developer's Database">
371 and doing a full search to check whether the maintainer is on vacation
372 and when he was last seen. Collect any important package names
373 he maintains and any Release Critical bugs filled against them.
374       <p>
375 Send all this information to &email-debian-qa;, in order to let the 
376 QA people do whatever is needed.
377
378       <sect>Retiring Gracefully
379         <p>
380 If you choose to leave the Debian project, you should make sure you do
381 the following steps:
382 <enumlist>
383             <item>
384 Orphan all your packages, as described in <ref id="orphaning">.
385             <item>
386 Send an email about how you are leaving the project to
387 &email-debian-private;.
388             <item>
389 Notify the Debian key ring maintainers that you are leaving by
390 emailing to &email-debian-keyring;.
391           </enumlist>
392
393
394     <chapt id="servers">Mailing Lists, Servers, and Other Machines
395       <p>
396 In this chapter you will find a very brief road map of the Debian
397 mailing lists, the main Debian servers, and other Debian machines
398 which may be available to you as a developer.
399
400       <sect id="mailing-lists">Mailing lists
401         <p>
402 The mailing list server is at <tt>&lists-host;</tt>.  Mail
403 <tt>debian-<var>foo</var>-REQUEST@&lists-host;</tt>, where
404 <tt>debian-<var>foo</var></tt> is the name of the list, with the word
405 <tt>subscribe</tt> in the <em>Subject</em> to subscribe to the list or
406 <tt>unsubscribe</tt> to unsubscribe.  More detailed instructions on
407 how to subscribe and unsubscribe to the mailing lists can be found at
408 <url id="&url-debian-lists-subscribe;">, <url id="&url-debian-lists;">
409 or locally in &file-mail-lists; if you have the
410 <package>doc-debian</package> package installed.
411         <p>
412 When replying to messages on the mailing list, please do not send a
413 carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
414 request to be copied.  Anyone who posts to a mailing list should read
415 it to see the responses.
416         <p>
417 The following are the core Debian mailing lists: &email-debian-devel;,
418 &email-debian-policy;, &email-debian-user;, &email-debian-private;,
419 &email-debian-announce;, and &email-debian-devel-announce;.  All
420 developers are expected to be subscribed to at least
421 &email-debian-devel-announce;.  There are
422 other mailing lists available for a variety of special topics; see
423 <url id="&url-debian-lists-subscribe;"> for a list.  Cross-posting
424 (sending the same message to multiple lists) is discouraged.
425         <p>
426 &email-debian-private; is a special mailing list for private
427 discussions amongst Debian developers.  It is meant to be used for
428 posts which for whatever reason should not be published publically.
429 As such, it is a low volume list, and users are urged not to use
430 &email-debian-private; unless it is really necessary.  Moreover, do
431 <em>not</em> forward email from that list to anyone.
432         <p>
433 &email-debian-email; is a special mailing list used as a grab-bag 
434 for Debian related correspondence such as contacting upstream authors
435 about licenses, bugs, etc. or discussing the project with others where it
436 might be useful to have the discussion archived somewhere.
437         <p>
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
440 posting messages.
441         <p>
442 Online archives of mailing lists are available at <url
443 id="&url-lists-archives;">.
444
445
446       <sect id="server-machines">Debian servers
447         <p>
448 Debian servers are well known servers which serve critical functions
449 in the Debian project.  Every developer should know what these servers
450 are and what they do.
451         <p>
452 If you have a problem with the operation of a Debian server, and you
453 think that the system operators need to be notified of this problem,
454 please find the contact address for the particular machine at <url
455 id="&url-devel-machines;">.  If you have a non-operating problems
456 (such as packages to be remove, suggestions for the web site, etc.),
457 generally you'll report a bug against a ``pseudo-package''.  See <ref
458 id="submit-bug"> for information on how to submit bugs.
459
460       <sect1 id="servers-master">The master server
461         <p>
462 <tt>master.debian.org</tt> is the canonical location for the Bug
463 Tracking System (BTS).  If you plan on doing some statistical analysis
464 or processing of Debian bugs, this would be the place to do it.
465 Please describe your plans on &email-debian-devel; before implementing
466 anything, however, to reduce unnecessary duplication of effort or
467 wasted processing time.
468         <p>
469 All Debian developers have accounts on <tt>master.debian.org</tt>.
470 Please take care to protect your password to this machine.  Try to
471 avoid login or upload methods which send passwords over the Internet
472 in the clear.
473         <p>
474 If you find a problem with <tt>master.debian.org</tt> such as disk
475 full, suspicious activity, or whatever, send an email to
476 &email-debian-admin;.
477
478       <sect1 id="servers-ftp-master">The ftp-master server
479         <p>
480 The ftp-master server, <tt>ftp-master.debian.org</tt> (or
481 <tt>auric.debian.org</tt>), holds the canonical copy of the Debian
482 archive (excluding the non-U.S. packages). Generally, package uploads
483 go to this server; see <ref id="upload">.
484         <p>
485 Problems with the Debian FTP archive generally need to be reported as
486 bugs against the <package>ftp.debian.org</package> pseudo-package or
487 an email to &email-ftpmaster;, but also see the procedures in
488 <ref id="archive-manip">.
489
490       <sect1 id="servers-www">The WWW server
491         <p>
492 The main web server, <tt>www.debian.org</tt>, is also known as
493 <tt>klecker.debian.org</tt>.  All developers are given accounts on this
494 machine.
495         <p>
496 If you have some Debian-specific information which you want to serve
497 up on the web, you can do this by putting material in the
498 <file>public_html</file> directory under your home directory.  You should
499 do this on <tt>klecker.debian.org</tt>. Any material you put in those areas
500 are accessible via the URL
501 <tt>http://people.debian.org/~<var>user-id</var>/</tt>.
502 You should only use this particular location because it will be backed up,
503 whereas on other hosts it won't. Please do not put any material on Debian
504 servers not relating to Debian, unless you have prior permission.
505 Send mail to &email-debian-devel; if you have any questions.
506         <p>
507 If you find a problem with the Debian web server, you should generally
508 submit a bug against the pseudo-package,
509 <package>www.debian.org</package>.  First check whether or not someone
510 else has already reported the problem on the
511 <url id="http://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
512
513
514       <sect1 id="servers-cvs">The CVS server
515         <p>
516 <tt>cvs.debian.org</tt> is also known as <tt>klecker.debian.org</tt>,
517 discussed above.  If you need to use a publically accessible CVS
518 server, for instance, to help coordinate work on a package between
519 many different developers, you can request a CVS area on the server.
520           <p>
521 Generally, <tt>cvs.debian.org</tt> offers a combination of local CVS
522 access, anonymous client-server read-only access, and full
523 client-server access through <prgn>ssh</prgn>.  Also, the CVS area can
524 be accessed read-only via the Web at <url id="&url-cvsweb;">.
525         <p>
526 To request a CVS area, send a request via email to
527 &email-debian-admin;.  Include the name of the requested CVS area,
528 Debian account should own the CVS root area, and why you need it.
529
530
531       <sect1 id="servers-mirrors">Mirrors of Debian servers
532         <p>
533 The web and FTP servers have several mirrors available.  Please do not
534 put heavy load on the canonical FTP or web servers.  Ideally, the
535 canonical servers only mirror out to a first tier of mirrors, and all
536 user access is to the mirrors.  This allows Debian to better spread
537 its bandwidth requirements over several servers and networks.  Note
538 that newer push mirroring techniques ensure that mirrors are as
539 up-to-date as they can be.
540         <p>
541 The main web page listing the available public FTP (and, usually,
542 HTTP) servers can be found at <url id="&url-debian-mirrors;">.  More
543 information concerning Debian mirrors can be found at <url
544 id="&url-debian-mirroring;">.  This useful page includes information
545 and tools which can be helpful if you are interested in setting up
546 your own mirror, either for internal or public access.
547         <p>
548 Note that mirrors are generally run by third-parties who are
549 interested in helping Debian.  As such, developers generally do not
550 have accounts on these machines.
551
552
553       <sect id="other-machines">Other Debian Machines
554         <p>
555 There are other Debian machines which may be made available to you.
556 You can use these for Debian-related purposes as you see fit.  Please
557 be kind to system administrators, and do not use up tons and tons of
558 disk space, network bandwidth, or CPU without first getting the
559 approval of the local maintainers.  Usually these machines are run by
560 volunteers.  Generally, these machines are for porting activities.
561         <p>
562 Aside from the servers mentioned in <ref id="server-machines">, there
563 is a list of machines available to Debian developers at <url
564 id="&url-devel-machines;">.
565
566
567
568     <chapt id="archive">The Debian Archive
569
570       <sect>Overview
571         <p>
572 The &debian-formal; distribution consists of a lot of Debian packages
573 (<tt>.deb</tt>'s, currently around &number-of-pkgs;) and a few
574 additional files (documentation, installation disk images, etc.).
575         <p>
576 Here is an example directory tree of a complete Debian archive:
577         <p>
578 &sample-dist-dirtree;
579         <p>
580 As you can see, the top-level directory contains two directories,
581 <tt>dists/</tt> and <tt>pool/</tt>. The latter is a ``pool'' in which the
582 packages actually are, and which is handled by the archive maintenance
583 database and the accompanying programs. The former contains the
584 distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>.
585 Each of those distribution directories is divided in equivalent
586 subdirectories purpose of which is equal, so we will only explain how it
587 looks in stable. The <tt>Packages</tt> and <tt>Sources</tt> files in the
588 distribution subdirectories can reference files in the <tt>pool/</tt>
589 directory.
590         <p>
591 <tt>dists/stable</tt> contains three directories, namely <em>main</em>,
592 <em>contrib</em>, and <em>non-free</em>.
593         <p>
594 In each of the areas, there is a directory with the source packages
595 (<tt>source</tt>), a directory for each supported architecture
596 (<tt>binary-i386</tt>, <tt>binary-m68k</tt>, etc.), and a directory
597 for architecture independent packages (<tt>binary-all</tt>).
598         <p>
599 The <em>main</em> area contains additional directories which holds
600 the disk images and some essential pieces of documentation required
601 for installing the Debian distribution on a specific architecture
602 (<tt>disks-i386</tt>, <tt>disks-m68k</tt>, etc.).
603         <p>
604 The <em>binary-*</em> and <em>source</em> directories are divided
605 further into <em>subsections</em>.
606
607
608       <sect>Sections
609         <p>
610 The <em>main</em> section of the Debian archive is what makes up the
611 <strong>official &debian-formal; distribution</strong>.  The
612 <em>main</em> section is official because it fully complies with all
613 our guidelines.  The other two sections do not, to different degrees;
614 as such, they are <strong>not</strong> officially part of
615 &debian-formal;.
616         <p>
617 Every package in the main section must fully comply with the <url
618 id="&url-dfsg;" name="Debian Free Software Guidelines"> (DFSG) and
619 with all other policy requirements as described in the <url
620 id="&url-debian-policy;" name="Debian Policy Manual">.  The DFSG is
621 our definition of ``free software.'' Check out the Debian Policy
622 Manual for details.
623         <p>
624 Packages in the <em>contrib</em> section have to comply with the DFSG,
625 but may fail other requirements.  For instance, they may depend on
626 non-free packages.
627         <p>
628 Packages which do not apply to the DFSG are placed in the
629 <em>non-free</em> section. These packages are not considered as part
630 of the Debian distribution, though we support their use, and we
631 provide infrastructure (such as our bug-tracking system and mailing
632 lists) for non-free software packages.
633         <p>
634 The <url id="&url-debian-policy;" name="Debian Policy Manual">
635 contains a more exact definition of the three sections. The above
636 discussion is just an introduction.
637         <p>
638 The separation of the three sections at the top-level of the archive
639 is important for all people who want to distribute Debian, either via
640 FTP servers on the Internet or on CD-ROMs: by distributing only the
641 <em>main</em> and <em>contrib</em> sections, one can avoid any legal
642 risks.  Some packages in the <em>non-free</em> section do not allow
643 commercial distribution, for example.
644         <p>
645 On the other hand, a CD-ROM vendor could easily check the individual
646 package licenses of the packages in <em>non-free</em> and include as
647 many on the CD-ROMs as he's allowed to. (Since this varies greatly from
648 vendor to vendor, this job can't be done by the Debian developers.)
649
650
651       <sect>Architectures
652         <p>
653 In the first days, the Linux kernel was only available for the Intel
654 i386 (or greater) platforms, and so was Debian. But when Linux became
655 more and more popular, the kernel was ported to other architectures,
656 too.
657         <p>
658 The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola
659 680x0 (like Atari, Amiga and Macintoshes), MIPS, and PowerPC.  The
660 Linux 2.2 kernel supports even more architectures, including ARM and
661 UltraSPARC.  Since Linux supports these platforms, Debian decided that
662 it should, too.  Therefore, Debian has ports underway; in fact, we
663 also have ports underway to non-Linux kernel.  Aside from
664 <em>i386</em> (our name for Intel x86), there is <em>m68k</em>,
665 <em>alpha</em>, <em>powerpc</em>, <em>sparc</em>, <em>hurd-i386</em>,
666 and <em>arm</em>, as of this writing.
667         <p>
668 &debian-formal; 1.3 is only available as <em>i386</em>.  Debian 2.0
669 shipped for <em>i386</em> and <em>m68k</em> architectures.  Debian 2.1
670 ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and
671 <em>sparc</em> architectures.  Debian 2.2 adds support for the
672 <em>powerpc</em> and <em>arm</em> architectures.
673         <p>
674 Information for developers or uses about the specific ports are
675 available at the <url id="&url-debian-ports;" name="Debian Ports web
676 pages">.
677
678
679       <sect>Subsections
680         <p>
681 The sections <em>main</em>, <em>contrib</em>, and <em>non-free</em>
682 are split into <em>subsections</em> to simplify the installation
683 process and the maintainance of the archive.  Subsections are not
684 formally defined, except perhaps the `base' subsection.
685 Subsections simply exist to simplify the organization and browsing of
686 available packages.  Please check the current Debian distribution to
687 see which sections are available.
688         <p>
689 Note however that with the introduction of package pools (see the top-level
690 <em>pool/</em> directory), the subsections in the form of subdirectories
691 will eventually cease to exist. They will be kept in the packages' `Section'
692 header fields, though.
693
694       <sect>Packages
695         <p>
696 There are two types of Debian packages, namely <em>source</em> and
697 <em>binary</em> packages.
698         <p>
699 Source packages consist of either two or three files: a <tt>.dsc</tt>
700 file, and either a <tt>.tar.gz</tt> file or both an
701 <tt>.orig.tar.gz</tt> and a <tt>.diff.gz</tt> file.
702         <p>
703 If a package is developed specially for Debian and is not distributed
704 outside of Debian, there is just one <tt>.tar.gz</tt> file which
705 contains the sources of the program.  If a package is distributed
706 elsewhere too, the <tt>.orig.tar.gz</tt> file stores the so-called
707 <em>upstream source code</em>, that is the source code that's
708 distributed from the <em>upstream maintainer</em> (often the author of
709 the software). In this case, the <tt>.diff.gz</tt> contains the
710 changes made by the Debian maintainer.
711         <p>
712 The <tt>.dsc</tt> lists all the files in the source package together
713 with checksums (<prgn>md5sums</prgn>) and some additional info about
714 the package (maintainer, version, etc.).
715
716
717       <sect>Distribution directories
718         <p>
719 The directory system described in the previous chapter is itself
720 contained within <em>distribution directories</em>.  Each
721 distribution is actually contained in the <tt>pool</tt> directory in the
722 top-level of the Debian archive itself.
723         <p>
724 To summarize, the Debian archive has a root directory within an FTP
725 server.  For instance, at the mirror site,
726 <ftpsite>ftp.us.debian.org</ftpsite>, the Debian archive itself is
727 contained in <ftppath>/debian</ftppath>, which is a common location
728 (another is <tt>/pub/debian</tt>).
729         <p>
730 A distribution is comprised of Debian source and binary packages, and the
731 respective <tt>Sources</tt> and <tt>Packages</tt> index files, containing
732 the header information from all those packages. The former are kept in the
733 <tt>pool/</tt> directory, while the latter are kept in the <tt>dists/</tt>
734 directory of the archive (because of backwards compatibility).
735
736
737         <sect1 id="sec-dists">Stable, testing, and unstable
738         <p>
739 There are always distributions called <em>stable</em> (residing in
740 <tt>dists/stable</tt>), one called <em>testing</em> (residing in
741 <tt>dists/testing</tt>), and one called <em>unstable</em> (residing in
742 <tt>dists/unstable</tt>). This reflects the development process of the
743 Debian project.
744         <p>
745 Active development is done in the <em>unstable</em> distribution
746 (that's why this distribution is sometimes called the <em>development
747 distribution</em>). Every Debian developer can update his or her
748 packages in this distribution at any time. Thus, the contents of this
749 distribution change from day-to-day. Since no special effort is done
750 to make sure everything in this distribution is working properly, it is
751 sometimes ``unstable.''
752         <p>
753 Packages get copied from <em>unstable</em> to <em>testing</em> if they
754 satisfy certain criteria. To get into <em>testing</em> distribution, a
755 package needs to be in the archive for two weeks and not have any
756 release critical bugs. After that period, it will propagate into
757 <em>testing</em> as soon as anything it depends on is also added. This
758 process is automatic.  You can see some notes on this system as well
759 as <tt>update_excuses</tt> (describing which packages are valid
760 candidates, which are not, and why not) at <url
761 id="&url-testing-maint;">.
762         <p>
763 After a period of development, once the release manager deems fit, the
764 <em>testing</em> distribution is frozen, meaning that the policies
765 which control how packages move from <em>unstable</em> to testing are
766 tightened.  Packages which are too buggy are removed.  No changes are
767 allowed into <em>testing</em> except for bug fixes.  After some time
768 has elapsed, depending on progress, the <em>testing</em> distribution
769 goes into a `deep freeze', when no changes are made to it except those
770 needed for the installation system.  This is called a ``test cycle'',
771 and it can last up to two weeks. There can be several test cycles,
772 until the distribution is prepared for release, as decided by the
773 release manager.  At the end of the last test cycle, the
774 <em>testing</em> distribution is renamed to <em>stable</em>,
775 overriding the old <em>stable</em> distribution, which is removed at
776 that time (although it can be found at <tt>&archive-host;</tt>).
777         <p>
778 This development cycle is based on the assumption that the
779 <em>unstable</em> distribution becomes <em>stable</em> after passing a
780 period of being in <em>testing</em>.  Even once a distribution is
781 considered stable, a few bugs inevitably remain &mdash that's why the
782 stable distribution is updated every now and then. However, these
783 updates are tested very carefully and have to be introduced into the
784 archive individually to reduce the risk of introducing new bugs.  You
785 can find proposed additions to <em>stable</em> in the
786 <tt>proposed-updates</tt> directory.  Those packages in
787 <tt>proposed-updates</tt> that pass muster are periodically moved as a
788 batch into the stable distribution and the revision level of the
789 stable distribution is incremented (e.g., `1.3' becomes `1.3r1',
790 `2.0r2' becomes `2.0r3', and so forth).
791         <p>
792 Note that development under <em>unstable</em> continues during the
793 ``freeze'' period, since the <em>unstable</em> distribution remains in
794 place in parallel with <em>testing</em>.
795
796         <sect1>Experimental
797           <p>
798 The <em>experimental</em> distribution is a specialty distribution.
799 It is not a full distribution in the same sense as `stable' and
800 `unstable' are.  Instead, it is meant to be a temporary staging area
801 for highly experimental software where there's a good chance that the
802 software could break your system, or software that's just too unstable
803 even for the <em>unstable</em> distribution (but there is a reason to
804 package it nevertheless).  Users who download and install
805 packages from <em>experimental</em> are expected to have been duly
806 warned.  In short, all bets are off for the <em>experimental</em>
807 distribution.
808           <p>
809 If there is a chance that the software could do grave damage to a system,
810 it is likely to be better to put it into <em>experimental</em>.
811 For instance, an experimental compressed file system should probably go
812 into <em>experimental</em>.
813           <p>
814 Whenever there is a new upstream version of a package that introduces new
815 features but breaks a lot of old ones, it should either not be uploaded, or
816 be uploaded to <em>experimental</em>. A new, beta, version of some software
817 which uses completely different configuration can go into
818 <em>experimental</em>, at the maintainer's discretion. If you are working
819 on an incompatible or complex upgrade situation, you can also use
820 <em>experimental</em> as a staging area, so that testers can get early
821 access.
822           <p>
823 Some experimental software can still go into <em>unstable</em>, with a few
824 warnings in the description, but that isn't recommended because packages
825 from <em>unstable</em> are expected to propagate to <em>testing</em> and
826 thus to <em>stable</em>.
827           <p>
828 New software which isn't likely to damage your system can go directly into
829 <em>unstable</em>.
830           <p>
831 An alternative to <em>experimental</em> is to use your personal web space
832 on <tt>people.debian.org</tt> (<tt>klecker.debian.org</tt>).
833
834
835       <sect id="codenames">Release code names
836         <p>
837 Every released Debian distribution has a <em>code name</em>: Debian
838 1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0,
839 `hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; and Debian 3.0, `woody'.  There is also
840 a ``pseudo-distribution'', called `sid', which is the current
841 `unstable' distribution; since packages are moved from `unstable' to
842 `testing' as they approach stability, `sid' itself is never released.
843 As well as the usual contents of a Debian distribution, `sid' contains
844 packages for architectures which are not yet officially supported or
845 released by Debian.  These architectures are planned to be integrated
846 into the mainstream distribution at some future date.
847         <p>
848 Since Debian has an open development model (i.e., everyone can
849 participate and follow the development) even the `unstable' and `testing'
850 distributions are distributed to the Internet through the Debian FTP and
851 HTTP server network. Thus, if we had called the directory which contains
852 the release candidate version `testing', then we would have to rename it
853 to `stable' when the version is released, which would cause all FTP
854 mirrors to re-retrieve the whole distribution (which is quite large).
855         <p>
856 On the other hand, if we called the distribution directories
857 <em>Debian-x.y</em> from the beginning, people would think that Debian
858 release <em>x.y</em> is available. (This happened in the past, where a
859 CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development
860 version. That's the reason why the first official Debian release was
861 1.1, and not 1.0.)
862         <p>
863 Thus, the names of the distribution directories in the archive are
864 determined by their code names and not their release status (e.g.,
865 `slink').  These names stay the same during the development period and
866 after the release; symbolic links, which can be changed easily,
867 indicate the currently released stable distribution.  That's why the
868 real distribution directories use the <em>code names</em>, while
869 symbolic links for <em>stable</em>, <em>testing</em>, and
870 <em>unstable</em> point to the appropriate release directories.
871
872
873     <chapt id="upload">Package uploads
874
875       <sect>Announcing new packages
876         <p>
877 If you want to create a new package for the Debian distribution, you
878 should first check the <url id="&url-wnpp;" name="Work-Needing and
879 Prospective Packages (WNPP)"> list. Checking the WNPP list ensures that
880 no one is already working on packaging that software, and that effort is
881 not duplicated. Read the <url id="&url-wnpp;" name="WNPP web pages"> for
882 more information.
883         <p>
884 Assuming no one else is already working on your prospective package,
885 you must then submit a bug report (<ref id="submit-bug">) against the
886 pseudo package <tt>wnpp</tt> 
887 describing your plan to create a new package, including, but not
888 limiting yourself to, a description of the package, the license of the
889 prospective package and the current URL where it can be downloaded
890 from.
891         <p>
892 You should set the subject of the bug to ``ITP: <var>foo</var>
893 -- <var>short description</var>'', substituting the name of the new
894 package for <var>foo</var>.  The severity of the bug report must be set
895 to <em>wishlist</em>. If you feel it's necessary, send a copy to
896 &email-debian-devel; by putting the address in the <tt>X-Debbugs-CC:</tt> header
897 of the message (no, don't use <tt>CC:</tt>, because that way the message's subject
898 won't indicate the bug number).
899         <p>
900 Please include a <tt>Closes: bug#<var>nnnnn</var></tt> entry on the
901 changelog of the new package in order for the bug report to be
902 automatically closed once the new package is installed on the archive
903 (<ref id="upload-bugfix">).
904         <p>
905 There are a number of reasons why we ask maintainers to announce their
906 intentions:
907           <list compact>
908             <item>
909 It helps the (potentially new) maintainer to tap into the experience
910 of people on the list, and lets them know if anyone else is working
911 on it already.
912             <item>
913 It lets other people thinking about working on the package know that
914 there already is a volunteer, so efforts may be shared.
915             <item>
916 It lets the rest of the maintainers know more about the package than
917 the one line description and the usual changelog entry ``Initial release''
918 that gets posted to <tt>debian-devel-changes</tt>.
919             <item>
920 It is helpful to the people who live off unstable (and form our first
921 line of testers).  We should encourage these people.
922             <item>
923 The announcements give maintainers and other interested parties a
924 better feel of what is going on, and what is new, in the project.
925           </list>
926
927
928       <sect id="upload-checking">Checking the package prior to upload
929           <p>
930 Before you upload your package, you should do basic testing on it.  At
931 a minimum, you should try the following activities (you'll need to
932 have an older version of the same Debian package around):
933 <list>
934               <item>
935 Install the package and make sure the software works, or upgrade the
936 package from an older version to your new version if a Debian package
937 for it already exists.
938               <item>
939 Run <prgn>lintian</prgn> over the package.  You can run
940 <prgn>lintian</prgn> as follows: <tt>lintian -v
941 <var>package-version</var>.changes</tt>. This will check the source
942 package as well as the binary package.  If you don't understand the
943 output that <prgn>lintian</prgn> generates, try adding the <tt>-i</tt>
944 switch, which will cause <prgn>lintian</prgn> to output a very verbose
945 description of the problem.
946                 <p>
947 Normally, a package should <em>not</em> be uploaded if it causes lintian
948 to emit errors (they will start with <tt>E</tt>).
949                 <p>
950 For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
951               <item>
952 Downgrade the package to the previous version (if one exists) &mdash; this
953 tests the <tt>postrm</tt> and <tt>prerm</tt> scripts.
954               <item>
955 Remove the package, then reinstall it.
956             </list>
957
958
959       <sect>Generating the changes file
960           <p>
961 When a package is uploaded to the Debian FTP archive, it must be
962 accompanied by a <tt>.changes</tt> file, which gives directions to the
963 archive maintainers for its handling.  This is usually generated by
964 <prgn>dpkg-genchanges</prgn> during the normal package build process.
965           <p>
966 The changes file is a control file with the following fields:
967           <p>
968 &control-file-fields;
969           <p>
970 All of these fields are mandatory for a Debian upload.  See the list
971 of control fields in the <url id="&url-debian-policy;" name="Debian
972 Policy Manual"> for the contents of these fields.  You can close bugs
973 automatically using the <tt>Description</tt> field, see <ref
974 id="upload-bugfix">.
975
976
977         <sect1>The original source tarball
978           <p>
979 The first time a version is uploaded which corresponds to a particular
980 upstream version, the original source tar file should be uploaded and
981 included in the <tt>.changes</tt> file.  Subsequently, this very same
982 tar file should be used to build the new diffs and <tt>.dsc</tt>
983 files, and will not need to be re-uploaded.
984           <p>
985 By default, <prgn>dpkg-genchanges</prgn> and
986 <prgn>dpkg-buildpackage</prgn> will include the original source tar
987 file if and only if the Debian revision part of the source version
988 number is 0 or 1, indicating a new upstream version.  This behaviour
989 may be modified by using <tt>-sa</tt> to always include it or
990 <tt>-sd</tt> to always leave it out.
991           <p>
992 If no original source is included in the upload, the original
993 source tar-file used by <prgn>dpkg-source</prgn> when constructing the
994 <tt>.dsc</tt> file and diff to be uploaded <em>must</em> be
995 byte-for-byte identical with the one already in the archive.  If there
996 is some reason why this is not the case, the new version of the
997 original source should be uploaded, possibly by using the <tt>-sa</tt>
998 flag.
999
1000
1001         <sect1 id="upload-dist">Picking a distribution
1002           <p>
1003 The <tt>Distribution</tt> field, which originates from the first line of
1004 the <file>debian/changelog</file> file, indicates which distribution the
1005 package is intended for.
1006           <p>
1007 There are three possible values for this field: `stable', `unstable',
1008 and `experimental'. Normally, packages are uploaded into
1009 <em>unstable</em>.
1010           <p>
1011 You should avoid combining `stable' with others because of potential
1012 problems with library dependencies (for your package and for the package
1013 built by the build daemons for other architecture).
1014 See <ref id="upload-stable"> for more information on when and how to
1015 upload to <em>stable</em>.
1016           <p>
1017 It never makes sense to combine the <em>experimental</em> distribution
1018 with anything else.
1019
1020 <!-- 
1021           <sect2 id="upload-frozen">Uploading to <em>frozen</em>
1022             <p>
1023 The Debian freeze is a crucial time for Debian.  It is our chance to
1024 synchronize and stabilize our distribution as a whole.  Therefore,
1025 care must be taken when uploading to <em>frozen</em>.
1026             <p>
1027 It is tempting to always try to get the newest release of software
1028 into the release.  However, it's much more important that the system
1029 as a whole is stable and works as expected.
1030             <p>
1031 The watchword for uploading to <em>frozen</em> is <strong>no new
1032 code</strong>.  This is a difficult thing to quantify, so here are
1033 some guidelines:
1034             <p>
1035 <list>
1036                 <item>
1037 Fixes for bugs of severity <em>critical</em>, <em>grave</em>, or
1038 <em>serious</em> severity are always allowed for those packages that
1039 must exist in the final release
1040                 <item>
1041 <em>critical</em>, <em>grave</em>, and <em>serious</em> bug fixes are
1042 allowed for non-necessary packages but only if they don't add any new
1043 features
1044                 <item>
1045 important, normal and minor bug fixes are allowed (though discouraged)
1046 on all packages if and only if there are no new features
1047                 <item>
1048 wishlist fixes are not allowed (they are, after all, not really bugs)
1049                 <item>
1050 documentation bug fixes are allowed, since good documentation is
1051 important
1052               </list>
1053             <p>
1054 Experience has shown that there is statistically a 15% chance that
1055 every bug fix will introduce a new bug.  The introduction and
1056 discovery of new bugs either delays release or weakens the final
1057 product.  There is little correlation between the severity of the
1058 original bug fixed and the severity of the bug newly introduced by the
1059 fix.
1060
1061  -->
1062
1063
1064           <sect2 id="upload-stable">Uploading to <em>stable</em>
1065             <p>
1066 Uploading to <em>stable</em> means that the package will be placed into the
1067 <tt>proposed-updates</tt> directory of the Debian archive for further
1068 testing before it is actually included in <em>stable</em>.
1069             <p>
1070 Extra care should be taken when uploading to <em>stable</em>. Basically, a
1071 package should only be uploaded to stable if one of the following happens:
1072 <list>
1073         <item>a security problem (e.g. a Debian security advisory)
1074         <item>a truely critical functionality problem
1075         <item>the package becomes uninstallable
1076         <item>a released architecture lacks the package
1077 </list>
1078             <p>
1079 It is discouraged to change anything else in the package that isn't
1080 important, because even trivial fixes can cause bugs later on. Uploading
1081 new upstream versions to fix security problems is deprecated; applying the
1082 specific patch from the new upstream version to the old one ("backporting"
1083 the patch) is the right thing to do in most cases.
1084             <p>
1085 Packages uploaded to <em>stable</em> need to be compiled on systems running
1086 <em>stable</em>, so that their dependencies are limited to the libraries
1087 (and other packages) available in <em>stable</em>; for example, a package
1088 uploaded to <em>stable</em> that depends on a library package that only
1089 exists in unstable will be rejected. Making changes to dependencies of other
1090 packages (by messing with <tt>Provides</tt> or shlibs files), possibly making
1091 those other packages uninstallable, is strongly discouraged.
1092             <p>
1093 The Release Team (which can be reached at &email-debian-release;) will
1094 regularly evaluate the uploads in <em>proposed-updates</em> and decide if
1095 your package can be included in <em>stable</em>. Please be clear (and
1096 verbose, if necessary) in your changelog entries for uploads to
1097 <em>stable</em>, because otherwise the package won't be considered for
1098 inclusion.
1099
1100
1101
1102       <sect id="uploading">Uploading a package
1103
1104         <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
1105           <p>
1106 To upload a package, you need a personal account on
1107 <ftpsite>ftp-master.debian.org</ftpsite>, which you should have as an
1108 official maintainer. If you use <prgn>scp</prgn> or <prgn>rsync</prgn>
1109 to transfer the files, place them into <tt>&us-upload-dir;</tt>;
1110 if you use anonymous FTP to upload, place them into
1111 <ftppath>/pub/UploadQueue/</ftppath>.  Please note that you should transfer
1112 the changes file last.  Otherwise, your upload may be rejected because the
1113 archive maintenance software will parse the changes file and see that not
1114 all files have been uploaded.  If you don't want to bother with transfering
1115 the changes file last, you can simply copy your files to a temporary
1116 directory on <tt>ftp-master</tt> and then move them to
1117 <tt>&us-upload-dir;</tt>.
1118           <p>
1119 <em>Note:</em> Do not upload to <tt>ftp-master</tt> packages
1120 containing software that is export-controlled by the United States
1121 government, nor to the overseas upload queues on <tt>chiark</tt> or
1122 <tt>erlangen</tt>.  This prohibition covers almost all cryptographic
1123 software, and even sometimes software that contains ``hooks'' to
1124 cryptographic software, such as electronic mail readers that support
1125 PGP encryption and authentication.  Uploads of such software should go
1126 to <tt>non-us</tt> (see <ref id="upload-non-us">).  If you are not
1127 sure whether U.S. export controls apply to your package, post a
1128 message to &email-debian-devel; and ask.
1129           <p>
1130 You may also find the Debian packages <package>dupload</package> or
1131 <package>dput</package> useful
1132 when uploading packages.  These handy program are distributed with
1133 defaults for uploading via <prgn>ftp</prgn> to <tt>ftp-master</tt>,
1134 <tt>chiark</tt>, and <tt>erlangen</tt>.  It can also be configured to
1135 use <prgn>ssh</prgn> or <prgn>rsync</prgn>.  See <manref name="dupload"
1136 section="1">, <manref name="dupload" section="5"> and <manref name="dput"
1137 section="1"> for more information.
1138           <p>
1139 After uploading your package, you can check how the archive maintenance
1140 software will process it by running <prgn>dinstall</prgn> on your changes
1141 file: <example>dinstall -n foo.changes</example>
1142
1143         <sect1 id="upload-non-us">Uploading to <tt>non-US</tt> (pandora)
1144           <p>
1145 As discussed above, export controlled software should not be uploaded
1146 to <tt>ftp-master</tt>.  Instead, use <prgn>scp</prgn> or <prgn>rsync</prgn>
1147 to copy the package to <ftpsite>non-us.debian.org</ftpsite>, placing
1148 the files in <tt>&non-us-upload-dir;</tt>. By default, you can
1149 use the same account/password that works on <tt>ftp-master</tt>.
1150 If you use anonymous FTP to upload, place the files into
1151 <ftppath>/pub/UploadQueue/</ftppath>.
1152           <p>
1153 The program <prgn>dupload</prgn> comes with support for uploading to
1154 <tt>non-us</tt>; please refer to the documentation that comes with
1155 the program for details.
1156           <p>
1157 You can check your upload the same way it's done on <tt>ftp-master</tt>,
1158 with:
1159 <example>dinstall -n foo.changes</example>
1160           <p>
1161 Note that U.S. residents or citizens are subject to restrictions on
1162 export of cryptographic software. As of this writing, U.S. citizens are
1163 allowed to export some cryptographic software, subject to notification
1164 rules by the U.S. Department of Commerce.
1165           <p>
1166 Debian policy does not prevent upload to non-US by U.S. residents or
1167 citizens, but care should be taken in doing so. It is recommended that
1168 developers take all necessary steps to ensure that they are not
1169 breaking current US law by doing an upload to non-US, <em>including
1170 consulting a lawyer</em>.
1171           <p>
1172 For packages in non-US main or contrib, developers should at least
1173 follow the <url id="&url-u.s.-export;" name="procedure outlined by the
1174 US Government">.  Maintainers of non-US/non-free packages should
1175 further consult these <url id="&url-notification-of-export;"
1176 name="rules on notification of export"> of non-free software.
1177           <p>
1178 This section is for information only and does not constitute legal
1179 advice. Again, it is strongly recommended that U.S. citizens and
1180 residents consult a lawyer before doing uploads to non-US.
1181
1182
1183         <sect1>Uploads via <tt>chiark</tt>
1184           <p>
1185 If you have a slow network connection to <tt>ftp-master</tt>, there are
1186 alternatives.  One is to upload files to <tt>Incoming</tt> via a
1187 upload queue in Europe on <tt>chiark</tt>. For details connect to
1188 <url id="&url-chiark-readme;">.
1189           <p>
1190 <em>Note:</em> Do not upload packages containing software that is
1191 export-controlled by the United States government to the queue on
1192 <tt>chiark</tt>.  Since this upload queue goes to <tt>ftp-master</tt>, the
1193 prescription found in <ref id="upload-ftp-master"> applies here as well.
1194           <p>
1195 The program <prgn>dupload</prgn> comes with support for uploading to
1196 <tt>chiark</tt>; please refer to the documentation that comes with the
1197 program for details.
1198
1199
1200         <sect1>Uploads via <tt>erlangen</tt>
1201           <p>
1202 Another upload queue is available in Germany: just upload the files
1203 via anonymous FTP to <url id="&url-upload-erlangen;">.
1204           <p>
1205 The upload must be a complete Debian upload, as you would put it into
1206 <tt>ftp-master</tt>'s <tt>Incoming</tt>, i.e., a <tt>.changes</tt> files
1207 along with the other files mentioned in the <tt>.changes</tt>. The
1208 queue daemon also checks that the <tt>.changes</tt> is correctly
1209 PGP-signed by a Debian developer, so that no bogus files can find
1210 their way to <tt>ftp-master</tt> via this queue. Please also make sure that
1211 the <tt>Maintainer</tt> field in the <tt>.changes</tt> contains
1212 <em>your</em> e-mail address. The address found there is used for all
1213 replies, just as on <tt>ftp-master</tt>.
1214           <p>
1215 There's no need to move your files into a second directory after the
1216 upload, as on <tt>chiark</tt>. And, in any case, you should get a
1217 mail reply from the queue daemon explaining what happened to your
1218 upload. Hopefully it should have been moved to <tt>ftp-master</tt>, but in
1219 case of errors you're notified, too.
1220           <p>
1221 <em>Note:</em> Do not upload packages containing software that is
1222 export-controlled by the United States government to the queue on
1223 <tt>erlangen</tt>.  Since this upload queue goes to <tt>ftp-master</tt>, the
1224 prescription found in <ref id="upload-ftp-master"> applies here as well.
1225           <p>
1226 The program <prgn>dupload</prgn> comes with support for uploading to
1227 <tt>erlangen</tt>; please refer to the documentation that comes with
1228 the program for details.
1229
1230
1231         <sect1>Other Upload Queues
1232           <p>
1233 Another upload queue is available which is based in the US, and is a
1234 good backup when there are problems reaching <tt>ftp-master</tt>.  You can
1235 upload files, just as in <tt>erlangen</tt>, to <url
1236 id="&url-upload-samosa;">.
1237           <p>
1238 An upload queue is available in Japan: just upload the files via
1239 anonymous FTP to <url id="&url-upload-jp;">.
1240
1241
1242
1243       <sect id="upload-announce">Announcing package uploads
1244         <p>
1245 When a package is uploaded, an announcement should be posted to one of
1246 the ``debian-changes'' lists. This is now done automatically by the archive
1247 maintenance software when it runs (usually once a day). You just need to use
1248 a recent <package>dpkg-dev</package> (&gt;= 1.4.1.2). The mail generated by
1249 the archive maintenance software will contain the PGP/GPG signed 
1250 <tt>.changes</tt> files that you uploaded with your package.
1251 Previously, <prgn>dupload</prgn> used to send those announcements, so
1252 please make sure that you configured your <prgn>dupload</prgn> not to
1253 send those announcements (check its documentation and look for
1254 ``dinstall_runs'').
1255         <p>
1256 If a package is released with the <tt>Distribution:</tt> set to
1257 `stable', the announcement is sent to &email-debian-changes;.  If a
1258 package is released with <tt>Distribution:</tt> set to `unstable',
1259 or `experimental', the announcement will be
1260 posted to &email-debian-devel-changes; instead.
1261         <p>
1262 The <prgn>dupload</prgn> program is clever enough to determine
1263 where the announcement should go, and will automatically mail the
1264 announcement to the right list.  See <ref id="dupload">.
1265
1266       <sect id="upload-notification">
1267         <heading>Notification that a new package has been installed</heading>
1268         <p>
1269 The Debian archive maintainers are responsible for handling package
1270 uploads.  For the most part, uploads are automatically handled on a
1271 daily basis by the archive maintenance tools, <prgn>katie</prgn>.
1272 Specifically, updates to existing packages to
1273 the `unstable' distribution are handled automatically. In other cases,
1274 notably new packages, placing the uploaded package into the
1275 distribution is handled manually. When uploads are handled manually,
1276 the change to the archive may take up to a month to occur. Please be
1277 patient.
1278         <p>
1279 In any case, you will receive email notification indicating that the
1280 package has added to the archive, which also indicates which bugs will
1281 be closed by the upload.  Please examine this notification carefully,
1282 checking if any bugs you meant to close didn't get triggered.
1283         <p>
1284 The installation notification also includes information on what
1285 section the package was inserted into.  If there is a disparity, you
1286 will receive a separate email notifying you of that.  Read on below.
1287
1288         <sect1 id="override-file">The override file
1289           <p>
1290 The <file>debian/control</file> file's <tt>Section</tt> and
1291 <tt>Priority</tt> fields do not actually specify where the file will
1292 be placed in the archive, nor its priority.  In order to retain the
1293 overall integrity of the archive, it is the archive maintainers who
1294 have control over these fields.  The values in the
1295 <file>debian/control</file> file are actually just hints.
1296           <p>
1297 The archive maintainers keep track of the canonical sections and
1298 priorities for packages in the <em>override file</em>.  If there is a
1299 disparity between the <em>override file</em> and the package's fields
1300 as indicated in <file>debian/control</file>, then you will receive an
1301 email noting the divergence when the package is installed into the
1302 archive.  You can either correct your <file>debian/control</file> file
1303 for your next upload, or else you may wish to make a change in the
1304 <em>override file</em>.
1305           <p>
1306 To alter the actual section that a package is put in, you need to
1307 first make sure that the <file>debian/control</file> in your package
1308 is accurate.  Next, send an email &email-override; or submit a bug
1309 against <package>ftp.debian.org</package> requesting that the section
1310 or priority for your package be changed from the old section or
1311 priority to the new one.  Be sure to explain your reasoning.
1312           <p>
1313 For more information about <em>override files</em>, see <manref
1314 name="dpkg-scanpackages" section="8">, &file-bts-mailing;, and
1315 &file-bts-info;.
1316
1317
1318
1319     <chapt id="nmu">Non-Maintainer Uploads (NMUs)
1320       <p>
1321 Under certain circumstances it is necessary for someone other than the
1322 official package maintainer to make a release of a package.  This is
1323 called a non-maintainer upload, or NMU.
1324        <p>
1325 Debian porters, who compile packages for different architectures, do
1326 NMUs as part of their normal porting activity (see <ref
1327 id="porting">).  Another reason why NMUs are done is when a Debian
1328 developers needs to fix another developers' packages in order to
1329 address serious security problems or crippling bugs, especially during
1330 the freeze, or when the package maintainer is unable to release a fix
1331 in a timely fashion.
1332       <p>
1333 This chapter contains information providing guidelines for when and
1334 how NMUs should be done.  A fundamental distinction is made between
1335 source and binary-only NMUs, which is explained in the next section.
1336
1337       <sect id="nmu-terms">Terminology
1338         <p>
1339 There are two new terms used throughout this section: ``binary-only NMU''
1340 and ``source NMU''.  These terms are used with specific technical
1341 meaning throughout this document.  Both binary-only and source NMUs are
1342 similar, since they involve an upload of a package by a developer who
1343 is not the official maintainer of that package.  That is why it's a
1344 <em>non-maintainer</em> upload.
1345         <p>
1346 A source NMU is an upload of a package by a developer who is not the
1347 official maintainer, for the purposes of fixing a bug in the package.
1348 Source NMUs always involves changes to the source (even if it is just
1349 a change to <file>debian/changelog</file>).  This can be either a
1350 change to the upstream source, or a change to the Debian bits of the
1351 source.  Note, however, that source NMUs may also include
1352 architecture-dependent packages, as well as an updated Debian diff
1353 (or, more rarely, new upstream source as well).
1354         <p>
1355 A binary-only NMU is a recompilation and upload of a binary package
1356 for a given architecture.  As such, it is usually part of a porting
1357 effort.  A binary-only NMU is a non-maintainer uploaded binary version
1358 of a package, with no source changes required.  There are many cases
1359 where porters must fix problems in the source in order to get them to
1360 compile for their target architecture; that would be considered a
1361 source NMU rather than a binary-only NMU.  As you can see, we don't
1362 distinguish in terminology between porter NMUs and non-porter NMUs.
1363         <p>
1364 Both classes of NMUs, source and binary-only, can be lumped by the
1365 term ``NMU''.  However, this often leads to confusion, since most
1366 people think ``source NMU'' when they think ``NMU''.  So it's best to
1367 be careful.  In this chapter, if we use the unqualified term ``NMU'',
1368 we refer to any type of non-maintainer upload NMUs, whether source and
1369 binary, or binary-only.
1370
1371
1372       <sect id="nmu-who">Who can do an NMU
1373         <p>
1374 Only official, registered Debian maintainers can do binary or source
1375 NMUs.  An official maintainer is someone who has their key in the
1376 Debian key ring.  Non-developers, however, are encouraged to download
1377 the source package and start hacking on it to fix problems; however,
1378 rather than doing an NMU, they should just submit worthwhile patches
1379 to the Bug Tracking System.  Maintainers almost always appreciate
1380 quality patches and bug reports.
1381
1382
1383       <sect id="nmu-when">When to do a source NMU
1384         <p>
1385 Guidelines for when to do a source NMU depend on the target
1386 distribution, i.e., stable, unstable, or experimental.  Porters have
1387 slightly different rules than non-porters, due to their unique
1388 circumstances (see <ref id="source-nmu-when-porter">).
1389         <p>
1390 When a security bug is detected, a fixed package should be uploaded
1391 as soon as possible. In this case, the Debian security officers get in
1392 contact with the package maintainer to make sure a fixed package is
1393 uploaded within a reasonable time (less than 48 hours). If the package
1394 maintainer cannot provide a fixed package fast enough or if he/she
1395 cannot be reached in time, a security officer may upload a fixed
1396 package (i.e., do a source NMU).
1397         <p>
1398 During the release cycle (see <ref id="sec-dists">), NMUs which fix
1399 serious or higher severity bugs are encouraged and accepted.  Even
1400 during this window, however, you should endeavor to reach the current
1401 maintainer of the package; they might be just about to upload a fix
1402 for the problem.  As with any source NMU, the guidelines found in <ref
1403 id="nmu-guidelines"> need to be followed.
1404         <p>
1405 Bug fixes to unstable by non-maintainers are also acceptable, but only
1406 as a last resort or with permission.  Try the following steps first,
1407 and if they don't work, it is probably OK to do an NMU:
1408         <p>
1409 <list>
1410             <item>
1411 Make sure that the package bug is in the Debian Bug Tracking System
1412 (BTS).  If not, submit a bug.
1413             <item>
1414 Email the maintainer, and offer to help fix the package bug.  Give it a 
1415 few days.
1416             <item>
1417 Go ahead and fix the bug, submitting a patch to the right bug in the
1418 BTS.  Build the package and test it as discussed in <ref
1419 id="upload-checking">.  Use it locally.
1420             <item>
1421 Wait a couple of weeks for a response.
1422             <item>
1423 Email the maintainer, asking if it is OK to do an NMU.
1424             <item>
1425 Double check that your patch doesn't have any unexpected side effects.
1426 Make sure your patch is as small and as non-disruptive as it can be.
1427             <item>
1428 Wait another week for a response.
1429             <item>
1430 Go ahead and do the source NMU, as described in <ref
1431 id="nmu-guidelines">.
1432           </list>
1433
1434
1435
1436       <sect id="nmu-guidelines">How to do a source NMU
1437         <p>
1438 The following applies to porters insofar as they are playing the dual
1439 role of being both package bug-fixers and package porters.  If a
1440 porter has to change the Debian source archive, automatically their
1441 upload is a source NMU and is subject to its rules.  If a porter is
1442 simply uploading a recompiled binary package, the rules are different;
1443 see <ref id="porter-guidelines">.
1444         <p>
1445 First and foremost, it is critical that NMU patches to source should
1446 be as non-disruptive as possible.  Do not do housekeeping tasks, do
1447 not change the name of modules or files, do not move directories; in
1448 general, do not fix things which are not broken.  Keep the patch as
1449 small as possible.  If things bother you aesthetically, talk to the
1450 Debian maintainer, talk to the upstream maintainer, or submit a bug.
1451 However, aesthetic changes must <em>not</em> be made in a non-maintainer
1452 upload.
1453
1454
1455         <sect1 id="nmu-version">Source NMU version numbering
1456           <p>
1457 Whenever you have made a change to a package, no matter how trivial,
1458 the version number needs to change.  This enables our packing system
1459 to function.
1460           <p>
1461 If you are doing a non-maintainer upload (NMU), you should add a new
1462 minor version number to the <var>debian-revision</var> part of the
1463 version number (the portion after the last hyphen).  This extra minor
1464 number will start at `1'.  For example, consider the package `foo',
1465 which is at version 1.1-3.  In the archive, the source package control
1466 file would be <file>foo_1.1-3.dsc</file>.  The upstream version is
1467 `1.1' and the Debian revision is `3'.  The next NMU would add a new
1468 minor number `.1' to the Debian revision; the new source control file
1469 would be <file>foo_1.1-3.1.dsc</file>.
1470           <p>
1471 The Debian revision minor number is needed to avoid stealing one of
1472 the package maintainer's version numbers, which might disrupt their
1473 work.  It also has the benefit of making it visually clear that a
1474 package in the archive was not made by the official maintainer.
1475           <p>
1476 If there is no <var>debian-revision</var> component in the version
1477 number then one should be created, starting at `0.1'.  If it is
1478 absolutely necessary for someone other than the usual maintainer to
1479 make a release based on a new upstream version then the person making
1480 the release should start with the <var>debian-revision</var> value
1481 `0.1'.  The usual maintainer of a package should start their
1482 <var>debian-revision</var> numbering at `1'.  Note that if you do
1483 this, you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the
1484 <tt>-sa</tt> switch to force the build system to pick up the new
1485 source package (normally it only looks for Debian revisions of '0' or
1486 '1' &mdash; it's not yet clever enough to know about `0.1').
1487           <p>
1488 Remember, porters who are simply recompiling a package for a different
1489 architecture do not need to renumber.  Porters should use new version
1490 numbers if and only if they actually have to modify the source package
1491 in some way, i.e., if they are doing a source NMU and not a binary
1492 NMU.
1493
1494
1495         <sect1 id="nmu-changelog">
1496           <heading>Source NMUs must have a new changelog entry</heading>
1497           <p>
1498 A non-maintainer doing a source NMU must create a changelog entry,
1499 describing which bugs are fixed by the NMU, and generally why the NMU
1500 was required and what it fixed.  The changelog entry will have the
1501 non-maintainer's email address in the log entry and the NMU version
1502 number in it.</p>
1503           <p>
1504 By convention, source NMU changelog entries start with the line
1505 <example>
1506   * Non-maintainer upload
1507 </example></p></sect1>
1508
1509
1510         <sect1 id="nmu-patch">Source NMUs and the Bug Tracking System
1511           <p>
1512 Maintainers other than the official package maintainer should make as
1513 few changes to the package as possible, and they should always send a
1514 patch as a unified context diff (<tt>diff -u</tt>) detailing their
1515 changes to the Bug Tracking System.
1516           <p>
1517 What if you are simply recompiling the package?  In this case, the
1518 process is different for porters than it is for non-porters, as
1519 mentioned above.  If you are not a porter and are doing an NMU that
1520 simply requires a recompile (i.e., a new shared library is available
1521 to be linked against, a bug was fixed in
1522 <package>debhelper</package>), there must still be a changelog entry;
1523 therefore, there will be a patch.  If you are a porter, you are
1524 probably just doing a binary-only NMU.  (Note: this leaves out in the cold
1525 porters who have to do recompiles &mdash; chalk it up as a weakness in how
1526 we maintain our archive.)
1527           <p>
1528 If the source NMU (non-maintainer upload) fixes some existing bugs,
1529 these bugs should be tagged <em>fixed</em> in the Bug Tracking
1530 System rather than closed.  By convention, only the official package
1531 maintainer or the original bug submitter are allowed to close bugs.
1532 Fortunately, Debian's archive system recognizes NMUs and thus marks
1533 the bugs fixed in the NMU appropriately if the person doing the NMU
1534 has listed all bugs in the changelog with the <tt>Closes:
1535 bug#<var>nnnnn</var></tt> syntax (see <ref id="upload-bugfix"> for
1536 more information describing how to close bugs via the changelog).
1537 Tagging the bugs <em>fixed</em> ensures that everyone knows that the
1538 bug was fixed in an NMU; however the bug is left open until the
1539 changes in the NMU are incorporated officially into the package by
1540 the official package maintainer.
1541           <p>
1542 Also, after doing an NMU, you have to open a new bug and include a
1543 patch showing all the changes you have made.  The normal maintainer
1544 will either apply the patch or employ an alternate method of fixing
1545 the problem.  Sometimes bugs are fixed independently upstream, which
1546 is another good reason to back out an NMU's patch.  If the maintainer
1547 decides not to apply the NMU's patch but to release a new version,
1548 the maintainer needs to ensure that the new upstream version really
1549 fixes each problem that was fixed in the non-maintainer release.
1550           <p>
1551 In addition, the normal maintainer should <em>always</em> retain the
1552 entry in the changelog file documenting the non-maintainer upload.
1553
1554
1555         <sect1 id="nmu-build">Building source NMUs
1556           <p>
1557 Source NMU packages are built normally.  Pick a distribution using the
1558 same rules as found in <ref id="upload-dist">.  Just as described in
1559 <ref id="uploading">, a normal changes file, etc., will be built.  In
1560 fact, all the prescriptions from <ref id="upload"> apply, including
1561 the need to announce the NMU to the proper lists.
1562           <p>
1563 Make sure you do <em>not</em> change the value of the maintainer in
1564 the <file>debian/control</file> file.  Your name as given in the NMU entry of
1565 the <file>debian/changelog</file> file will be used for signing the
1566 changes file.
1567
1568
1569
1570
1571     <chapt id="porting">Porting and Being Ported
1572       <p>
1573 Debian supports an ever-increasing number of architectures.  Even if
1574 you are not a porter, and you don't use any architecture but one, it
1575 is part of your duty as a maintainer to be aware of issues of
1576 portability.  Therefore, even if you are not a porter, you should read
1577 most of this chapter.
1578       <p>
1579 Porting is the act of building Debian packages for architectures that
1580 is different from the original architecture of the package
1581 maintainer's binary package.  It is a unique and essential activity.
1582 In fact, porters do most of the actual compiling of Debian packages.
1583 For instance, for a single <em>i386</em> binary package, there must be
1584 a recompile for each architecture, which is amounts to
1585 &number-of-arches; more builds.
1586
1587
1588       <sect id="kind-to-porters">Being Kind to Porters
1589         <p>
1590 Porters have a difficult and unique task, since they are required to
1591 deal with a large volume of packages.  Ideally, every source package
1592 should build right out of the box.  Unfortunately, this is often not
1593 the case.  This section contains a checklist of ``gotchas'' often
1594 committed by Debian maintainers &mdash; common problems which often stymie
1595 porters, and make their jobs unnecessarily difficult.
1596         <p>
1597 The first and most important watchword is to respond quickly to bug or
1598 issues raised by porters.  Please treat porters with courtesy, as if
1599 they were in fact co-maintainers of your package (which in a way, they
1600 are).  Please be tolerant of succinct or even unclear bug reports,
1601 doing your best to hunt down whatever the problem is.
1602         <p>
1603 By far, most of the problems encountered by porters are caused by
1604 <em>packaging bugs</em> in the source packages.  Here is a checklist
1605 of things you should check or be aware of.
1606
1607 <enumlist>
1608             <item>
1609 Make sure that your <tt>Build-Depends</tt> and
1610 <tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
1611 are set properly.  The best way to validate this is to use the
1612 <package>debootstrap</package> package to create an unstable chroot
1613 environment.  Within that chrooted environment, install the
1614 <package>build-essential</package> package and any package
1615 dependancies mention in <tt>Build-Depends</tt> and/or
1616 <tt>Build-Depends-Indep</tt>.  Finally, try building your package
1617 within that chrooted environment.
1618                 <p>
1619 See the <url id="&url-debian-policy;" name="Debian Policy
1620 Manual"> for instructions on setting build dependencies.
1621             <item>
1622 Don't set architecture to a value other than ``all'' or ``any'' unless
1623 you really mean it.  In too many cases, maintainers don't follow the
1624 instructions in the <url id="&url-debian-policy;" name="Debian Policy
1625 Manual">.  Setting your architecture to ``i386'' is usually incorrect.
1626             <item>
1627 Make sure your source package is correct.  Do <tt>dpkg-source -x
1628 <var>package</var>.dsc</tt> to make sure your source package unpacks
1629 properly.  Then, in there, try building your package from scratch with
1630 <tt>dpkg-buildpackage</tt>.
1631             <item>
1632 Make sure you don't ship your source package with the
1633 <file>debian/files</file> or <file>debian/substvars</file> files.
1634 They should be removed by the `clean' target of
1635 <file>debian/rules</file>.
1636             <item>
1637 Make sure you don't rely on locally installed or hacked configurations
1638 or programs.  For instance, you should never be calling programs in
1639 <file>/usr/local/bin</file> or the like.  Try not to rely on programs
1640 be setup in a special way.  Try building your package on another
1641 machine, even if it's the same architecture.
1642             <item>
1643 Don't depend on the package you're building already being installed (a
1644 sub-case of the above issue).
1645             <item>
1646 Don't rely on the compiler being a certain version, if possible.  If
1647 not, then make sure your build dependencies reflect the restrictions,
1648 although you are probably asking for trouble, since different
1649 architectures sometimes standardize on different compilers.
1650             <item>
1651 Make sure your debian/rules contains separate ``binary-arch'' and
1652 ``binary-indep'' targets, as the Debian Packaging Manual requires.
1653 Make sure that both targets work independently, that is, that you can
1654 call the target without having called the other before. To test this,
1655 try to run <tt>dpkg-buildpackage -b</tt>.
1656           </enumlist>
1657
1658
1659       <sect id="porter-guidelines">Guidelines for Porter Uploads
1660         <p>
1661 If the package builds out of the box for the architecture to be ported
1662 to, you are in luck and your job is easy.  This section applies to
1663 that case; it describes how to build and upload your binary-only NMU so
1664 that it is properly installed into the archive.  If you do have to
1665 patch the package in order to get it to compile for the other
1666 architecture, you are actually doing a source NMU, so consult <ref
1667 id="nmu-guidelines"> instead.
1668         <p>
1669 In a binary-only NMU, no real changes are being made to the source.  You do
1670 not need to touch any of the files in the source package.  This
1671 includes <file>debian/changelog</file>.
1672         <p>
1673 The way to invoke <prgn>dpkg-buildpackage</prgn> is as
1674 <tt>dpkg-buildpackage -B -e<var>porter-email</var></tt>.  Of course,
1675 set <var>porter-email</var> to your email address.  This will do a
1676 binary-only build of only the architecture-dependant portions of the
1677 package, using the `binary-arch' target in <file>debian/rules</file>.
1678
1679         <sect1 id="recompile-nmu-versioning">
1680           <heading>Recompilation Binary-Only NMU Versioning</heading>
1681         <p>
1682 Sometimes you need to recompile a package against other packages which
1683 have been updated, such as libraries.  You do have to bump the version
1684 number in this case, so that the version comparison system can
1685 function properly.  Even so, these are considered binary-only NMUs
1686 &mdash; there is no need in this case to trigger all other
1687 architectures to consider themselves out of date or requiring
1688 recompilation.
1689         <p>
1690 Such recompilations require special ``magic'' version numbering, so that
1691 the archive maintenance tools recognize that, even though there is a
1692 new Debian version, there is no corresponding source update.  If you
1693 get this wrong, the archive maintainers will reject your upload (due
1694 to lack of corresponding source code).
1695         <p>
1696 The ``magic'' for a recompilation-only NMU is triggered by using the
1697 third-level number on the Debian part of the version.  For instance,
1698 if the latest version you are recompiling against was version
1699 ``2.9-3'', your NMU should carry a version of ``2.9-3.0.1''.  If the
1700 latest version was ``3.4-2.1'', your NMU should have a version number
1701 of ``3.4-2.1.1''.
1702
1703
1704         <sect1 id="source-nmu-when-porter">
1705           <heading>When to do a source NMU if you are a porter</heading>
1706           <p>
1707 Porters doing a source NMU generally follow the guidelines found in
1708 <ref id="nmu">, just like non-porters.  However, it is expected that
1709 the wait cycle for a porter's source NMU is smaller than for a
1710 non-porter, since porters have to cope with a large quantity of
1711 packages.
1712 Again, the situation varies depending on the distribution they are
1713 uploading to.
1714
1715 <!-- 
1716 FIXME: commented out until I can work out how to upload to testing directly
1717
1718   Crucial fixes (i.e., changes need to get a source
1719 package to compile for a released-targeted architecture) can be
1720 uploaded with <em>no</em> waiting period for the `frozen' distribution.
1721  -->
1722           <p>
1723 However, if you are a porter doing an NMU for `unstable', the above
1724 guidelines for porting should be followed, with two variations.
1725 Firstly, the acceptable waiting period &mdash the time between when the
1726 bug is submitted to the BTS and when it is OK to do an NMU &mdash; is seven
1727 days for porters working on the unstable distribution.  This period
1728 can be shortened if the problem is critical and imposes hardship on
1729 the porting effort, at the discretion of the porter group.  (Remember,
1730 none of this is Policy, just mutually agreed upon guidelines.)
1731           <p>
1732 Secondly, porters doing source NMUs should make sure that the bug they
1733 submit to the BTS should be of severity `serious' or greater.  This
1734 ensures that a single source package can be used to compile every
1735 supported Debian architecture by release time.  It is very important
1736 that we have one version of the binary and source package for all
1737 architecture in order to comply with many licenses.
1738           <p>
1739 Porters should try to avoid patches which simply kludge around bugs in
1740 the current version of the compile environment, kernel, or libc.
1741 Sometimes such kludges can't be helped.  If you have to kludge around
1742 compilers bugs and the like, make sure you <tt>#ifdef</tt> your work
1743 properly; also, document your kludge so that people know to remove it
1744 once the external problems have been fixed.
1745           <p>
1746 Porters may also have an unofficial location where they can put the
1747 results of their work during the waiting period.  This helps others
1748 running the port have the benefit of the porter's work, even during
1749 the waiting period.  Of course, such locations have no official
1750 blessing or status, so buyer, beware.
1751
1752
1753       <sect>Tools for Porters
1754         <p>
1755 There are several tools available for the porting effort. This section
1756 contains a brief introduction to these tools; see the package
1757 documentation or references for full information.
1758
1759
1760         <sect1 id="quinn-diff">
1761           <heading><package>quinn-diff</package>
1762           <p>
1763 <package>quinn-diff</package> is used to locate the differences from
1764 one architecture to another.  For instance, it could tell you which
1765 packages need to be ported for architecture <var>Y</var>, based on
1766 architecture <var>X</var>.
1767
1768
1769         <sect1 id="buildd">
1770           <heading><package>buildd</package>
1771           <p>
1772 The <package>buildd</package> system is used as a distributed,
1773 client-server build distribution system.  It is usually used in
1774 conjunction with <em>auto-builders</em>, which are ``slave'' hosts
1775 which simply check out and attempt to auto-build packages which need
1776 to be ported.  There is also an email interface to the system, which
1777 allows porters to ``check out'' a source package (usually one which
1778 cannot yet be autobuilt) and work on it.
1779           <p>
1780 <package>buildd</package> is not yet available as a package; however,
1781 most porting efforts are either using it currently or planning to use
1782 it in the near future.  It collects a number of as yet unpackaged
1783 components which are currently very useful and in use continually,
1784 such as <prgn>andrea</prgn>, <prgn>sbuild</prgn> and
1785 <prgn>wanna-build</prgn>.
1786           <p>
1787 Some of the data produced by <package>buildd</package> which is
1788 generally useful to porters is available on the web at <url
1789 id="&url-buildd;">.  This data includes nightly updated information
1790 from <prgn>andrea</prgn> (source dependencies) and
1791 <package>quinn-diff</package> (packages needing recompilation).
1792           <p>
1793 We are very excited about this system, since it potentially has so
1794 many uses.  Independent development groups can use the system for
1795 different sub-flavors of Debian, which may or may not really be of
1796 general interest (for instance, a flavor of Debian built with gcc
1797 bounds checking).  It will also enable Debian to recompile entire
1798 distributions quickly.
1799
1800
1801         <sect1 id="dpkg-cross">
1802           <heading><package>dpkg-cross</package>
1803           <p>
1804 <package>dpkg-cross</package> is a tool for installing libraries and
1805 headers for cross-compiling in a way similar to
1806 <package>dpkg</package>. Furthermore, the functionality of
1807 <prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
1808 enhanced to support cross-compiling.
1809
1810
1811
1812
1813     <chapt id="archive-manip">
1814       <heading>Moving, Removing, Renaming, Adopting, and Orphaning
1815       Packages</heading>
1816       <p>
1817 Some archive manipulation operation are not automated in the Debian
1818 upload process.  These procedures should be manually followed by
1819 maintainers.  This chapter gives guidelines in what to do in these
1820 cases.
1821
1822       <sect>Moving packages
1823         <p>
1824 Sometimes a package will change its section.  For instance, a
1825 package from the `non-free' section might be GPL'd in a later version,
1826 in which case, the package should be moved to `main' or
1827 `contrib'.<footnote> See the <url id="&url-debian-policy;"
1828 name="Debian Policy Manual"> for guidelines on what section a package
1829 belongs in.
1830           </footnote>
1831         <p>
1832 If you need to change the section for one of your packages, change the
1833 package control information to place the package in the desired
1834 section, and re-upload the package (see the <url id="&url-debian-policy;"
1835 name="Debian Policy Manual"> for details).  Carefully examine the
1836 installation log sent to you when the package is installed into the
1837 archive.  If for some reason the old location of the package remains,
1838 file a bug against <tt>ftp.debian.org</tt> asking that the old
1839 location be removed.  Give details on what you did, since it might be
1840 a bug in the archive maintenance software.
1841         <p>
1842 If, on the other hand, you need to change the <em>subsection</em> of
1843 one of your packages (e.g., ``devel'', ``admin''), the procedure is
1844 slightly different.  Correct the subsection as found in the control
1845 file of the package, and reupload that.  Also, you'll need to get the
1846 override file updated, as described in <ref id="override-file">.
1847
1848
1849       <sect id="removing-pkgs">Removing packages
1850         <p>
1851 If for some reason you want to completely remove a package (say, if it
1852 is an old compatibility library which is not longer required), you
1853 need to file a bug against <tt>ftp.debian.org</tt> asking that the
1854 package be removed.  Make sure you indicate which distribution the
1855 package should be removed from.
1856         <p>
1857 If in doubt concerning whether a package is disposable, email
1858 &email-debian-devel; asking for opinions.  Also of interest is the
1859 <prgn>apt-cache</prgn> program from the <package>apt</package>
1860 package.  When invoked as <tt>apt-cache showpkg
1861 <var>package</var></tt>, the program will show details for
1862 <var>package</var>, including reverse depends.
1863
1864         <sect1>Removing packages from <tt>Incoming</tt>
1865           <p>
1866 In the past, it was possible to remove packages from <tt>incoming</tt>.
1867 With the introduction of the New Incoming system this is no longer
1868 possible.  Instead, you have to upload a new revision of your package with
1869 a higher version as the package you want to replace.  Both versions will be
1870 installed in the archive but only the higher version will actually be
1871 available in <em>unstable</em> since the previous version will immediately
1872 be replaced by the higher.  However, if you do proper testing of your
1873 packages, the need to replace a package should not occur too often anyway.
1874
1875       <sect>Replacing or renaming packages
1876         <p>
1877 Sometimes you made a mistake naming the package and you need to rename
1878 it.  In this case, you need to follow a two-step process.  First, set
1879 your <file>debian/control</file> file to replace and conflict with the
1880 obsolete name of the package (see the <url id="&url-debian-policy;"
1881 name="Debian Policy Manual"> for details).  Once you've uploaded
1882 that package, and the package has moved into the archive, file a bug
1883 against <tt>ftp.debian.org</tt> asking to remove the package with the
1884 obsolete name.
1885
1886       <sect id="orphaning">Orphaning a package
1887         <p>
1888 If you can no longer maintain a package, you need to inform the others
1889 about that, and see that the package is marked as orphaned.
1890 you should set the package maintainer to <tt>Debian QA Group
1891 &orphan-address;</tt> and submit a bug report
1892 against the pseudo package <package>wnpp</package>.  The bug report should be
1893 titled <tt>O: <var>package</var> -- <var>short description</var></tt>
1894 indicating that the package is now orphaned.  The severity of the bug
1895 should be set to <em>normal</em>. If you feel it's necessary, send a copy
1896 to &email-debian-devel; by putting the address in the X-Debbugs-CC: header
1897 of the message (no, don't use CC:, because that way the message's subject
1898 won't indicate the bug number).
1899         <p>
1900 If the package is especially crucial to Debian, you should instead submit
1901 a bug against <tt>wnpp</tt> and title it <tt>RFA: <var>package</var> --
1902 <var>short description</var></tt> and set its severity to
1903 <em>important</em>. Definitely copy the message to debian-devel in this
1904 case, as described above.
1905         <p>
1906 Read instructions on the <url id="&url-wnpp;" name="WNPP web pages">
1907 for more information.
1908
1909       <sect id="adopting">Adopting a package
1910         <p>
1911 A list of packages in need of a new maintainer is available at in the
1912 <url name="Work-Needing and Prospective Packages list (WNPP)"
1913 id="&url-wnpp;">. If you wish to take over maintenance of any of the
1914 packages listed in the WNPP, please take a look at the aforementioned
1915 page for information and procedures.
1916         <p>
1917 It is not OK to simply take over a package that you feel is neglected
1918 &mdash; that would be package hijacking.  You can, of course, contact the
1919 current maintainer and ask them if you may take over the package.
1920 However, without their assent, you may not take over the package.
1921 Even if they ignore you, that is still not grounds to take over a
1922 package.  If you really feel that a maintainer has gone AWOL (absent
1923 without leave), post a query to &email-debian-private;.
1924         <p>
1925 If you take over an old package, you probably want to be listed as the
1926 package's official maintainer in the bug system. This will happen
1927 automatically once you upload a new version with an updated
1928 <tt>Maintainer:</tt> field, although it can take a few hours after the
1929 upload is done. If you do not expect to upload a new version for a while,
1930 send an email to &email-override; so that bug reports will go to you
1931 right away.
1932
1933
1934
1935     <chapt id="bug-handling">Handling Bugs
1936
1937       <sect>Monitoring bugs
1938         <p>
1939 If you want to be a good maintainer, you should periodically check the
1940 <url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
1941 packages.  The BTS contains all the open bugs against your packages.
1942         <p>
1943 Maintainers interact with the BTS via email addresses at
1944 <tt>bugs.debian.org</tt>.  Documentation on available commands can be
1945 found at <url id="&url-bts;">, or, if you have installed the
1946 <package>doc-debian</package> package, you can look at the local files
1947 &file-bts-docs;.
1948         <p>
1949 Some find it useful to get periodic reports on open bugs.  You can add
1950 a cron job such as the following if you want to get a weekly email
1951 outlining all the open bugs against your packages:
1952 <example>
1953 # ask for weekly reports of bugs in my packages
1954 &cron-bug-report;
1955 </example>
1956 Replace <var>address</var> with you official Debian
1957 maintainer address.
1958
1959       <sect id="submit-bug">Submitting Bugs
1960         <p>
1961 Often as a package maintainer, you find bugs in other packages or else
1962 have bugs reported to your packages which need to be reassigned.  The
1963 <url id="&url-bts-control;" name="BTS instructions"> can tell you how
1964 to do this.
1965         <p>
1966 We encourage you to file bugs when there are problems.  Try to submit
1967 the bug from a normal user account at which you are likely to receive
1968 mail.  Do not submit bugs as root.
1969         <p>
1970 Make sure the bug is not already filed against a package.  Try to do a
1971 good job reporting a bug and redirecting it to the proper location.
1972 For extra credit, you can go through other packages, merging bugs
1973 which are reported more than once, or setting bug severities to
1974 `fixed' when they have already been fixed.  Note that when you are
1975 neither the bug submitter nor the package maintainer, you should
1976 not actually close the bug (unless you secure permission from the
1977 maintainer).
1978
1979       <sect>Responding to Bugs
1980         <p>
1981 Make sure that any discussions you have about bugs are sent both to
1982 the original submitter of the bug, and the bug itself (e.g.,
1983 <email>123@bugs.debian.org</email>).
1984         <p>
1985 You should <em>never</em> close bugs via the bug server `close'
1986 command sent to &email-bts-control;.  If you do so, the original
1987 submitter will not receive any feedback on why the bug was closed.
1988
1989       <sect id="upload-bugfix">When bugs are closed by new uploads
1990         <p>
1991 If you fix a bug in your packages, it is your responsibility as the
1992 package maintainer to close the bug when it has been fixed.  However,
1993 you should not close the bug until the package which fixes the bug has
1994 been accepted into the Debian archive.  Therefore, once you get
1995 notification that your updated package has been installed into the
1996 archive, you can and should close the bug in the BTS.
1997         <p>
1998 If you are using a new version of <package>dpkg-dev</package> and you do
1999 your changelog entry properly, the archive maintenance software will close
2000 the bugs automatically.  All you have to do is follow a certain syntax in
2001 your <file>debian/changelog</file> file:
2002 <example>
2003 acme-cannon (3.1415) unstable; urgency=low
2004
2005   * Frobbed with options (closes: Bug#98339)
2006   * Added safety to prevent operator dismemberment, closes: bug#98765,
2007     bug#98713, #98714.
2008   * Added manpage. Closes: #98725.
2009 </example>
2010
2011 Technically speaking, the following Perl regular expression is what is
2012 used:
2013 <example>
2014   /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
2015 </example>
2016
2017 The author prefers the <tt>(closes: Bug#<var>XXX</var>)</tt> syntax,
2018 since it stands out from the rest of the changelog entries.
2019         <p>
2020 If you want to close bugs the old fashioned, manual way, it is usually
2021 sufficient to mail the <tt>.changes</tt> file to
2022 <email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your
2023 bug number.
2024
2025
2026       <sect id="lintian-reports">Lintian reports
2027         <p>
2028 You should periodically get the new <package>lintian</package> from
2029 `unstable' and check over all your packages.  Alternatively you can
2030 check for your maintainer email address at the <url id="&url-lintian;"
2031 name="online lintian report">.  That report, which is updated
2032 automatically, contains <prgn>lintian</prgn> reports against the
2033 latest version of the distribution (usually from 'unstable') using the
2034 latest <package>lintian</package>.
2035
2036
2037       <sect>Reporting lots of bugs at once
2038         <p>
2039 Reporting a great number of bugs for the same problem on a great
2040 number of different packages &mdash i.e., more than 10 &mdash is a deprecated
2041 practice.  Take all possible steps to avoid submitting bulk bugs at
2042 all.  For instance, if checking for the problem can be automated, add
2043 a new check to <package>lintian</package> so that an error or warning
2044 is emitted.
2045         <p>
2046 If you report more than 10 bugs on the same topic at once, it is
2047 recommended that you send a message to &email-debian-devel; describing
2048 your intention before submitting the report. This will allow other
2049 developers to verify that the bug is a real problem. In addition, it
2050 will help prevent a situation in which several maintainers start
2051 filing the same bug report simultaneously.
2052         <p>
2053 Note that when sending lots of bugs on the same subject, you should
2054 send the bug report to <email>maintonly@bugs.debian.org</email> so
2055 that the bug report is not forwarded to the bug distribution mailing
2056 list.
2057
2058
2059     <chapt id="newmaint">
2060       <heading>Interaction with Prospective Developers</heading>
2061
2062       <p>
2063 This chapter describes procedures that existing Debian developers should
2064 follow when it comes to dealing with wannabe developers.
2065
2066       <sect id="sponsoring">Sponsoring packages
2067         <p>
2068 Sponsoring a package means uploading a package for a maintainer who is not
2069 able to do it on their own, a new maintainer applicant. Sponsoring a package
2070 also means accepting responsibility for it.
2071         <p>
2072 New maintainers usually have certain difficulties creating Debian packages
2073 &mdash; this is quite understandable. That is why the sponsor is there, to check
2074 the package and verify that it is good enough for inclusion in Debian.
2075 (Note that if the sponsored package is new, the FTP admins will also have to
2076 inspect it before letting it in.)
2077         <p>
2078 Sponsoring merely by signing the upload or just recompiling is
2079 <strong>definitely not recommended</strong>. You need to build the source
2080 package just like you would build a package of your own. Remember that it
2081 doesn't matter that you left the prospective developer's name both in the
2082 changelog and the control file, the upload can still be traced to you.
2083         <p>
2084 If you are an application manager for a prospective developer, you can also
2085 be their sponsor. That way you can also verify the how the applicant is
2086 handling the `Tasks and Skills' part of their application.
2087
2088       <sect>Advocating new developers
2089         <p>
2090 See the page about <url id="&url-newmaint-advocate;"
2091 name="advocating a prospective developer"> at the Debian web site.
2092
2093       <sect>Handling new maintainer applications
2094         <p>
2095 Please see <url id="&url-newmaint-amchecklist;" name="Checklist for
2096 Application Managers"> at the Debian web site.
2097
2098
2099
2100     <chapt id="tools">Overview of Debian Maintainer Tools
2101       <p>
2102 This section contains a rough overview of the tools available to
2103 maintainers.  The following is by no means complete or definitive, but
2104 just a guide to some of the more popular tools.
2105       <p>
2106 Debian maintainer tools are meant to help convenience developers and 
2107 free their time for critical tasks.  As Larry Wall says, there's more
2108 than one way to do it.
2109       <p>
2110 Some people prefer to use high-level package maintenance tools and
2111 some do not.  Debian is officially agnostic on this issue; any tool
2112 which gets the job done is fine.  Therefore, this section is not meant
2113 to stipulate to anyone which tools they should use or how they should
2114 go about with their duties of maintainership.  Nor is it meant to
2115 endorse any particular tool to the exclusion of a competing tool.
2116       <p>
2117 Most of the descriptions of these packages come from the actual
2118 package descriptions themselves.  Further information can be found in
2119 the package documentation itself.  You can also see more info with the
2120 command <tt>apt-cache show <var>package_name</var></tt>.
2121
2122
2123       <sect id="dpkg-dev">
2124         <heading><package>dpkg-dev</package>
2125         <p>
2126 <package>dpkg-dev</package> contains the tools (including
2127 <prgn>dpkg-source</prgn>) required to unpack, build and upload Debian
2128 source packages.  These utilities contain the fundamental, low-level
2129 functionality required to create and manipulated packages; as such,
2130 they are required for any Debian maintainer.
2131
2132
2133       <sect id="lintian">
2134         <heading><package>lintian</package>
2135         <p>
2136 <package>Lintian</package> dissects Debian packages and reports bugs
2137 and policy violations. It contains automated checks for many aspects
2138 of Debian policy as well as some checks for common errors.  The use of
2139 <package>lintian</package> has already been discussed in <ref
2140 id="upload-checking"> and <ref id="lintian-reports">.
2141
2142
2143       <sect id="debconf">
2144         <heading><package>debconf</package></heading>
2145         <p>
2146 <package>debconf</package> provides a consistent interface to
2147 configuring packages interactively.  It is user interface
2148 independant, allowing end-users to configure packages with a
2149 text-only interface, an HTML interface, or a dialog interface.  New
2150 interfaces can be added modularly.
2151         <p>
2152 You can find documentation for this package in the
2153 <package>debconf-doc</package> package.
2154         <p>
2155 Many feel that this system should be used for all packages requiring
2156 interactive configuration.  <package>debconf</package> is not
2157 currently required by Debian Policy, however, that may change in the
2158 future.
2159         <p>
2160
2161
2162       <sect id="debhelper">
2163         <heading><package>debhelper</package>
2164         <p>
2165 <package>debhelper</package> is a collection of programs that can be
2166 used in <file>debian/rules</file> to automate common tasks related to
2167 building binary Debian packages. Programs are included to install
2168 various files into your package, compress files, fix file permissions,
2169 integrate your package with the Debian menu system.
2170         <p>
2171 Unlike some approaches, <package>debhelper</package> is broken into
2172 several small, granular commands which act in a consistent manner.  As
2173 such, it allows a greater granularity of control than some of the
2174 other "debian/rules tools".
2175         <p>
2176 There are a number of little <package>debhelper</package> add-on
2177 packages, too transient to document.  You can see the list of most of
2178 them by doing <tt>apt-cache search ^dh-</tt>.
2179
2180
2181       <sect id="debmake">
2182         <heading><package>debmake</package>
2183         <p>
2184 <package>debmake</package>, a pre-cursor to
2185 <package>debhelper</package>, is a less granular
2186 <file>debian/rules</file> assistant. It includes two main programs:
2187 <prgn>deb-make</prgn>, which can be used to help a maintainer convert
2188 a regular (non-Debian) source archive into a Debian source package;
2189 and <prgn>debstd</prgn>, which incorporates in one big shot the same
2190 sort of automated functions that one finds in
2191 <package>debhelper</package>.
2192         <p>
2193 The consensus is that <package>debmake</package> is now deprecated in
2194 favor of <package>debhelper</package>.  However, it's not a bug to use
2195 <package>debmake</package>.
2196
2197
2198       <sect id="yada">
2199         <heading><package>yada</package>
2200         <p>
2201 <package>yada</package> is another packaging helper tool.  It uses a
2202 <file>debian/packages</file> file to auto-generate
2203 <file>debian/rules</file> other necessary files in the
2204 <file>debian/</file> subdirectory.
2205         <p>
2206 Note that <package>yada</package> is called "essentially unmaintained"
2207 by it's own maintainer, Charles Briscoe-Smith.  As such, it can be
2208 considered deprecated.
2209
2210
2211       <sect id="equivs">
2212         <heading><package>equivs</package>
2213         <p>
2214 <package>equivs</package> is another package for making packages.  It
2215 is often suggested for local use if you need to make a package simply
2216 to fulfill dependencies.  It is also sometimes used when making
2217 ``meta-packages'', which are packages whose only purpose is to depend
2218 on other packages.
2219
2220
2221       <sect id="cvs-buildpackage">
2222         <heading><package>cvs-buildpackage</package>
2223         <p>
2224 <package>cvs-buildpackage</package> provides the capability to inject
2225 or import Debian source packages into a CVS repository, build a Debian
2226 package from the CVS repository, and helps in integrating upstream
2227 changes into the repository.
2228         <p>
2229 These utilities provide an infrastructure to facilitate the use of CVS
2230 by Debian maintainers. This allows one to keep separate CVS branches
2231 of a package for <em>stable</em>, <em>unstable</em>, and possibly
2232 <em>experimental</em> distributions, along with the other benefits of
2233 a version control system.
2234
2235
2236       <sect id="dupload">
2237         <heading><package>dupload</package>
2238         <p>
2239 <package>dupload</package> is a package and a script to automagically
2240 upload Debian packages to the Debian archive, to log the upload, and
2241 to send mail about the upload of a package.  You can configure it for
2242 new upload locations or methods.
2243
2244
2245       <sect id="dput">
2246         <heading><package>dput</package>
2247         <p>
2248 The <package>dput</package> package and script does much the same
2249 thing as <package>dupload</package>, but in a different way.  It has
2250 some features over <package>dupload</package>, such as the ability to
2251 check the GnuPG signature and checksums before uploading, and the
2252 possibility of running <tt>dinstall</tt> in dry-run mode after the
2253 upload.
2254
2255
2256       <sect id="fakeroot">
2257         <heading><package>fakeroot</package>
2258         <p>
2259 <package>fakeroot</package> simulates root privileges.  This enables
2260 you to build packages without being root (packages usually want to
2261 install files with root ownership).  If you have
2262 <package>fakeroot</package> installed, you can build packages as a
2263 user: <tt>dpkg-buildpackage -rfakeroot</tt>.
2264
2265
2266       <sect id="debootstrap">
2267         <heading><package>debootstrap</package>
2268         <p>
2269 The <package>debootstrap</package> package and script allows you to
2270 "bootstrap" a Debian base system into any part of your filesystem.
2271 By "base system", we mean the bare minimum of packages required to
2272 operate and install the rest of the system.
2273         <p>
2274 Having a system link this can be useful in many ways. For instance,
2275 you can <prgn>chroot</prgn> into it if you want to test your build
2276 depends.  Or, you can test how your package behaves when installed
2277 into a bare base system.
2278
2279
2280       <sect id="devscripts">
2281         <heading><package>devscripts</package>
2282         <p>
2283 <package>devscripts</package> is a package containing a few wrappers
2284 and tools which you may find helpful for maintaining your Debian
2285 packages.  Example scripts include <prgn>debchange</prgn> and
2286 <prgn>dch</prgn>, which manipulate your <file>debian/changelog</file>
2287 file from the command-line, and <prgn>debuild</prgn>, which is a
2288 wrapper around <prgn>dpkg-buildpackage</prgn>.
2289
2290
2291       <sect id="debget">
2292         <heading><package>debget</package>
2293         <p>
2294 <package>debget</package> is a package containing a convenient script
2295 which can be helpful in downloading files from the Debian archive.
2296 You can use it to download source packages, for instance (although
2297 <tt>apt-get source <var>package</var></tt> does pretty much the same
2298 thing).
2299
2300
2301 <!-- FIXME: add the following
2302   dpkg-awk
2303   dpkg-cross
2304   dpkg-dev-el
2305   alien
2306   dpkg-repack
2307   grep-dctrl
2308   pbuilder -->
2309
2310
2311   </book>
2312 </debiandoc>
2313
2314 <!-- Keep this comment at the end of the file
2315 Local variables:
2316 mode: sgml
2317 sgml-omittag:t
2318 sgml-shorttag:t
2319 sgml-minimize-attributes:nil
2320 sgml-always-quote-attributes:t
2321 sgml-indent-step:2
2322 sgml-indent-data:nil
2323 sgml-parent-document:nil
2324 sgml-exposed-tags:nil
2325 sgml-declaration:nil
2326 sgml-local-catalogs:nil
2327 sgml-local-ecat-files:nil
2328 End:
2329 -->