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