1 <!doctype debiandoc system [
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
9 Topics to be included someday:
10 - bugs in upstream versions should be reported upstream!
11 - pointer for useful tools for maintainers
16 <title>Debian Developer's Reference
17 <author>Adam P. Harris, current maintainer <email/aph@debian.org/
18 <author>Christian Schwarz <email/schwarz@debian.org/
19 <author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
20 <version>version &version;, &date;
23 Copyright ©1998 Adam P. Harris. Copyright ©1997,1998
26 This manual is free software; you may redistribute it and/or modify it
27 under the terms of the GNU General Public License as published by the
28 Free Software Foundation; either version 2, or (at your option) any
31 This is distributed in the hope that it will be useful, but
32 <em>without any warranty</em>; without even the implied warranty of
33 merchantability or fitness for a particular purpose. See the GNU
34 General Public License for more details.
36 A copy of the GNU General Public License is available as
37 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux distribution
38 or on the World Wide Web at <url
39 id="http://www.gnu.org/copyleft/gpl.html">. You can also obtain it by
40 writing to the Free Software Foundation, Inc., 59 Temple Place - Suite
41 330, Boston, MA 02111-1307, USA.
45 <chapt>Applying to Become a Maintainer
49 So, you've read all the documentation, you understand what everything
50 in the <prgn/hello/ example package is for, and you're about to
51 Debianise your favourite package. How do you actually become a Debian
52 developer so that your work can be incorporated into the Project?
54 Firstly, subscribe to <email/debian-devel@lists.debian.org/ if you
55 haven't already. Send the word <tt/subscribe/ in the <em/Subject/ of
56 a mail to <email/debian-devel-REQUEST@lists.debian.org/. In case of
57 problems contact the list administrator at
58 <email/listmaster@lists.debian.org/.
60 You should subscribe and lurk for a bit before doing any coding, and
61 you should post about your intentions to work on something to avoid
64 If you do not have a PGP key yet, generate one. You should probably
65 read the PGP manual, since it has much important information which is
66 critical to its security. Many more security failures are due to
67 human error than to software failure or high-powered spy techniques.
69 Due to export restrictions by the United States government some Debian
70 packages, including PGP, have been moved to an ftp site outside of the
71 United States. You can find the current locations of those packages on
72 <ftpsite/ftp.debian.org/ or <ftpsite/ftp.us.debian.org/ in the
73 <ftppath>/pub/debian/README.non-US</ftppath> file.
75 If you live in a country where use of cryptography even for
76 authentication is forbidden then please contact us so we can make
77 special arrangements. This does not apply in France, where I believe
78 only encryption and not authentication is forbidden.
81 <sect>Registering as a Debian developer
83 Before you decide to work in the Debian Project you have to read the
84 <url id="http://www.debian.org/social_contract" name="Debian Social
87 After that, you should send a message to
88 <email/new-maintainer@debian.org/ to register as an 'offical' Debian
89 developer so that you will be able to upload your packages.
91 The message should say what you've done and who you are, and should
92 ask for an account on <tt/master/ and to be subscribed to
93 <email/debian-private@lists.debian.org/ (the developers-only mailing
94 list). It should contain your PGP or RSA public key (extracted using
95 <tt>pgp -kxa</tt> in the case of PGP; note that <tt/gpg/ integration
96 is underway) for the database of keys which is distributed on the FTP
98 id="ftp://ftp.debian.org/pub/debian/doc/debian-keyring.tar.gz">, or
99 the <prgn>debian-keyring</prgn>> package). Please be sure to sign
100 your request message with your chosen PGP or RSA key. In addition, you
101 have to mention that you've read the ``Debian Social Contract'' (see
102 above) and you are expected to know where to find the ``Debian Policy
103 Manual'' and the ``Debian Packaging Manual.''
105 Please be sure to include your preferred login name on <tt/master/
106 (seven characters or less), as well as the email address at which
107 you'd prefer to be subscribed to
108 <email/debian-private@lists.debian.org/ (typically this will be either
109 your primary mail address or your new <tt>debian.org</tt> address).
111 You should also include some mechanism by which we can verify your
112 real-life identity. For example, any of the following mechanisms
116 A PGP or RSA key signed by any well-known signature, such as any
117 current Debian developer.
119 A scanned (or physically mailed) copy of any formal documents
120 certifying your identity (such as a birth certificate, national ID
121 card, U.S. Driver's License, etc.). Please sign the image with your
125 The following mechanisms are discouraged, but are acceptable if
126 neither of the first two mechanisms is practical:
129 A pointer to a phone listing at which you could be reached (at our
130 expense). This phone listing should be verifiable independently
131 through external means such as a national directory-listing service or
132 other authoritative source.
134 Any other mechanism by which you can establish your real-life identity
135 with reasonable certainty.
138 We're sorry about the inconvenience of requiring proof of identity,
139 but for the moment, such measures are unfortunately the only way we
140 can ensure the security and reliability of our distribution.
142 Once this information is received and processed, you should be
143 contacted with information about your new Debian maintainer account.
144 If you don't hear anything within 7-10 days, please re-send your
145 original message--the new-maintainer volunteers are typically
146 overworked, and mistakes do occasionally happen.
151 There is a mailing list called <email/debian-mentors@lists.debian.org/
152 which has been set up for newbie maintainers who seek help with
153 initial packaging and other developer-related issues.
155 Every new developer is invited to subscribe to that list (see <ref
156 id="mailing-lists"> for details).
158 Those who prefer one-on-one help (e.g., via private emails) should
159 also post to that list and an experienced developer will volunteer to
163 <chapt>Internet Servers
165 <sect id="mailing-lists">Mailing lists
167 The mailing list server is at <tt/lists.debian.org/. Mail
168 <tt/debian-<var/foo/-REQUEST@lists.debian.org/, where
169 <tt/debian-<var/foo// is the name of the list, with the word
170 <tt/subscribe/ in the Subject to subscribe or <tt/unsubscribe/ to
173 When replying to messages on the mailing list, please do not send a
174 carbon copy (<tt/CC/--this does not mean `courtesy copy') to the
175 original poster. Anyone who posts to a mailing list should read it to
178 In addition, all messages should usually only be sent to one of the
179 following mailing lists: <email/debian-devel@lists.debian.org/,
180 <email/debian-policy@lists.debian.org/,
181 <email/debian-user@lists.debian.org/,
182 <email/debian-announce@lists.debian.org/, or
183 <email/debian-devel-announce@lists.debian.org/. Cross-posting is
186 As ever on the net, please trim down the quoting of articles you're
187 replying to. In general, please adhere to the usual conventions for
191 <sect>The master server
193 The master server, <tt/master.debian.org/, holds the cannonical copy
194 of the Debian archive (excluding the non-U.S. packages). Generally,
195 package uploads go to this server; cf. <ref id="upload">. All Debian
196 developers have accounts on this machine.
198 <sect>The FTP servers
201 <sect>The WWW servers
205 <chapt>The Debian Archive
209 The Debian GNU/Linux distribution consists of a lot of Debian packages
210 (<tt/.deb/'s, currently more than 1500) and a few additional files
211 (documentation, installation disk images, etc.).
213 Here is an example directory tree of a complete Debian distribution:
217 main/binary-all/admin/
218 main/binary-all/base/
219 main/binary-all/comm/
220 main/binary-all/devel/
239 non-free/binary-i386/
240 non-free/binary-m86k/
245 As you can see, the top-level directory of the distribution contains
246 three directories, namely <em>main</>, <em>contrib</>, and
247 <em>non-free</>. These directories are called <em>sections</>.
248 <!-- NO THEY ARE NOT!!!!
249 dark: so from the current devel-ref, s/sub-section/section and s/section/SOMETHING ELSE/
251 *dark* You call main, contrib, and non-free "sections", and you call admin, base, etc "subsections".
252 *dark* The latter are called "sections" everywhere else. The former don't have a real name, but Christian used
253 | "sub-sections" in the policy manual.
254 dark: so dists/stable/main/binary-all/admin, for instance, is a "section" of the debian distribution.... and the naming for dists/stable/contrib itself is unclear
256 AFAIK, dists/stable/main is itself the actual distribution
257 <dark> aph: That's how the packaging manual describes it. And there's the "Section:" header.
258 <dark> aph: Unfortunately, Guy kind of polluted that by using contrib/section and non-free/section as sections.
260 <dark> aph: Hmm Culus may have invented a name for the something else, in his archive-description file format.
264 In each section, there is a directory with the source packages
265 (source), a directory for each supported architecture (binary-i386,
266 binary-m86k, etc.), and a directory for architecture independent
267 packages (binary-all).
269 The <em/main/ section contains additional directories which holds the
270 disk images and some essential pieces of documentation required for
271 installing the Debian distribution on a specific architecture
272 (disks-i386, disks-m68k, etc.).
274 The <em/binary/ and <em/source/ directories are divided further into
280 The <em>main section</> is what makes up the <em>Debian GNU/Linux
281 distribution</>. This is because the packages in the other two
282 sections do not fully comply with all our guidelines.
284 For example, every package in the main distribution must fully comply
285 with the <em>Debian Free Software Guidelines</> (DFSG) and with all
286 other policy requirements as described in the <em>Debian Policy
287 Manual</em>. (The DFSG is our definition of ``free software.'' Check
288 out the Debian Policy Manual for details.)
290 The packages which do not apply to the DFSG are placed in the
291 <em>non-free</> section. These packages are not considered as part of
292 the Debian distribution, though we support their use, and we provide
293 infrastructure (such as our bug-tracking system and mailing lists) for
294 non-free software packages.
296 Packages in the <em>contrib</> section have to apply to the DFSG, but
297 fail other requirements.
299 (The Debian Policy Manual contains a more exact definition of the
300 three sections. This is just meant to be an introduction.)
302 The separation of the three sections at the top-level of the archive
303 is important for all people who want to distribute Debian, either via
304 FTP servers on the Internet or on CD-ROMs: by distributing only the
305 <em/main/ and <em/contrib/ sections, one can avoid any legal risks,
306 since some packages in the <em/non-free/ section do not allow
307 commercial distribution, for example.
309 On the other hand, a CD-ROM vendor could easily check the individual
310 package licenses of the packages in <em/non-free/ and include as many
311 on the CD-ROMs as he's allowed. (Since this varies from vendor to
312 vendor very much, this job can't be done by the Debian developers.)
317 In the first days, the Linux kernel was only available for the Intel
318 i386 (or greater) platforms, and so was Debian. But when Linux became
319 more and more popular, the kernel was ported to other architectures,
322 The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs, M68000
323 machines (like Atari and Amiga), MIPS, and PowerPC.
325 Debian GNU/Linux 1.3 is only available for Intel platforms. Debian
326 2.0 supports Intel and m68k architectures. The next version of Debian
327 is likely to also support Sparc, PPC, and Alpha, if not more.
332 The sections <em/main/, <em/contrib/, and <em/non-free/ are split into
333 <em/sub sections/, to simplify the installation process and the
334 maintainance of the archive.
339 There are two types of Debian packages, namely <em/source/ and
340 <em/binary/ packages.
342 Source packages consist of either two or three files: a <tt/.dsc/
343 file, and either one <tt/.tar.gz/ file or a <tt/.orig.tar.gz/ and a
346 If a package is developed specially for Debian and is not distributed
347 outside of Debian, there is just one <tt/.tar.gz/ file which contains
348 the sources of the program.
350 If a package is distributed elsewhere too, the <tt/.orig.tar.gz/ file
351 stores the so-called <em/upstream source code/, that is the source
352 code that's distributed from the <em/upstream maintainer/ (author). In
353 this case, the <tt/.diff.gz/ contains the changes made by the Debian
356 The <tt/.dsc/ lists all components of the source package together with
357 checksums (md5sums) and some additional info about the package
358 (maintainer, version, etc.).
361 <sect>Distribution directories
363 If you have a look at the Debian FTP server or one of its mirrors,
364 you'll discover that there is one additional directory level on top of
365 the directory tree, as described in the previous chapter. These
366 directories are the <em/distribution directories/. All distributions
367 are contained in the <tt/dists/ directory in the top-level of the
368 Debian archive (the symlinks from the top-level directory to the
369 distributions themselves is for backwards compatability and
372 There is always a distribution called <em/stable/ (residing in
373 <tt>dists/stable</tt>) and one called <em/unstable/ (residing in
374 <tt>dists/unstable</tt>. This reflects the development process of the
377 The ``development'' is done in the <em/unstable/ distribution (that's
378 why this distribution is sometimes called <em/development
379 distribution/). Every Debian developer can update his or her packages in
380 this distribution at any time. Thus, the contents of this distribution
381 changes from day to day and since no special effort is done to test
382 this distribution it's sometimes ``unstable.''
384 After about two months of development, the <em/unstable/ distribution
385 is copied in a new distribution directory, called <em/frozen/. After
386 that, no changes are allowed to the frozen distribution, except bug
387 fixes. (That's why it's called ``frozen.'')
389 After another month or a little longer, the <em/frozen/ distribution
390 is renamed to <em/stable/, overriding the old <em/stable/
391 distribution, which is removed at that time.
393 This development cycle is based on the assumption, that the once
394 `unstable' distribution finally becomes `stable' after passing one
395 month of testing. Unfortunately, a few bugs still remain--that's why
396 the stable distribution is updated every now and then. However, these
397 updates are tested very carefully and have to be acknowledged
398 individually to reduce the risk of introducing new bugs. You can find
399 proposed additions to `stable' in the <tt/proposed-updates/ directory.
401 Note, that development is continued during the ``freeze'' period,
402 since a new ``unstable'' distribution will be created at that time.
404 In summary, there is always a <em/stable/ and an <em/unstable/
405 distribution available and the <em/frozen/ distribution shows up for a
406 month from time to time.
408 <sect>Release code names
410 Every released Debian distribution has a <em/code name/: Debian 1.1 is
411 called <em/buzz/, Debian 1.2 <em/rex/, Debian 1.3 <em/bo/, Debian 2.0
412 <em/hamm/, Debian 2.1 will be called <em/slink/, etc. There is also a
413 "pseudo-distribution", called <em/sid/, which is
414 used to contain packages for architectures which are not yet
415 officially supported or released by Debian. are intended to be
416 released for some future distribution.
418 Since the Debian has an open development model (i.e., everyone can
419 participate and follow the development) even the ``development
420 versions'' (unstable) are distributed via the Internet on the Debian
421 FTP server. This FTP server is mirrored by lots of other
422 systems. Thus, if we'd call the directory which contains the
423 development version simply `unstable', then we would have to rename it
424 to `stable' when the version is released, which would cause all FTP
425 mirrors to re-get the whole distribution (which is already very
428 On the other hand, if we would call the distribution directories
429 <em>Debian-x.y</em> from the beginning, people would think that Debian
430 release <em>x.y</> is available. (This happened in the past, where a
431 CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development
432 version. That's the reason why the first official Debian release was
435 Thus, the names of the distribution directories in the archive should
436 stay the same during the development period and after the release but
437 there may be symbolic links, which can be changed.
439 That's why the distribution directories use the <em/code names/ and
440 there are symbolic links <em/stable/, <em/unstable/, <em/frozen/,
441 etc., which point to the appriopriate release directories.
444 <chapt id="upload">Package uploads
446 <sect>Announcing new packages
448 If you want to create a new package for the Debian distribution, you
449 should first check the <url
450 id="http://www.debian.org/doc/prospective-packages.html"
451 name="Work-Needing and Prospective Packages (WNPP)"> page. Checking
452 the WNPP ensures that effort is not duplicated or wasted; namely, that
453 no-one is already working on packaging that software. Assuming no-one
454 else is currently working on your prospective package, you have to
455 send a short email to <email/debian-devel@lists.debian.org/ describing
456 your plan create a new package. You should set the subject of the
457 email to "intent to package <var/foobar/", substituting the name of
458 the new package for <var/foobar/.
460 There are a number of reasons why we ask maintainers to follow these
464 It helps the (potentially new) maintainer to tap into the experience
465 of people on the list, and lets them know if any one else is working
469 It lets other people thinking about working on the package know that
470 there already is a volunteer, and efforts may be shared. The "intent
471 to package" message to <email/debian-devel@lists.debian.org/ will be
472 picked up the the WNPP maintainer, and your intention will be
473 published in subsequent versions of the WNPP document.
476 It lets the rest of the maintainers know more about the package than
477 the one line description and the changelog entry "Initial version"
478 that generally gets posted to <tt/debian-devel-changes/ by default.
481 It is helpful to the people who live off unstable (and form our first
482 line of testers); we should encourage these people.
485 I think the announcements gives us a better feel of what is going on,
486 and what is new, in the project.
489 We should not dismiss anybody who installs from unstable and helps us
490 debug our packages as "fools, fools, you installed from unstable; you
491 deserve what you get"--we derive a certain benefit from the alpha
495 If we appreciate alpha testers, than any name changes have to be
496 backwards compatible with the people who already installed the old
497 package (conflict and replace old package name at a minimum).
501 <sect>Uploading a package
503 <sect1>Generating the changes file
505 When a package is uploaded to the Debian FTP archive, it must be
506 accompanied by a <tt/.changes/ file which gives directions for its
507 handling. This is usually generated by <prgn/dpkg-genchanges/.
509 This file is a control file with the following fields:
515 <item><tt/Architecture/
517 <item><tt/Distribution/
519 <item><tt/Maintainer/
520 <item><tt/Description/
525 All of them are mandatory for a Debian upload. See the list of
526 control fields in the <em/Debian Packaging Manual/ for the contents of
529 The first time a version is uploaded which corresponds to a particular
530 upstream version the original source tar file should be uploaded and
531 included in the <tt/.changes/ file; subsequent times the very same tar
532 file should be used to build the new diffs and <tt/.dsc/ files, and it
533 need not then be uploaded.
535 By default <prgn/dpkg-genchanges/ and <prgn/dpkg-buildpackage/ will
536 include the original source tar-file if and only if the Debian
537 revision part of the source version number is <tt/0/ or <tt/1/,
538 indicating a new upstream version. This behaviour may be modified by
539 using <tt/-sa/ to always include it or <tt/-sd/ to always leave it
542 If no original source is included in the upload then the original
543 source tar-file used by <prgn/dpkg-source/ when constructing the
544 <tt/.dsc/ file and diff to be uploaded <em/must/ be byte-for-byte
545 identical with the one already in the archive. If there is some
546 reason why this is not the case then the new version of the original
547 source should be uploaded, possibly by using the <tt/-sa/ flag.
550 <sect1>Checking the package prior to upload
552 Before you upload your package, you should do basic testing on it.
553 Make sure you try the following activities (you'll need to have an
554 older version of the Debian package around).
556 <item> install the package and make sure the software
559 <item> upgrade the package from an older version to your
562 <item> downgrade the package to the previous version
563 (this tests the <tt/postrm/ and <tt/prerm/ scripts)
565 <item> remove the package
567 <item> run <prgn/lintian/ over the package. You can run
568 <prgn/lintian/ as follows: <tt>lintian -v
569 <var>package-NN</var>.changes</tt>. This will check the
570 source package as well as the binary package. If you
571 don't understand the output that <prgn/lintian/
572 generates, try adding the <tt/-i/ switch, which will
573 cause <prgn/lintian/ to output a very verbose
574 description of the problem.
579 <sect1>Transferring the files to master
581 To upload a package, you need a personal account on
582 <ftpsite>master.debian.org</ftpsite>. All maintainers should already
583 have this account. You can use either <prgn/ssh/ or <prgn/ftp/ to
584 transfer the files. In either case, the files need to be placed into
585 <ftppath>/home/Debian/ftp/private/project/Incoming</ftppath>. (You
586 cannot upload to Incoming on master using anonymous FTP--you must use
587 your user-name and password.)
589 You may also find the Debian package <prgn/dupload/ useful when
590 uploading packages. This handy program is distributed with defaults
591 for uploading via <prgn/ftp/ to <tt/master/, <tt/chiark/, and
592 <tt/erlangen/. It can also be configured to use <prgn/ssh/. See
593 <manref name="dupload" section="1"> and <manref name="dupload"
594 section="5"> for more information.
597 <sect1>Uploads via Chiark
599 If you have a slow network connection to <tt/master/, there are two
600 alternatives: You can upload files to Incoming via a cron-driven
601 upload queue in Europe on <tt/chiark/. For details connect to
602 <ftpsite>ftp.chiark.greenend.org.uk</ftpsite> using anonymous FTP and
604 <ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>.
606 The program <tt/dupload/ supports uploads to chiark, please refer to
607 the documentation that comes with the program for details.
610 <sect1>Uploads via Erlangen
612 Another cron-driven upload queue is available in Germany: just upload
613 the files via anonymous FTP to <url
614 id="ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue">.
616 The upload must be a complete Debian upload, as you would put it into
617 master's <tt/Incoming/, i.e., a <tt/.changes/ files along with the
618 other files mentioned in the <tt/.changes/. The queue daemon also
619 checks that the <tt/.changes/ is correctly PGP-signed by a Debian
620 developer, so that no bogus files can find their way to master via the
621 queue. Please also make sure that the <tt/Maintainer:/ field in the
622 <tt/.changes/ contains <em/your/ e-mail address. The address found
623 there is used for all replies, just as on master.
625 There's no need to move your files into a second directory after the
626 upload as on chiark. And, in any case, you should get some mail reply
627 from the queue daemon what happened to your upload. Hopefully it
628 should have been moved to master, but in case of errors you're
631 The program <prgn/dupload/ supports uploads to erlangen, please refer
632 to the documentation that comes with the program for details.
635 <sect1>Uploading to the non-us server
637 To upload a package to the <em/non-us/ server you just have to
638 transfer the files via anonymous ftp to <url
639 id="ftp://nonus.debian.org/pub/debian-non-US/Incoming">. Note, that
640 the <tt>.changes</tt> file must have a valid PGP signature from one of
641 the keys of the developers keyring.
644 <sect>Announcing package uploads
646 When a package is uploaded an announcement should be posted to one of
647 the debian-changes lists. The announcement should give the (source)
648 package name and version number, and a very short summary of the
649 changes, in the <tt/Subject/ field, and should contain the PGP-signed
650 <tt/.changes/ file. Some additional explanatory text may be added
651 before the start of the <tt/.changes/ file.
653 If a package is released with the <tt/Distribution:/ set to
654 <tt/stable/, the announcement is sent to
655 <email/debian-changes@lists.debian.org/.
657 If a package is released with <tt/Distribution:/ set to <tt/unstable/,
658 <tt/experimental/, or <tt/frozen/ (when present), the announcement
659 should be posted to <email/debian-devel-changes@lists.debian.org/
662 If you use dupload, it is clever enough to determine for itself where
663 the announcement should go, and will automatically mail the
666 <sect>Notification that a new package has been installed
668 The Debian archive maintainers are responsible for handling package
669 uploads. For the most part, uploads are automatically handled on a
670 daily basis by an archive maintenance tool called <prgn/dinstall/.
671 Specifically, updates to existing packages to the `unstable'
672 distribution are handled automatically. In other cases, notably new
673 packages, placing the uploaded package into the distribution is
674 handled manually. When uploads are handled manually, the change to the
675 archive may take up to a week to occur (please be patient).
677 In any case, you will receive notification indicating that the package
678 has been uploaded via email. Please examine this notification
679 carefully. Sometimes the "override" file which the archive
680 maintainers use to indicate where packages go, is incorrect or
681 out-of-sync with your control file. In these cases, you should either
682 correct your control file or file a bug against <tt/ftp.debian.org/
685 <sect>Interim releases
687 Under certain circumstances it is necessary for someone other than the
688 usual package maintainer to make a release of a package. For example,
689 a porter for another architecture may have to make some small changes
690 to the source package and does not wish to wait with uploading their
691 release until the main maintainer has incorporated the patch, or a
692 serious security problem or bug may have come to light requiring
695 When a security bug is detected a fixed package should be uploaded as
696 soon as possible. In this case, the Debian Security Managers should
697 get in contact with the package maintainer to make sure a fixed
698 package is uploaded within a reasonable time (less than 48 hours). If
699 the package maintainer cannot provide a fixed package fast enough or
700 if he/she cannot be reached in time, the Security Manager may upload a
703 When someone other than the usual maintainer releases a package they
704 should add a new component to the <var/debian-revision/ component of
705 the version number--that is, the portion after the (last) hyphen.
706 This extra component will start at <tt/1/. This is to avoid
707 `stealing' one of the usual maintainer's version numbers, possibly
708 disrupting their work. If there is no <var/debian-revision/ component
709 in the version number then one should be created, starting at <tt/1/.
711 If it is absolutely necessary for someone other than the usual
712 maintainer to make a release based on a new upstream version then the
713 person making the release should start with the <var/debian-revision/
714 value <tt/0.1/. The usual maintainer of a package should start their
715 <var/debian-revision/ numbering at <tt/1/.
717 Maintainers other than the usual package maintainer should make as few
718 changes to the package as possible, and they should always send a
719 unified context diff (<tt/diff -u/) detailing their changes to the bug
720 tracking system properly flagged with the correct package so that the
721 usual maintainer is kept aware of the situation.
723 If the non-maintainer upload (as known as an "NMU") fixes some
724 existing bugs, the bug reports should not be closed. Technically,
725 only the official package maintainer or the original bug submitter are
726 allowed to close bugs. However, the person making the non-maintainer
727 release should send a short message to the bug tracking system to all
728 the fixed bugs explaining that they have been fixed. Using
729 <email/control@bugs.debian.org/, the party doing the NMU should also
730 set the severity of the bugs fixed in the NMU to "fixed". This
731 ensures that everyone knows that the bug was fixed in an NMU; however
732 the bug is left open until the changes in the NMU are incorporated
733 "officially" into the package by the offical package maintainer.
736 The normal maintainer should do at least one of
741 read the diff and decide on each part of it themselves, or
743 if the maintainer decides not to apply the patch but to release a new
744 version, read the description of the changes to the next upstream
745 version and ensure that they fix each problem that was fixed in the
746 non-maintainer release.
749 In addition, the normal maintainer should <em/always/ include an entry
750 in the changelog file documenting the non-maintainer upload.
753 <sect>Maintainer changes
755 Periodically, a listing of packages in need of new maintainers will be
756 sent to <email/debian-devel@lists.debian.org</email> list. This list
757 is also available at in the Work-Needing and Prospective Packages
758 document (WNPP), <url
759 id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html">
761 id="http://www.debian.org/doc/prospective-packages.html">. If you wish
762 to take over maintenance of any of the packages listed in the WNPP, or
763 if you can no longer maintain a packages you have, or you simply want
764 to know if any one is working on a new package, send a message to
765 <email/wnpp@debian.org/.
767 If you take over an old package, you probably want to be listed as the
768 package's official maintainer in the bug system. This will happen
769 automatically once you upload a new version with an updated
770 <tt/Maintainer:/ field. If you do not expect to upload a new version
771 for a while, send an email to <email/override-change@debian.org/ so
772 that bug reports will go to you.
775 <chapt>Handling bug reports
777 <sect>Bugs in your packages
779 If you want to be a good maintainer, you should periodically check the
780 <url id="http://www.debian.org/Bugs/" name="Debian bug tracking system
781 (BTS)"> for your packages. The BTS contains all the open bugs against
784 If you fix a bug in your packages, it is your responsibility as the
785 package maintainer to close the bug when it has been fixed. However,
786 you should not close the bug until the package which fixes the bug has
787 been accepted into the Debian archive. Therefore, once you get
788 notification that your updated package has been installed into the
789 archive, you can and should close the bug in the BTS.
791 Maintainers interact with the BTS via email addresses at
792 <tt/bugs.debian.org/. Documentation on available commands can be
793 found in <tt>/usr/doc/debian/bug-*</tt> from the <prgn/debian-doc/
796 <sect>Lintian reports
798 You should periodically get the new <prgn/lintian/ from `unstable' and
799 check over all your packages. Alternatively you can check for you're
800 maintainer email address at <url
801 id="http://www.debian.org/lintian/">. That page, which is
802 updated automatically, contains lintian reports against the latest
803 version of the package (usually from 'unstable') using the latest
807 <sect>Reporting lots of bugs at once
809 If you report more then 10 bugs on the same topic at once, it is
810 recommended that you send a message to
811 <email/debian-devel@lists.debian.org/ describing your intention before
812 submitting the report. This will allow other developers to verify that
813 the bug is a real problem. In addition, it will prevent the situation
814 where several maintainers start filing the same bug report
817 Note, that when sending lots of bugs on the same subject, you should
818 send the bug report to <email/maintonly@bugs.debian.org/ so that the
819 bug report is not forwarded to the bug distribution mailing list.
825 <!-- Keep this comment at the end of the file
830 sgml-minimize-attributes:nil
831 sgml-always-quote-attributes:t
834 sgml-parent-document:nil
835 sgml-exposed-tags:nil
836 sgml-local-catalogs:nil
837 sgml-local-ecat-files:nil