1 <!doctype debiandoc system>
4 Debian GNU/Linux Developer's Reference.
5 Copyright (C)1997,1998 Christian Schwarz;
6 released under the terms of the GNU
7 General Public License, version 2 or (at your option) any later.
12 Topics to be included someday:
13 - bugs in upstream versions should be reported upstream!
19 <title>Debian Developer's Reference
20 <author>Christian Schwarz <email/schwarz@debian.org/
21 <author>based on earlier documents by Ian Jackson <email/ijackson@gnu.ai.mit.edu/
22 <version>version 2.4.1.2, 14 April 1998
24 <copyright>Copyright ©1997,1998 Christian Schwarz.
27 This manual is free software; you may redistribute it and/or modify it
28 under the terms of the GNU General Public License as published by the
29 Free Software Foundation; either version 2, or (at your option) any
33 This is distributed in the hope that it will be useful, but
34 <em>without any warranty</em>; without even the implied warranty of
35 merchantability or fitness for a particular purpose. See the GNU
36 General Public License for more details.
39 A copy of the GNU General Public License is available as
40 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
41 distribution or on the World Wide Web at
42 <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also obtain it
43 by writing to the Free Software Foundation, Inc., 59 Temple Place -
44 Suite 330, Boston, MA 02111-1307, USA.
49 <chapt>Applying to Become a Maintainer<p>
54 So, you've read all the documentation, you understand what
55 everything in the <prgn/hello/ example package is for, and
56 you're about to Debianise your favourite package. How do
57 you actually become a Debian developer so that your work can
58 be incorporated into the Project?
61 Firstly, subscribe to <prgn/debian-devel/ if you haven't
62 already. Send the word <tt/subscribe/ in the <em/Subject/
63 of a mail to <email/debian-devel-REQUEST@lists.debian.org/.
64 In case of problems contact the list administrator at
65 <email/listmaster@lists.debian.org/.
68 You should subscribe and lurk for a bit before doing any
69 coding, and you should post about your intentions to work on
70 something to avoid duplicated effort.
73 If you do not have a PGP key yet generate one. You should
74 probably read the PGP manual, as it has much important
75 information which is critical to its security. Many more
76 security failures are due to human error than to software
77 failure or high-powered spy techniques.
80 Due to export restrictions by the United States government
81 some Debian packages, including PGP, have been moved to an
82 ftp site outside of the United States. You can find the
83 current locations of those packages on
84 <ftpsite/ftp.debian.org/ in the
85 <ftppath>/pub/debian/README.non-US</> file.
88 If you live in a country where use of cryptography even for
89 authentication is forbidden then please contact us so we can
90 make special arrangements. This does not apply in France,
91 where I believe only encryption and not authentication is
95 <sect>Registering as a Debian developer
98 Before you decide to work in the Debian Project you have to
99 read the ``Debian Social Contract'' (available on
100 <tt/www.debian.org/).
102 After that, you should send a message to
103 <email/new-maintainer@debian.org/ to register as an
104 'offical' Debian developer so that you will be able to
105 upload your packages.
107 The message should say what you've done and who you are, and
108 should ask for an account on master and to be subscribed to
109 debian-private (the developers-only mailing list). It should
110 contain your PGP or RSA public key (extracted using `pgp
111 -kxa', in the case of PGP) for the database of keys which is
112 distributed on the FTP server
113 (<tt>doc/debian-keyring.tar.gz</tt>). Please be sure to
114 sign your request message with your chosen PGP or RSA
115 key. In addition, you have to mention that you've read the
116 ``Debian Social Contract'' (see above) and you are expected
117 to know where to find the ``Debian Policy Manual'' and the
118 ``Debian Packaging Manual.''
120 Please be sure to include your preferred login name on
121 master (seven characters or less), as well as the E-mail
122 address at which you'd prefer to be subscribed to
123 debian-private (typically this will be either your primary
124 mail address or your new debian.org address).
126 You should also include some mechanism by which we can
127 verify your real-life identity. For example, any of the
128 following mechanisms would suffice:
131 <item>A PGP or RSA key signed by any well-known signature,
132 such as any current Debian developer.
133 <item>A scanned (or physically mailed) copy of any formal
134 documents certifying your identity (such as a birth
135 certificate, national ID card, U.S. Driver's License,
136 etc.). Please sign the image with your PGP or RSA key.
139 The following mechanisms are discouraged, but are acceptable if
140 neither of the first two mechanisms is practical:
142 <item>A pointer to a phone listing at which you could be
143 reached (at our expense). This phone listing should
144 be verifiable independently through external means
145 such as a national directory-listing service or other
146 authoritative source.
147 <item>Any other mechanism by which you can establish your
148 real-life identity with reasonable certainty.
151 We're sorry about the inconvenience of requiring proof of
152 identity, but for the moment, such measures are
153 unfortunately the only way we can ensure the security and
154 reliability of our distribution.
157 Once this information is received and processed, you should
158 be contacted with information about your new Debian
159 maintainer account. If you don't hear anything within 7-10
160 days, please re-send your original message--the
161 new-maintainer volunteers are typically overworked, and
162 mistakes do occasionally happen.
168 There is a mailing list called <tt/debian-mentors/ which has
169 been set up for newbie maintainers who seek help with
170 initial packaging and other developer-related issues.
172 Every new developer is invited to subscribe to that list
173 (see <ref id="mailing-lists"> for details).
175 Those who prefer one-on-one help (e.g., via private emails)
176 should also post to that list and an experienced developer
177 will volunteer to help.
181 <chapt>Internet Servers<p>
183 <sect id="mailing-lists">Mailing lists<p>
185 The mailing list server is at <tt/lists.debian.org/. Mail
186 <tt/debian-<var/foo/-REQUEST@lists.debian.org/, where
187 <tt/debian-<var/foo// is the name of the list, with the word
188 <tt/subscribe/ in the Subject to subscribe or
189 <tt/unsubscribe/ to unsubscribe.
191 When replying to messages on the mailing list, please do not
192 send a carbon copy (<tt/CC/--this does not mean `courtesy
193 copy') to the original poster. Anyone who posts to a
194 mailing list should read it to see the responses.
196 In addition, all messages should usually only be sent to one
197 of the following mailing lists: <tt/debian-devel/,
198 <tt/debian-policy/, <tt/debian-user/, <tt/debian-announce/,
199 <tt/debian-devel-announce/.
201 As ever on the net, please trim down the quoting of articles
202 you're replying to. In general, please adhere to the usual
203 conventions for posting messages.
206 <sect>The master server
209 <sect>The FTP servers
212 <sect>The WWW servers
215 <chapt>The Debian Archive<p>
220 The Debian GNU/Linux distribution consists of a lot of
221 Debian packages (<tt/.deb/'s, currently more than 1000) and
222 a few additional files (documentation, installation disk
225 Here is an example directory tree of a complete Debian
230 main/binary-all/admin/
231 main/binary-all/base/
232 main/binary-all/comm/
233 main/binary-all/devel/
252 non-free/binary-i386/
253 non-free/binary-m86k/
258 As you can see, the top-level directory of the distribution
259 contains three directories, namely <em>main</>,
260 <em>contrib</>, and <em>non-free</>. These directories are
261 called <em>sections</>.
263 In each section, there is a directory with the source
264 packages (source), a directory for each supported
265 architecture (binary-i386, binary-m86k, etc.), and a
266 directory for architecture independent packages
269 The <em/main/ section contains additional directories which
270 holds the disk images and some essential pieces of
271 documentation required for installing the Debian
272 distribution on a specific architecture (disks-i386,
275 The <em/binary/ and <em/source/ directories are divided
276 further into <em/sub-sections/.
282 The <em>main section</> is what makes up the <em>Debian
283 GNU/Linux distribution</>. This is because the packages in
284 the other two sections do not fully comply with all our
287 For example, every package in the main distribution must
288 fully comply with the <em>Debian Free Software Guidelines</>
289 (DFSG) and with all other policy requirements as described
290 in the <em>Debian Policy Manual</em>. (The DFSG is our
291 definition of ``free software.'' Check out the Debian Policy
294 The packages which do not apply to the DFSG are placed in
295 the <em>non-free</> section. These packages are not
296 considered as part of the Debian distribution, though we
297 support their use, and we provide infrastructure (such as
298 our bug-tracking system and mailing lists) for non-free
301 Packages in the <em>contrib</> section have to apply to
302 the DFSG, but fail other requirements.
304 (The Debian Policy Manual contains a more exact definition
305 of the three sections. This is just meant to be an
308 The separation of the three sections at the top-level of
309 the archive is important for all people who want to
310 distribute Debian, either via FTP servers on the Internet
311 or on CD-ROMs: by distributing only the <em/main/ and
312 <em/contrib/ sections, one can avoid any legal risks,
313 since some packages in the <em/non-free/ section do not
314 allow commercial distribution, for example.
316 On the other hand, a CD-ROM vendor could easily check the
317 individual package licenses of the packages in <em/non-free/
318 and include as many on the CD-ROMs as he's allowed. (Since
319 this varies from vendor to vendor very much, this job can't
320 be done by the Debian developers.)
326 In the first days, the Linux kernel was only available for
327 the Intel i386 (or greater) platforms, and so was
328 Debian. But when Linux became more and more popular, the
329 kernel was ported to other architectures, too.
331 The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs,
332 M68000 machines (like Atari and Amiga), MIPS, and
335 Debian GNU/Linux 1.3 is only available for Intel
336 platforms. One of the goals for Debian 2.0 is to support
337 some of the other architectures, too.
343 The sections <em/main/, <em/contrib/, and <em/non-free/ are
344 split into <em/sub sections/, to simplify the installation
345 process and the maintainance of the archive.
351 There are two types of Debian packages, namely <em/source/
352 and <em/binary/ packages.
354 Source packages consist of either two or three files: a
355 <tt/.dsc/ file, and either one <tt/.tar.gz/ file or a
356 <tt/.orig.tar.gz/ and a <tt/.diff.gz/ file.
358 If a package is developed specially for Debian and is not
359 distributed outside of Debian, there is just one
360 <tt/.tar.gz/ file which contains the sources of the program.
362 If a package is distributed elsewhere too, the
363 <tt/.orig.tar.gz/ file stores the so-called <em/upstream
364 source code/, that is the source code that's distributed
365 from the <em/upstream maintainer/ (author). In this case,
366 the <tt/.diff.gz/ contains the changes made by the Debian
369 The <tt/.dsc/ lists all components of the source package
370 together with checksums (md5sums) and some additional info
371 about the package (maintainer, version, etc.).
374 <sect>Distribution directories
377 If you have a look at the Debian FTP server or one of its
378 mirrors, you'll discover that there is one additional
379 directory level on top of the directory tree, as described
380 in the previous chapter. These directories are the
381 <em/distribution directories/.
383 There is always a distribution called <em/stable/ and one
384 called <em/unstable/. This reflects the development process
385 of the Debian project:
387 The ``development'' is done in the <em/unstable/
388 distribution (that's why this distribution is sometimes
389 called <em/development distribution/). Every Debian
390 developer can update his/her packages in this distribution
391 at any time. Thus, the contents of this distribution changes
392 from day to day and since no special effort is done to test
393 this distribution it's sometimes ``unstable.''
395 After about two months of development, the <em/unstable/
396 distribution is copied in a new distribution directory,
397 called <em/frozen/. After that, no changes are allowed to
398 the frozen distribution, except bug fixes. (That's why it's
401 After another month or a little longer, the <em/frozen/
402 distribution is renamed to <em/stable/, overriding the old
403 <em/stable/ distribution, which is removed at that time.
405 This development cycle is based on the assumption, that the
406 once `unstable' distribution finally becomes `stable' after
407 passing one month of testing. Unfortunately, a few bugs
408 still remain--that's why the stable distribution is updated
409 every few weeks. However, these updates are tested very
410 carefully and have to be acknowledged individually to reduce
411 the risk of introducing new bugs.
413 Note, that development is continued during the ``freeze''
414 period, since a new ``unstable'' distribution will be
415 created at that time.
417 In summary, there is always a <em/stable/ and an
418 <em/unstable/ distribution available and the <em/frozen/
419 distribution shows up for a month from time to time.
422 <sect>Release code names
424 Every released Debian distribution has a <em/code name/:
425 Debian 1.1 is called <em/buzz/, Debian 1.2 <em/rex/, Debian
426 1.3 <em/bo/, Debian 2.0 <em/hamm/, etc.
428 Since the Debian has an open development (i.e. everyone can
429 participate and follow the development) even the
430 ``development versions'' (unstable) are distributed via the
431 Internet on the Debian FTP server. This FTP server is
432 mirrored by lots of other systems. Thus, if we'd call the
433 directory which contains the development version simply
434 `unstable', then we would have to rename it to `stable' when
435 the version is released, which would cause all FTP mirrors
436 to re-get the whole distribution (which is already very
439 On the other hand, if we would call the distribution
440 directories <em>Debian-x.y</em> from the beginning, people
441 would think that Debian release <em>x.y</> is
442 available. (This happened in the past, where a CD-ROM vendor
443 built a Debian 1.0 CD-ROM based on a pre-1.0 development
444 version. That's the reason why the first official Debian
445 release was 1.1, and not 1.0.)
447 Thus, the names of the distribution directories in the
448 archive should stay the same during the development period
449 and after the release but there may be symbolic links, which
452 That's why the distribution directories use the <em/code
453 names/ and there are symbolic links <em/stable/,
454 <em/unstable/, <em/frozen/, etc. which point to the
455 appriopriate release directories.
458 <chapt>Package uploads<p>
460 <sect>Announcing new packages
462 If you want to create a new package for the Debian
463 distribution, you have to send a short email to
464 <em/debian-devel/ describing your plans before you upload
467 This has the following advantages:
470 <item>It helps the (potentially new) maintainer to tap
471 into the experience of people on the list, and lets
472 them know if any one else is working on it already
474 <item>It lets other people thinking about working on the
475 package know that there already is a volunteer, and
476 efforts may be shared
478 <item>It lets the rest of the maintainers know more about
479 the package than the one line description and the
480 changelog entry "Initial version" that generally gets
481 posted to debian-devel-changes by default
483 <item>It is helpful to the people who live off unstable
484 (and form our first line of testers); we should
485 encourage these people
487 <item>I think the announcements gives us a better feel of
488 what is going on, and what is new, in the project.
490 <item>We should not dismiss anybody who installs from
491 unstable and helps us debug our packages as "fools,
492 fools, you installed from unstable; you deserve what
493 you get"--we derive a certain benefit from the alpha
496 <item>If we appreciate alpha testers, than any name
497 changes have to be backwards compatible with the
498 people who already installed the old package (conflict
499 and replace old package name at a minimum)
502 <sect>Uploading a package
505 <sect1>Generating the changes file
508 When a package is uploaded to the Debian FTP archive, it
509 must be accompanied by a <tt/.changes/ file which gives
510 directions for its handling. This is usually generated by
511 <prgn/dpkg-genchanges/.
514 This file is a control file with the following fields:
520 <item><tt/Architecture/
522 <item><tt/Distribution/
524 <item><tt/Maintainer/
525 <item><tt/Description/
531 All of them are mandatory for a Debian upload. See the
532 list of control fields in the <em/Debian Packaging Manual/
533 for the contents of these fields.
536 The first time a version is uploaded which corresponds to
537 a particular upstream version the original source tar file
538 should be uploaded and included in the <tt/.changes/ file;
539 subsequent times the very same tar file should be used to
540 build the new diffs and <tt/.dsc/ files, and it need not
544 By default <prgn/dpkg-genchanges/ and
545 <prgn/dpkg-buildpackage/ will include the original source
546 tar-file if and only if the Debian revision part of the
547 source version number is <tt/0/ or <tt/1/, indicating a
548 new upstream version. This behaviour may be modified by
549 using <tt/-sa/ to always include it or <tt/-sd/ to always
553 If no original source is included in the upload then the
554 original source tar-file used by <prgn/dpkg-source/ when
555 constructing the <tt/.dsc/ file and diff to be uploaded
556 <em/must/ be byte-for-byte identical with the one already
557 in the archive. If there is some reason why this is not
558 the case then the new version of the original source
559 should be uploaded, possibly by using the <tt/-sa/ flag.
562 <sect1>Transferring the files to master
564 To upload a package, you need a personal account on the
565 master server. Just log in via ftp and transfer the
567 `<tt>/home/Debian/ftp/private/project/Incoming</tt>.'
568 (You cannot upload to Incoming on master using anonymous
569 FTP--you must use your user-name and password.)
571 You may also find the Debian package '<tt>dupload</tt>'
572 useful in uploading new packages to master. See the
573 '<tt>dupload</tt>' documentation for more information.
576 <sect1>Uploads via Chiark
578 If you have a slow network connection to the master
579 system, there are two alternatives: You can upload files
580 to Incoming via a cron-driven upload queue in Europe on
581 ftp.chiark.greenend.org.uk. For details connect to chiark
582 using anonymous FTP and read
583 <tt>/pub/debian/private/project/README.how-to-upload</tt>.
585 The program <tt/dupload/ support uploads to chiark, please
586 refer to the documentation that comes with the program,
590 <sect1>Uploads via Erlangen
592 Another cron-driven upload queue is available in Germany:
593 Just upload the files via anonymous FTP to
594 <tt>ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue</>.
596 The upload must be a complete Debian upload, as you would
597 put it into master's incoming, i.e. a <tt/.changes/ files
598 along with the other files mentioned in the
599 <tt/.changes/. The queue daemon also checks that the
600 <tt/.changes/ is correctly PGP-signed by a Debian
601 developer, so that no bogus files can find their way to
602 master via the queue. Please also make sure that the
603 <tt/Maintainer:/ field in the <tt/.changes/ contains
604 *your* e-mail address. The address found there is used for
605 all replies, just as on master.
607 There's no need to move your files into a second directory
608 after the upload as on chiark. And, in any case, you
609 should get some mail reply from the queue daemon what
610 happened to your upload. Hopefully it should have been
611 moved to master, but in case of errors you're notified,
614 The program <tt/dupload/ support uploads to erlangen,
615 please refer to the documentation that comes with the
616 program, for details.
619 <sect1>Uploading to the non-us server
621 To upload a package to the <em/non-us/ server you just
622 have to transfer the files via anonymous ftp to
623 <tt>ftp://nonus.debian.org/pub/debian-non-US/Incoming</tt>.
624 Note, that the <tt>.changes</tt> file must have a valid
625 PGP signature from one of the keys of the developers
629 <sect>Announcing package uploads
631 When a package is uploaded an announcement should be posted
632 to one of the debian-changes lists. The announcement should
633 give the (source) package name and version number, and a
634 very short summary of the changes, in the <prgn/Subject/
635 field, and should contain the PGP-signed <tt/.changes/ file.
636 Some additional explanatory text may be added before the
637 start of the <tt/.changes/ file.
639 If a package is released with the <tt/Distribution:/ set to
640 <tt/stable/, the announcement is sent to
641 <email/debian-changes@lists.debian.org/.
643 If a package is released with <tt/Distribution:/ set to
644 <tt/unstable/, <tt/experimental/, or <tt/frozen/ (when
645 present), the announcement should be posted to
646 <email/debian-devel-changes@lists.debian.org/ instead.
649 <sect>Interim releases
651 Under certain circumstances it is necessary for someone
652 other than the usual package maintainer to make a release of
653 a package. For example, a porter for another architecture
654 may have to make some small changes to the source package
655 and does not wish to wait with uploading their release until
656 the main maintainer has incorporated the patch, or a serious
657 security problem may have come to light requiring immediate
660 When a security bug is detected a fixed package should be
661 uploaded as soon as possible. In this case, the Debian
662 Security Managers should get in contact with the package
663 maintainer to make sure a fixed package is uploaded within a
664 reasonable time (less than 48 hours). If the package
665 maintainer cannot provide a fixed package fast enough or if
666 he/she cannot be reached in time, the Security Manager
667 may upload a fixed package.
669 When someone other than the usual maintainer releases a
670 package they should add a new component to the
671 <var/debian-revision/ component of the version number--that
672 is, the portion after the (last) hyphen. This extra
673 component will start at <tt/1/. This is to avoid `stealing'
674 one of the usual maintainer's version numbers, possibly
675 disrupting their work. If there is no <var/debian-revision/
676 component in the version number then one should be created,
679 If it is absolutely necessary for someone other than the
680 usual maintainer to make a release based on a new upstream
681 version then the person making the release should start with
682 the <var/debian-revision/ value <tt/0.1/. The usual
683 maintainer of a package should start their
684 <var/debian-revision/ numbering at <tt/1/.
686 Maintainers other than the usual package maintainer should
687 make as few changes to the package as possible, and they
688 should always send a unified context diff (<tt/diff -u/)
689 detailing their changes to the bug tracking system properly
690 flagged with the correct package so that the usual
691 maintainer is kept aware of the situation. If the
692 non-maintainer upload fixes some bugs, the bug reports
693 should not be closed. However, the person making the
694 non-maintainer release should send a short message to the
695 bug tracking system to all the fixed bugs explaining that
696 they have been fixed. This way, the maintainer and other
697 people will get notified about that.
699 The normal maintainer should do at least one of
701 <item> apply the diff,
703 <item> read the diff and decide on each part of it
706 <item> if the maintainer decides not to apply the patch
707 but to release a new version, read the description of the
708 changes to the next upstream version and ensure that they
709 fix each problem that was fixed in the non-maintainer
713 In addition, the normal maintainer should <em/always/
714 include an entry in the changelog file documenting the
715 non-maintainer upload.
718 <sect>Maintainer changes
720 Periodically, a listing of packages in need of new
721 maintainers will be sent to the <tt>debian-devel</>
722 list. This list is also available at
723 <ftpsite>ftp.debian.org</> in
724 <ftppath>/debian/doc/package-developer/prospective-packages.html</>
725 If you wish to take over maintenance of any of those
726 packages, or if you can no longer maintain the packages you
727 have, or you simply want to know if any one is working on a
728 new package, send a message to
729 <email/override-change@debian.org/.
731 If you take over an old package, you probably want to be
732 listed as the package's official maintainer in the bug
733 system. This will happen automatically once you upload a new
734 version with an updated <tt/Maintainer:/ field. If you do
735 not expect to upload a new version for a while, send an
736 email to <email/override-change@debian.org/ so that bug
737 reports will go to you.
740 <chapt>Handling bug reports<p>
742 <sect>Reporting lots of bugs at once
744 If you report more then 10 bugs on the same topic at once,
745 it is recommended that you send a message to debian-devel
746 describing your intention before submitting the report. This
747 will allow other developers to verify that the bug is a real
748 problem. In addition, it will prevent the situation where
749 several maintainers start filing the same bug report
752 Note, that when sending lots of bugs on the same subject,
753 you should send the bug report to
754 <tt/maintonly@bugs.debian.org/ so that the bug report is not
755 forwarded to the bug distribution mailing list.