Topics to be included someday:
- bugs in upstream versions should be reported upstream!
- - how to be a good non-maintainer
+ - pointer for useful tools for maintainers
-->
<book>
Debianise your favourite package. How do you actually become a Debian
developer so that your work can be incorporated into the Project?
<p>
-Firstly, subscribe to <prgn/debian-devel/ if you haven't already.
-Send the word <tt/subscribe/ in the <em/Subject/ of a mail to
-<email/debian-devel-REQUEST@lists.debian.org/. In case of problems
-contact the list administrator at <email/listmaster@lists.debian.org/.
+Firstly, subscribe to <email/debian-devel@lists.debian.org/ if you
+haven't already. Send the word <tt/subscribe/ in the <em/Subject/ of
+a mail to <email/debian-devel-REQUEST@lists.debian.org/. In case of
+problems contact the list administrator at
+<email/listmaster@lists.debian.org/.
<p>
You should subscribe and lurk for a bit before doing any coding, and
you should post about your intentions to work on something to avoid
duplicated effort.
<p>
-If you do not have a PGP key yet generate one. You should probably
-read the PGP manual, as it has much important information which is
+If you do not have a PGP key yet, generate one. You should probably
+read the PGP manual, since it has much important information which is
critical to its security. Many more security failures are due to
human error than to software failure or high-powered spy techniques.
<p>
Due to export restrictions by the United States government some Debian
packages, including PGP, have been moved to an ftp site outside of the
United States. You can find the current locations of those packages on
-<ftpsite/ftp.debian.org/ in the <ftppath>/pub/debian/README.non-US</>
-file.
+<ftpsite/ftp.debian.org/ or <ftpsite/ftp.us.debian.org/ in the
+<ftppath>/pub/debian/README.non-US</ftppath> file.
<p>
If you live in a country where use of cryptography even for
authentication is forbidden then please contact us so we can make
special arrangements. This does not apply in France, where I believe
only encryption and not authentication is forbidden.
- <p>
+
<sect>Registering as a Debian developer
<p>
developer so that you will be able to upload your packages.
<p>
The message should say what you've done and who you are, and should
-ask for an account on master and to be subscribed to debian-private
-(the developers-only mailing list). It should contain your PGP or RSA
-public key (extracted using `pgp -kxa', in the case of PGP) for the
-database of keys which is distributed on the FTP server
-(<tt>doc/debian-keyring.tar.gz</tt>). Please be sure to sign your
-request message with your chosen PGP or RSA key. In addition, you have
-to mention that you've read the ``Debian Social Contract'' (see above)
-and you are expected to know where to find the ``Debian Policy
+ask for an account on <tt/master/ and to be subscribed to
+<email/debian-private@lists.debian.org/ (the developers-only mailing
+list). It should contain your PGP or RSA public key (extracted using
+<tt>pgp -kxa</tt> in the case of PGP; note that <tt/gpg/ integration
+is underway) for the database of keys which is distributed on the FTP
+server (<url
+id="ftp://ftp.debian.org/pub/debian/doc/debian-keyring.tar.gz">, or
+the <prgn>debian-keyring</prgn>> package). Please be sure to sign
+your request message with your chosen PGP or RSA key. In addition, you
+have to mention that you've read the ``Debian Social Contract'' (see
+above) and you are expected to know where to find the ``Debian Policy
Manual'' and the ``Debian Packaging Manual.''
<p>
-Please be sure to include your preferred login name on master (seven
-characters or less), as well as the E-mail address at which you'd
-prefer to be subscribed to debian-private (typically this will be
-either your primary mail address or your new debian.org address).
+Please be sure to include your preferred login name on <tt/master/
+(seven characters or less), as well as the email address at which
+you'd prefer to be subscribed to
+<email/debian-private@lists.debian.org/ (typically this will be either
+your primary mail address or your new <tt>debian.org</tt> address).
<p>
You should also include some mechanism by which we can verify your
real-life identity. For example, any of the following mechanisms
<sect>Debian Mentors
<p>
-There is a mailing list called <tt/debian-mentors/ which has been set
-up for newbie maintainers who seek help with initial packaging and
-other developer-related issues.
+There is a mailing list called <email/debian-mentors@lists.debian.org/
+which has been set up for newbie maintainers who seek help with
+initial packaging and other developer-related issues.
<p>
Every new developer is invited to subscribe to that list (see <ref
id="mailing-lists"> for details).
see the responses.
<p>
In addition, all messages should usually only be sent to one of the
-following mailing lists: <tt/debian-devel/, <tt/debian-policy/,
-<tt/debian-user/, <tt/debian-announce/, <tt/debian-devel-announce/.
+following mailing lists: <email/debian-devel@lists.debian.org/,
+<email/debian-policy@lists.debian.org/,
+<email/debian-user@lists.debian.org/,
+<email/debian-announce@lists.debian.org/, or
+<email/debian-devel-announce@lists.debian.org/. Cross-posting is
+discouraged.
<p>
As ever on the net, please trim down the quoting of articles you're
replying to. In general, please adhere to the usual conventions for
<sect>The master server
<p>
+The master server, <tt/master.debian.org/, holds the cannonical copy
+of the Debian archive (excluding the non-U.S. packages). Generally,
+package uploads go to this server; cf. <ref id="upload">. All Debian
+developers have accounts on this machine.
<sect>The FTP servers
<p>
<sect>Overview
<p>
The Debian GNU/Linux distribution consists of a lot of Debian packages
-(<tt/.deb/'s, currently more than 1000) and a few additional files
+(<tt/.deb/'s, currently more than 1500) and a few additional files
(documentation, installation disk images, etc.).
<p>
Here is an example directory tree of a complete Debian distribution:
As you can see, the top-level directory of the distribution contains
three directories, namely <em>main</>, <em>contrib</>, and
<em>non-free</>. These directories are called <em>sections</>.
+<!-- NO THEY ARE NOT!!!!
+dark: so from the current devel-ref, s/sub-section/section and s/section/SOMETHING ELSE/
+
+*dark* You call main, contrib, and non-free "sections", and you call admin, base, etc "subsections".
+*dark* The latter are called "sections" everywhere else. The former don't have a real name, but Christian used
+ | "sub-sections" in the policy manual.
+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
+<dark> aph: Yep.
+AFAIK, dists/stable/main is itself the actual distribution
+<dark> aph: That's how the packaging manual describes it. And there's the "Section:" header.
+<dark> aph: Unfortunately, Guy kind of polluted that by using contrib/section and non-free/section as sections.
+
+<dark> aph: Hmm Culus may have invented a name for the something else, in his archive-description file format.
+
+-->
<p>
In each section, there is a directory with the source packages
(source), a directory for each supported architecture (binary-i386,
machines (like Atari and Amiga), MIPS, and PowerPC.
<p>
Debian GNU/Linux 1.3 is only available for Intel platforms. Debian
-2.0 supports Intel and m68k architectures.
+2.0 supports Intel and m68k architectures. The next version of Debian
+is likely to also support Sparc, PPC, and Alpha, if not more.
<sect>Sub sections
If you have a look at the Debian FTP server or one of its mirrors,
you'll discover that there is one additional directory level on top of
the directory tree, as described in the previous chapter. These
-directories are the <em/distribution directories/.
+directories are the <em/distribution directories/. All distributions
+are contained in the <tt/dists/ directory in the top-level of the
+Debian archive (the symlinks from the top-level directory to the
+distributions themselves is for backwards compatability and
+deprecated).
<p>
-There is always a distribution called <em/stable/ and one called
-<em/unstable/. This reflects the development process of the Debian
-project:
+There is always a distribution called <em/stable/ (residing in
+<tt>dists/stable</tt>) and one called <em/unstable/ (residing in
+<tt>dists/unstable</tt>. This reflects the development process of the
+Debian project.
<p>
The ``development'' is done in the <em/unstable/ distribution (that's
why this distribution is sometimes called <em/development
-distribution/). Every Debian developer can update his/her packages in
+distribution/). Every Debian developer can update his or her packages in
this distribution at any time. Thus, the contents of this distribution
changes from day to day and since no special effort is done to test
this distribution it's sometimes ``unstable.''
This development cycle is based on the assumption, that the once
`unstable' distribution finally becomes `stable' after passing one
month of testing. Unfortunately, a few bugs still remain--that's why
-the stable distribution is updated every few weeks. However, these
+the stable distribution is updated every now and then. However, these
updates are tested very carefully and have to be acknowledged
-individually to reduce the risk of introducing new bugs.
+individually to reduce the risk of introducing new bugs. You can find
+proposed additions to `stable' in the <tt/proposed-updates/ directory.
<p>
Note, that development is continued during the ``freeze'' period,
since a new ``unstable'' distribution will be created at that time.
<p>
Every released Debian distribution has a <em/code name/: Debian 1.1 is
called <em/buzz/, Debian 1.2 <em/rex/, Debian 1.3 <em/bo/, Debian 2.0
-<em/hamm/, Debian 2.1 will be called <em/slink/, etc.
+<em/hamm/, Debian 2.1 will be called <em/slink/, etc. There is also a
+"pseudo-distribution", called <em/sid/, which is
+used to contain packages for architectures which are not yet
+officially supported or released by Debian. are intended to be
+released for some future distribution.
<p>
-Since the Debian has an open development (i.e., everyone can
+Since the Debian has an open development model (i.e., everyone can
participate and follow the development) even the ``development
versions'' (unstable) are distributed via the Internet on the Debian
FTP server. This FTP server is mirrored by lots of other
<p>
That's why the distribution directories use the <em/code names/ and
there are symbolic links <em/stable/, <em/unstable/, <em/frozen/,
-etc. which point to the appriopriate release directories.
+etc., which point to the appriopriate release directories.
- <chapt>Package uploads
+ <chapt id="upload">Package uploads
<sect>Announcing new packages
<p>
If you want to create a new package for the Debian distribution, you
-have to send a short email to <em/debian-devel/ describing your plans
-before you upload the new package.
- <p>
-This has the following advantages:
-
+should first check the <url
+id="http://www.debian.org/doc/prospective-packages.html"
+name="Work-Needing and Prospective Packages (WNPP)"> page. Checking
+the WNPP ensures that effort is not duplicated or wasted; namely, that
+no-one is already working on packaging that software. Assuming no-one
+else is currently working on your prospective package, you have to
+send a short email to <email/debian-devel@lists.debian.org/ describing
+your plan create a new package. You should set the subject of the
+email to "intent to package <var/foobar/", substituting the name of
+the new package for <var/foobar/.
+ <p>
+There are a number of reasons why we ask maintainers to follow these
+steps.
<list compact>
<item>
It helps the (potentially new) maintainer to tap into the experience
<item>
It lets other people thinking about working on the package know that
-there already is a volunteer, and efforts may be shared.
+there already is a volunteer, and efforts may be shared. The "intent
+to package" message to <email/debian-devel@lists.debian.org/ will be
+picked up the the WNPP maintainer, and your intention will be
+published in subsequent versions of the WNPP document.
<item>
It lets the rest of the maintainers know more about the package than
the one line description and the changelog entry "Initial version"
-that generally gets posted to debian-devel-changes by default.
+that generally gets posted to <tt/debian-devel-changes/ by default.
<item>
It is helpful to the people who live off unstable (and form our first
<item>
If we appreciate alpha testers, than any name changes have to be
backwards compatible with the people who already installed the old
-package (conflict and replace old package name at a minimum)
+package (conflict and replace old package name at a minimum).
</list>
-
+
+
<sect>Uploading a package
<sect1>Generating the changes file
handling. This is usually generated by <prgn/dpkg-genchanges/.
<p>
This file is a control file with the following fields:
- <list compact>
+<list compact>
<item><tt/Format/
<item><tt/Date/
<item><tt/Source/
source should be uploaded, possibly by using the <tt/-sa/ flag.
+ <sect1>Checking the package prior to upload
+ <p>
+Before you upload your package, you should do basic testing on it.
+Make sure you try the following activities (you'll need to have an
+older version of the Debian package around).
+<list>
+ <item> install the package and make sure the software
+ works
+
+ <item> upgrade the package from an older version to your
+ new version
+
+ <item> downgrade the package to the previous version
+ (this tests the <tt/postrm/ and <tt/prerm/ scripts)
+
+ <item> remove the package
+
+ <item> run <prgn/lintian/ over the package. You can run
+ <prgn/lintian/ as follows: <tt>lintian -v
+ <var>package-NN</var>.changes</tt>. This will check the
+ source package as well as the binary package. If you
+ don't understand the output that <prgn/lintian/
+ generates, try adding the <tt/-i/ switch, which will
+ cause <prgn/lintian/ to output a very verbose
+ description of the problem.
+
+ </list>
+
+
<sect1>Transferring the files to master
<p>
-To upload a package, you need a personal account on the master
-server. Just log in via ftp and transfer the files to
-<tt>/home/Debian/ftp/private/project/Incoming</tt>. (You cannot
-upload to Incoming on master using anonymous FTP--you must use your
-user-name and password.)
+To upload a package, you need a personal account on
+<ftpsite>master.debian.org</ftpsite>. All maintainers should already
+have this account. You can use either <prgn/ssh/ or <prgn/ftp/ to
+transfer the files. In either case, the files need to be placed into
+<ftppath>/home/Debian/ftp/private/project/Incoming</ftppath>. (You
+cannot upload to Incoming on master using anonymous FTP--you must use
+your user-name and password.)
<p>
-You may also find the Debian package '<tt>dupload</tt>' useful in
-uploading new packages to master. See the '<tt>dupload</tt>'
-documentation for more information.
+You may also find the Debian package <prgn/dupload/ useful when
+uploading packages. This handy program is distributed with defaults
+for uploading via <prgn/ftp/ to <tt/master/, <tt/chiark/, and
+<tt/erlangen/. It can also be configured to use <prgn/ssh/. See
+<manref name="dupload" section="1"> and <manref name="dupload"
+section="5"> for more information.
<sect1>Uploads via Chiark
<p>
-If you have a slow network connection to the master system, there are
-two alternatives: You can upload files to Incoming via a cron-driven
-upload queue in Europe on ftp.chiark.greenend.org.uk. For details
-connect to chiark using anonymous FTP and read
-<tt>/pub/debian/private/project/README.how-to-upload</tt>.
+If you have a slow network connection to <tt/master/, there are two
+alternatives: You can upload files to Incoming via a cron-driven
+upload queue in Europe on <tt/chiark/. For details connect to
+<ftpsite>ftp.chiark.greenend.org.uk</ftpsite> using anonymous FTP and
+read
+<ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>.
<p>
-The program <tt/dupload/ support uploads to chiark, please refer to
-the documentation that comes with the program, for details.
+The program <tt/dupload/ supports uploads to chiark, please refer to
+the documentation that comes with the program for details.
<sect1>Uploads via Erlangen
<p>
-Another cron-driven upload queue is available in Germany: Just upload
-the files via anonymous FTP to
-<tt>ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue</>.
+Another cron-driven upload queue is available in Germany: just upload
+the files via anonymous FTP to <url
+id="ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue">.
<p>
The upload must be a complete Debian upload, as you would put it into
-master's incoming, i.e. a <tt/.changes/ files along with the other
-files mentioned in the <tt/.changes/. The queue daemon also checks
-that the <tt/.changes/ is correctly PGP-signed by a Debian developer,
-so that no bogus files can find their way to master via the
+master's <tt/Incoming/, i.e., a <tt/.changes/ files along with the
+other files mentioned in the <tt/.changes/. The queue daemon also
+checks that the <tt/.changes/ is correctly PGP-signed by a Debian
+developer, so that no bogus files can find their way to master via the
queue. Please also make sure that the <tt/Maintainer:/ field in the
-<tt/.changes/ contains *your* e-mail address. The address found there
-is used for all replies, just as on master.
+<tt/.changes/ contains <em/your/ e-mail address. The address found
+there is used for all replies, just as on master.
<p>
There's no need to move your files into a second directory after the
upload as on chiark. And, in any case, you should get some mail reply
should have been moved to master, but in case of errors you're
notified, too.
<p>
-The program <prgn/dupload/ support uploads to erlangen, please refer
-to the documentation that comes with the program, for details.
- <p>
+The program <prgn/dupload/ supports uploads to erlangen, please refer
+to the documentation that comes with the program for details.
+
<sect1>Uploading to the non-us server
<p>
<tt/experimental/, or <tt/frozen/ (when present), the announcement
should be posted to <email/debian-devel-changes@lists.debian.org/
instead.
-
+ <p>
+If you use dupload, it is clever enough to determine for itself where
+the announcement should go, and will automatically mail the
+announcement.
+
+ <sect>Notification that a new package has been installed
+ <p>
+The Debian archive maintainers are responsible for handling package
+uploads. For the most part, uploads are automatically handled on a
+daily basis by an archive maintenance tool called <prgn/dinstall/.
+Specifically, updates to existing packages to the `unstable'
+distribution are handled automatically. In other cases, notably new
+packages, placing the uploaded package into the distribution is
+handled manually. When uploads are handled manually, the change to the
+archive may take up to a week to occur (please be patient).
+ <p>
+In any case, you will receive notification indicating that the package
+has been uploaded via email. Please examine this notification
+carefully. Sometimes the "override" file which the archive
+maintainers use to indicate where packages go, is incorrect or
+out-of-sync with your control file. In these cases, you should either
+correct your control file or file a bug against <tt/ftp.debian.org/
+using the BTS.
<sect>Interim releases
<p>
a porter for another architecture may have to make some small changes
to the source package and does not wish to wait with uploading their
release until the main maintainer has incorporated the patch, or a
-serious security problem may have come to light requiring immediate
-attention.
+serious security problem or bug may have come to light requiring
+immediate attention.
<p>
When a security bug is detected a fixed package should be uploaded as
soon as possible. In this case, the Debian Security Managers should
changes to the package as possible, and they should always send a
unified context diff (<tt/diff -u/) detailing their changes to the bug
tracking system properly flagged with the correct package so that the
-usual maintainer is kept aware of the situation. If the non-maintainer
-upload fixes some bugs, the bug reports should not be closed. However,
-the person making the non-maintainer release should send a short
-message to the bug tracking system to all the fixed bugs explaining
-that they have been fixed. This way, the maintainer and other people
-will get notified about that.
+usual maintainer is kept aware of the situation.
+ <p>
+If the non-maintainer upload (as known as an "NMU") fixes some
+existing bugs, the bug reports should not be closed. Technically,
+only the official package maintainer or the original bug submitter are
+allowed to close bugs. However, the person making the non-maintainer
+release should send a short message to the bug tracking system to all
+the fixed bugs explaining that they have been fixed. Using
+<email/control@bugs.debian.org/, the party doing the NMU should also
+set the severity of the bugs fixed in the NMU to "fixed". This
+ensures that everyone knows that the bug was fixed in an NMU; however
+the bug is left open until the changes in the NMU are incorporated
+"officially" into the package by the offical package maintainer.
+
<p>
The normal maintainer should do at least one of
<list compact>
<sect>Maintainer changes
<p>
Periodically, a listing of packages in need of new maintainers will be
-sent to the <tt>debian-devel</> list. This list is also available at
-<ftpsite>ftp.debian.org</> in
-<ftppath>/debian/doc/package-developer/prospective-packages.html</> If
-you wish to take over maintenance of any of those packages, or if you
-can no longer maintain the packages you have, or you simply want to
-know if any one is working on a new package, send a message to
-<email/override-change@debian.org/.
+sent to <email/debian-devel@lists.debian.org</email> list. This list
+is also available at in the Work-Needing and Prospective Packages
+document (WNPP), <url
+id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html">
+and at <url
+id="http://www.debian.org/doc/prospective-packages.html">. If you wish
+to take over maintenance of any of the packages listed in the WNPP, or
+if you can no longer maintain a packages you have, or you simply want
+to know if any one is working on a new package, send a message to
+<email/wnpp@debian.org/.
<p>
If you take over an old package, you probably want to be listed as the
package's official maintainer in the bug system. This will happen
<chapt>Handling bug reports
+ <sect>Bugs in your packages
+ <p>
+If you want to be a good maintainer, you should periodically check the
+<url id="http://www.debian.org/Bugs/" name="Debian bug tracking system
+(BTS)"> for your packages. The BTS contains all the open bugs against
+your packages.
+ <p>
+If you fix a bug in your packages, it is your responsibility as the
+package maintainer to close the bug when it has been fixed. However,
+you should not close the bug until the package which fixes the bug has
+been accepted into the Debian archive. Therefore, once you get
+notification that your updated package has been installed into the
+archive, you can and should close the bug in the BTS.
+ <p>
+Maintainers interact with the BTS via email addresses at
+<tt/bugs.debian.org/. Documentation on available commands can be
+found in <tt>/usr/doc/debian/bug-*</tt> from the <prgn/debian-doc/
+package.
+
+ <sect>Lintian reports
+ <p>
+You should periodically get the new <prgn/lintian/ from `unstable' and
+check over all your packages. Alternatively you can check for you're
+maintainer email address at <url
+id="http://www.debian.org/lintian/">. That page, which is
+updated automatically, contains lintian reports against the latest
+version of the package (usually from 'unstable') using the latest
+<prgn/lintian/.
+
+
<sect>Reporting lots of bugs at once
<p>
If you report more then 10 bugs on the same topic at once, it is
-recommended that you send a message to debian-devel describing your
-intention before submitting the report. This will allow other
-developers to verify that the bug is a real problem. In addition, it
-will prevent the situation where several maintainers start filing the
-same bug report simultaneously.
+recommended that you send a message to
+<email/debian-devel@lists.debian.org/ describing your intention before
+submitting the report. This will allow other developers to verify that
+the bug is a real problem. In addition, it will prevent the situation
+where several maintainers start filing the same bug report
+simultaneously.
<p>
Note, that when sending lots of bugs on the same subject, you should
send the bug report to <email/maintonly@bugs.debian.org/ so that the
~ianmdlvl / developers-reference.git / commitdiff