<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.103 $">
+ <!entity cvs-rev "$Revision: 1.109 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
id="&url-gpl;" name="the GNU website">. You can also obtain it by
writing to the &fsf-addr;.
- <toc detail="sect2">
+ <toc detail="sect1">
<chapt id="scope">Scope of This Document
<p>
<p>
Be very careful with your private keys. Do not place them on any
public servers or multiuser machines, such as
-<tt>master.debian.org</tt>. Back your keys up; keep a copy offline.
+<tt>&master-host;</tt>. Back your keys up; keep a copy offline.
Read the documentation that comes with your software; read the <url
id="&url-pgp-faq;" name="PGP FAQ">.
<p>
<sect id="voting">Voting
<p>
-&FIXME;<url id="url-vote">
+Even if Debian is not always a real democracy, Debian has democratic
+tools and uses a democratic process to elect its leader or
+to approve a general resolution. Those processes are described in
+the <url id="&url-constitution;" name="Debian Constitution">.
+ <p>
+Democratic processes work well only if everybody take part in the
+vote, that's why you have to vote. To be able to vote you have to
+subscribe to &email-debian-devel-announce; since call for votes are sent
+there. If you want to follow the debate preceding a vote, you
+may want to subscribe to &email-debian-vote;.
+ <p>
+The list of all the proposals (past and current) is available on the
+web at <url id="url-vote">. You will find there additionnal information
+about how to make a vote proposal.
<sect id="inform-vacation">Going on vacation gracefully
<item>
Notify the Debian key ring maintainers that you are leaving by
emailing to &email-debian-keyring;.
- </enumlist>
+</enumlist>
&email-debian-private; unless it is really necessary. Moreover, do
<em>not</em> forward email from that list to anyone. Archives of this
list are not available on the web for obvious reasons, but you can see
-them using your shell account on <tt>master.debian.org</tt> and looking
+them using your shell account on <tt>&master-host;</tt> and looking
in the <file>~debian/archive/debian-private</file> directory.
<p>
&email-debian-email; is a special mailing list used as a grab-bag
Online archives of mailing lists are available at <url
id="&url-lists-archives;">.
+ <sect id="irc-channels">IRC channels
+ <p>
+Several IRC channels are dedicated to Debian's development. They are all
+hosted on the <url id="&url-openprojects;" name="OpenProjects"> network.
+The <tt>irc.debian.org</tt> DNS entry is just an alias to
+<tt>irc.openprojects.net</tt>.
+ <p>
+The main channel <em>#debian-devel</em> is very active since more
+than 150 persons are always logged in. It's a channel for people who work
+on Debian, it's not a support channel (there's <em>#debian</em> for that).
+It is however open to anyone who wants to lurk (and learn). Its topic is
+always full of interesting informations. Since it's an open channel, you
+should not speak there of issues that are discussed in
+&email-debian-private;. There's a key protected channel
+<em>#debian-private</em> for that purpose. The key is available
+in the archives of debian-private in <file>&master-host;:&file-debian-private-archive;</file>, just <prgn>zgrep</prgn> for <em>#debian-private</em> in
+all the files.
+ <p>
+There are other additionnal channels dedicated to specific subjects.
+<em>#debian-bugs</em> is used for coordinating bug squash parties.
+<em>#debian-boot</em> is used to coordinate the work on the boot
+floppies (i.e. the installer). <em>#debian-doc</em> is
+occasionnaly used to work on documentation like the one you are
+reading. Other channels are dedicated to an architecture or a set of
+packages : <em>#debian-bsd</em>, <em>#debian-kde</em>,
+<em>#debian-sf</em> (SourceForge package), <em>#debian-oo</em> (OpenOffice
+package) ...
+ <p>
+Some non-english channels exist, for example <em>#debian-devel-fr</em> for
+french speaking people interested in Debian's development.
<sect id="doc-rsrcs">Documentation
<p>
-&FIXME; <url id="&url-devel-docs;">
-
-
+This document contains many informations very useful to Debian developers,
+but it can not contain everything. Most of the other interesting documents
+are linked from <url id="&url-devel-docs;" name="The Developers' Corner">.
+Take the time to browse all the links, you will learn many more things.
<sect id="server-machines">Debian servers
<p>
<sect1 id="servers-master">The master server
<p>
-<tt>master.debian.org</tt> is the canonical location for the Bug
-Tracking System (BTS). If you plan on doing some statistical analysis
-or processing of Debian bugs, this would be the place to do it.
-Please describe your plans on &email-debian-devel; before implementing
+<tt>&master-host;</tt> is the canonical location for the Bug Tracking
+System (BTS). If you plan on doing some statistical analysis or
+processing of Debian bugs, this would be the place to do it. Please
+describe your plans on &email-debian-devel; before implementing
anything, however, to reduce unnecessary duplication of effort or
wasted processing time.
<p>
-All Debian developers have accounts on <tt>master.debian.org</tt>.
+All Debian developers have accounts on <tt>&master-host;</tt>.
Please take care to protect your password to this machine. Try to
avoid login or upload methods which send passwords over the Internet
in the clear.
<p>
-If you find a problem with <tt>master.debian.org</tt> such as disk
+If you find a problem with <tt>&master-host;</tt> such as disk
full, suspicious activity, or whatever, send an email to
&email-debian-admin;.
<sect id="archive">The Debian archive
<p>
The &debian-formal; distribution consists of a lot of packages
-(<tt>.deb</tt>'s, currently around &number-of-pkgs;) and a few
+(<file>.deb</file>'s, currently around &number-of-pkgs;) and a few
additional files (such documentation and installation disk images).
<p>
Here is an example directory tree of a complete Debian archive:
&sample-dist-dirtree;
<p>
As you can see, the top-level directory contains two directories,
-<tt>dists/</tt> and <tt>pool/</tt>. The latter is a “pool” in which the
+<file>dists/</file> and <file>pool/</file>. The latter is a “pool” in which the
packages actually are, and which is handled by the archive maintenance
database and the accompanying programs. The former contains the
distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>.
Each of those distribution directories is divided in equivalent
subdirectories purpose of which is equal, so we will only explain how it
-looks in stable. The <tt>Packages</tt> and <tt>Sources</tt> files in the
-distribution subdirectories can reference files in the <tt>pool/</tt>
+looks in stable. The <file>Packages</file> and <file>Sources</file> files in the
+distribution subdirectories can reference files in the <file>pool/</file>
directory.
<p>
-<tt>dists/stable</tt> contains three directories, namely <em>main</em>,
-<em>contrib</em>, and <em>non-free</em>.
+<file>dists/stable</file> contains three directories, namely <file>main</file>,
+<file>contrib</file>, and <file>non-free</file>.
<p>
In each of the areas, there is a directory for the source packages
-(<tt>source</tt>) and a directory for each supported architecture
-(<tt>binary-i386</tt>, <tt>binary-m68k</tt>, etc.).
+(<file>source</file>) and a directory for each supported architecture
+(<file>binary-i386</file>, <file>binary-m68k</file>, etc.).
<p>
-The <em>main</em> area contains additional directories which holds
+The <file>main</file> area contains additional directories which holds
the disk images and some essential pieces of documentation required
for installing the Debian distribution on a specific architecture
-(<tt>disks-i386</tt>, <tt>disks-m68k</tt>, etc.).
+(<file>disks-i386</file>, <file>disks-m68k</file>, etc.).
<sect1>Sections
There are two types of Debian packages, namely <em>source</em> and
<em>binary</em> packages.
<p>
-Source packages consist of either two or three files: a <tt>.dsc</tt>
-file, and either a <tt>.tar.gz</tt> file or both an
-<tt>.orig.tar.gz</tt> and a <tt>.diff.gz</tt> file.
+Source packages consist of either two or three files: a <file>.dsc</file>
+file, and either a <file>.tar.gz</file> file or both an
+<file>.orig.tar.gz</file> and a <file>.diff.gz</file> file.
<p>
If a package is developed specially for Debian and is not distributed
-outside of Debian, there is just one <tt>.tar.gz</tt> file which
+outside of Debian, there is just one <file>.tar.gz</file> file which
contains the sources of the program. If a package is distributed
-elsewhere too, the <tt>.orig.tar.gz</tt> file stores the so-called
+elsewhere too, the <file>.orig.tar.gz</file> file stores the so-called
<em>upstream source code</em>, that is the source code that's
distributed from the <em>upstream maintainer</em> (often the author of
-the software). In this case, the <tt>.diff.gz</tt> contains the
+the software). In this case, the <file>.diff.gz</file> contains the
changes made by the Debian maintainer.
<p>
-The <tt>.dsc</tt> lists all the files in the source package together
+The <file>.dsc</file> file lists all the files in the source package together
with checksums (<prgn>md5sums</prgn>) and some additional info about
the package (maintainer, version, etc.).
<p>
The directory system described in the previous chapter is itself
contained within <em>distribution directories</em>. Each
-distribution is actually contained in the <tt>pool</tt> directory in the
+distribution is actually contained in the <file>pool</file> directory in the
top-level of the Debian archive itself.
<p>
To summarize, the Debian archive has a root directory within an FTP
server. For instance, at the mirror site,
<ftpsite>ftp.us.debian.org</ftpsite>, the Debian archive itself is
contained in <ftppath>/debian</ftppath>, which is a common location
-(another is <tt>/pub/debian</tt>).
+(another is <file>/pub/debian</file>).
<p>
A distribution is comprised of Debian source and binary packages, and the
-respective <tt>Sources</tt> and <tt>Packages</tt> index files, containing
+respective <file>Sources</file> and <file>Packages</file> index files, containing
the header information from all those packages. The former are kept in the
-<tt>pool/</tt> directory, while the latter are kept in the <tt>dists/</tt>
-directory of the archive (because of backwards compatibility).
+<file>pool/</file> directory, while the latter are kept in the <file>dists/</file>
+directory of the archive (for backwards compatibility).
<sect2 id="sec-dists">Stable, testing, and unstable
<p>
There are always distributions called <em>stable</em> (residing in
-<tt>dists/stable</tt>), one called <em>testing</em> (residing in
-<tt>dists/testing</tt>), and one called <em>unstable</em> (residing in
-<tt>dists/unstable</tt>). This reflects the development process of the
+<file>dists/stable</file>), one called <em>testing</em> (residing in
+<file>dists/testing</file>), and one called <em>unstable</em> (residing in
+<file>dists/unstable</file>). This reflects the development process of the
Debian project.
<p>
Active development is done in the <em>unstable</em> distribution
updates are tested very carefully and have to be introduced into the
archive individually to reduce the risk of introducing new bugs. You
can find proposed additions to <em>stable</em> in the
-<tt>proposed-updates</tt> directory. Those packages in
-<tt>proposed-updates</tt> that pass muster are periodically moved as a
+<file>proposed-updates</file> directory. Those packages in
+<file>proposed-updates</file> that pass muster are periodically moved as a
batch into the stable distribution and the revision level of the
stable distribution is incremented (e.g., ‘3.0’ becomes
‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and
directories and scripts that are installed both on <tt>&ftp-master-host;</tt>
and <tt>&non-us-host;</tt>.
<p>
-Packages are uploaded by all the maintainers into an <tt>unchecked</tt>
+Packages are uploaded by all the maintainers into an <file>unchecked</file>
directory. This directory is scanned every 15 minutes by the katie script
that verifies the integrity of the package and the cryptographic
signature. If the package is considered ready to be installed, it
-is moved into an <tt>accepted</tt> directory. If it is the first upload of
-the package then it is moved in a <tt>new</tt> directory waiting an
+is moved into an <file>accepted</file> directory. If it is the first upload of
+the package then it is moved in a <file>new</file> directory waiting an
approval of the ftpmasters. If the package contains files to be installed
-"by-hand" is is moved in the <tt>byhand</tt> directory waiting a manual
+"by-hand" is is moved in the <file>byhand</file> directory waiting a manual
installation by the ftpmasters. Otherwise, if any error has been detected,
-the package is refused and is moved in the <tt>reject</tt> directory.
+the package is refused and is moved in the <file>reject</file> directory.
<p>
Once the package is accepted the system sends a confirmation
mail to the maintainer, closes all the bugs marked as fixed by the upload
in the Debian archive. This happens only once a day, the package
is then removed from incoming and installed in the pool along with all
the other packages. Once all the other updates (generating new
-<tt>Packages</tt> and <tt>Sources</tt> index files for example) have been
+<file>Packages</file> and <file>Sources</file> index files for example) have been
made, a special script is called to ask all the primary mirrors to update
themselves.
<p>
-All debian developers have write access to the <tt>unchecked</tt>
+All debian developers have write access to the <file>unchecked</file>
directory in order to upload their packages, they also have that access
-to the <tt>reject</tt> directory in order to remove their bad uploads
-or to move some files back in the <tt>unchecked</tt> directory. But
+to the <file>reject</file> directory in order to remove their bad uploads
+or to move some files back in the <file>unchecked</file> directory. But
all the other directories are only writable by the ftpmasters, that is
why you can not remove an upload once it has been accepted.
<sect1 id="delayed-incoming">Delayed incoming
<p>
-The <tt>unchecked</tt> directory has a special <tt>DELAYED</tt>
+The <file>unchecked</file> directory has a special <file>DELAYED</file>
subdirectory. It is itself subdivised in nine directories
-called <tt>1-day</tt> to <tt>9-day</tt>. Packages which are uploaded in
+called <file>1-day</file> to <file>9-day</file>. Packages which are uploaded in
one of those directories will be moved in the real unchecked
directory after the corresponding number of days.
This is done by a script that is run each day and which moves the
packages between the directories. Those which are in "1-day" are
-installed in <tt>unchecked</tt> while the others are moved in the
-adjacent directory (for example, a package in <tt>5-day</tt> will
-be moved in <tt>4-day</tt>). This feature is particularly useful
+installed in <file>unchecked</file> while the others are moved in the
+adjacent directory (for example, a package in <file>5-day</file> will
+be moved in <file>4-day</file>). This feature is particularly useful
for people who are doing non-maintainer uploads. Instead of
waiting before uploading a NMU, it is uploaded as soon as it is
-ready but in one of those <tt>DELAYED/x-day</tt> directories.
+ready but in one of those <file>DELAYED/<var>x</var>-day</file> directories.
That leaves the corresponding number of days to the maintainer
in order to react and upload himself another fix if he is not
completely satisfied with the NMU. Alternatively he can remove
the NMU by himself.
<p>
The use of that delayed feature can be simplified with a bit
-of integration with your upload tool, the following addition to
-the <prgn>dupload</prgn> configuration file should be
-considered.
- <p>
+of integration with your upload tool. For instance, if you use
+<prgn>dupload</prgn> (see <ref id="dupload">), you can add this
+snippet to your configuration file:
<example>
$delay = ($ENV{DELAY} || 7);
$cfg{'delayed'} = {
- fqdn => "ftp-master.debian.org",
+ fqdn => "&ftp-master-host;",
login => "yourdebianlogin",
incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
visibleuser => "yourdebianlogin",
method => "scpb"
};
</example>
- <p>
-<prgn>dupload</prgn> can now be used to easily upload a package
-in one of the delayed directories :
+Once you've made that change, <prgn>dupload</prgn> can be used to
+easily upload a package in one of the delayed directories:
<example>DELAY=5 dupload --to delayed <changes-file></example>
<sect id="testing-scripts">
<package>devscripts</package> package. It can be easily put in a crontab
to keep someone informed of the progression of his packages in testing.
<p>
-The <tt>update_excuses</tt> file does not always give the precise reason
+The <file>update_excuses</file> file does not always give the precise reason
why the package is refused, one may have to find it by himself by looking
what would break with the inclusion of the package. The <url
id="&url-testing-faq;" name="testing FAQ"> gives some more information
<sect1 id="pkg-info-web">On the web
<p>
Each package has several dedicated web pages that contains many
-informations. First <tt>http://&packages-host;/<package></tt>
-will let you discover a presentation of each version of the package
-available in the various distributions. It includes its description,
-the dependencies and some links to download the package.
+informations. <tt>http://&packages-host;/<var>package-name</var></tt>
+will display each version of the package
+available in the various distributions. The per-version detailed
+information includes the package description,
+the dependencies and links to download the package.
<p>
The bug tracking system sorts the bugs by package, you can
watch the bugs of each package at
-<tt>http://&bugs-host;/<package></tt>.
+<tt>http://&bugs-host;/<var>package-name</var></tt>.
- <sect1 id="madison">The madison utility
+ <sect1 id="madison">The <prgn>madison</prgn> utility
<p>
<prgn>madison</prgn> is a command-line utility that is available
on both <tt>&ftp-master-host;</tt> and <tt>&non-us-host;</tt>. It
<p>
Assuming no one else is already working on your prospective package,
you must then submit a bug report (<ref id="submit-bug">) against the
-pseudo package <tt>wnpp</tt>
+pseudo-package <package>wnpp</package>
describing your plan to create a new package, including, but not
limiting yourself to, a description of the package, the license of the
prospective package and the current URL where it can be downloaded
For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
<item>
Downgrade the package to the previous version (if one exists) — this
-tests the <tt>postrm</tt> and <tt>prerm</tt> scripts.
+tests the <file>postrm</file> and <file>prerm</file> scripts.
<item>
Remove the package, then reinstall it.
</list>
<sect1>Generating the changes file
<p>
When a package is uploaded to the Debian FTP archive, it must be
-accompanied by a <tt>.changes</tt> file, which gives directions to the
+accompanied by a <file>.changes</file> file, which gives directions to the
archive maintainers for its handling. This is usually generated by
<prgn>dpkg-genchanges</prgn> during the normal package build process.
<p>
<p>
The first time a version is uploaded which corresponds to a particular
upstream version, the original source tar file should be uploaded and
-included in the <tt>.changes</tt> file. Subsequently, this very same
-tar file should be used to build the new diffs and <tt>.dsc</tt>
+included in the <file>.changes</file> file. Subsequently, this very same
+tar file should be used to build the new diffs and <file>.dsc</file>
files, and will not need to be re-uploaded.
<p>
By default, <prgn>dpkg-genchanges</prgn> and
<p>
If no original source is included in the upload, the original
source tar-file used by <prgn>dpkg-source</prgn> when constructing the
-<tt>.dsc</tt> file and diff to be uploaded <em>must</em> be
+<file>.dsc</file> file and diff to be uploaded <em>must</em> be
byte-for-byte identical with the one already in the archive.
<sect3 id="upload-stable">Uploading to <em>stable</em>
<p>
Uploading to <em>stable</em> means that the package will be placed into the
-<tt>proposed-updates</tt> directory of the Debian archive for further
+<file>proposed-updates</file> directory of the Debian archive for further
testing before it is actually included in <em>stable</em>.
<p>
Extra care should be taken when uploading to <em>stable</em>. Basically, a
<sect2 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
<p>
To upload a package, you need a personal account on
-<ftpsite>ftp-master.debian.org</ftpsite>, which you should have as an
+<ftpsite>&ftp-master-host;</ftpsite>, which you should have as an
official maintainer. If you use <prgn>scp</prgn> or <prgn>rsync</prgn>
-to transfer the files, place them into <tt>&us-upload-dir;</tt>;
+to transfer the files, place them into &us-upload-dir;;
if you use anonymous FTP to upload, place them into
-<ftppath>/pub/UploadQueue/</ftppath>. Please note that you should transfer
+&upload-queue;. Please note that you should transfer
the changes file last. Otherwise, your upload may be rejected because the
archive maintenance software will parse the changes file and see that not
all files have been uploaded. If you don't want to bother with transferring
the changes file last, you can simply copy your files to a temporary
directory on <tt>ftp-master</tt> and then move them to
-<tt>&us-upload-dir;</tt>.
+&us-upload-dir;.
<p>
<em>Note:</em> Do not upload to <tt>ftp-master</tt> cryptographic
packages which belong to <em>contrib</em> or <em>non-free</em>. Uploads of
id="upload-non-us">). Furthermore packages containing code that is
patent-restricted by the United States government can not be uploaded to
<tt>ftp-master</tt>; depending on the case they may still be uploaded to
-<tt>non-US/non-free</tt> (it's in non-free because of distribution issues
+<file>non-US/non-free</file> (it's in non-free because of distribution issues
and not because of the license of the software). If you can't upload it to
<tt>ftp-master</tt>, then neither can you upload it to the overseas upload
queues on <tt>chiark</tt> or <tt>erlangen</tt>. If you are not sure
whether U.S. patent controls or cryptographic controls apply to your
package, post a message to &email-debian-devel; and ask.
<p>
-You may also find the Debian packages <package>dupload</package> or
-<package>dput</package> useful
-when uploading packages. These handy programs are distributed with
-defaults for uploading via <prgn>ftp</prgn> to <tt>ftp-master</tt>,
-<tt>chiark</tt>, and <tt>erlangen</tt>. They can also be configured to
-use <prgn>ssh</prgn> or <prgn>rsync</prgn>. See <manref name="dupload"
-section="1">, <manref name="dupload" section="5"> and <manref name="dput"
-section="1"> for more information.
+You may also find the Debian packages <ref id="dupload"> or
+<ref id="dput"> useful
+when uploading packages. These handy programs help automate the
+process of uploading packages into Debian.
<p>
-After uploading your package, you can check how the archive maintenance
-software will process it by running <prgn>dinstall</prgn> on your changes
-file: <example>dinstall -n foo.changes</example>
+After uploading your package, you can check how the archive
+maintenance software will process it by running <prgn>dinstall</prgn>
+on your changes file: <example>dinstall -n foo.changes</example>.
+Note that <prgn>dput</prgn> can do this for you automatically.
<sect2 id="upload-non-us">Uploading to <tt>non-US</tt> (pandora)
<p>
As discussed above, export controlled software should not be uploaded
to <tt>ftp-master</tt>. Instead, upload the package to
<ftpsite>non-us.debian.org</ftpsite>, placing the files in
-<tt>&non-us-upload-dir;</tt> (both <ref id="dupload"> and <ref
-id="dput"> can be used also, with the right invocation). By default,
+&non-us-upload-dir; (again, both <ref id="dupload"> and <ref
+id="dput"> can do this for you if invocated properly). By default,
you can use the same account/password that works on
<tt>ftp-master</tt>. If you use anonymous FTP to upload, place the
-files into <ftppath>/pub/UploadQueue/</ftppath>.
+files into &upload-queue;.
<p>
You can check your upload the same way it's done on <tt>ftp-master</tt>,
with:
<sect2>Uploads via <tt>chiark</tt>
<p>
If you have a slow network connection to <tt>ftp-master</tt>, there are
-alternatives. One is to upload files to <tt>Incoming</tt> via a
+alternatives. One is to upload files to <file>Incoming</file> via a
upload queue in Europe on <tt>chiark</tt>. For details connect to
<url id="&url-chiark-readme;">.
<p>
via anonymous FTP to <url id="&url-upload-erlangen;">.
<p>
The upload must be a complete Debian upload, as you would put it into
-<tt>ftp-master</tt>'s <tt>Incoming</tt>, i.e., a <tt>.changes</tt> files
-along with the other files mentioned in the <tt>.changes</tt>. The
-queue daemon also checks that the <tt>.changes</tt> is correctly
+<tt>ftp-master</tt>'s <file>Incoming</file>, i.e., a <file>.changes</file> files
+along with the other files mentioned in the <file>.changes</file>. The
+queue daemon also checks that the <file>.changes</file> is correctly
signed with GnuPG or OpenPGP by a Debian developer, so that no bogus files can find
their way to <tt>ftp-master</tt> via this queue. Please also make sure that
-the <tt>Maintainer</tt> field in the <tt>.changes</tt> contains
+the <tt>Maintainer</tt> field in the <file>.changes</file> contains
<em>your</em> e-mail address. The address found there is used for all
replies, just as on <tt>ftp-master</tt>.
<p>
maintenance software when it runs (usually once a day). You just need to use
a recent <package>dpkg-dev</package> (>= 1.4.1.2). The mail generated by
the archive maintenance software will contain the OpenPGP/GnuPG signed
-<tt>.changes</tt> files that you uploaded with your package.
+<file>.changes</file> files that you uploaded with your package.
Previously, <prgn>dupload</prgn> used to send those announcements, so
please make sure that you configured your <prgn>dupload</prgn> not to
send those announcements (check its documentation and look for
Double check that your patch doesn't have any unexpected side effects.
Make sure your patch is as small and as non-disruptive as it can be.
<item>
-Upload your package to incoming in <tt>DELAYED/7-day</tt> (cf.
+Upload your package to incoming in <file>DELAYED/7-day</file> (cf.
<ref id="delayed-incoming">), send the final patch to the maintainer via
the BTS, and explain him that he has 7 days to react if he wants to cancel
the NMU.
<package>build-essential</package> package and any package
dependencies mentioned in <tt>Build-Depends</tt> and/or
<tt>Build-Depends-Indep</tt>. Finally, try building your package
-within that chrooted environment.
+within that chrooted environment. These steps can be automated
+by the use of the <prgn>pbuilder</prgn> program which is provided by
+the package of the same name.
<p>
See the <url id="&url-debian-policy;" name="Debian Policy
Manual"> for instructions on setting build dependencies.
Make sure your source package is correct. Do <tt>dpkg-source -x
<var>package</var>.dsc</tt> to make sure your source package unpacks
properly. Then, in there, try building your package from scratch with
-<tt>dpkg-buildpackage</tt>.
+<prgn>dpkg-buildpackage</prgn>.
<item>
Make sure you don't ship your source package with the
<file>debian/files</file> or <file>debian/substvars</file> files.
was removed because <tt>libfoo13</tt> supersedes it) or closed if the
software is simply no more part of Debian.
- <sect2>Removing packages from <tt>Incoming</tt>
+ <sect2>Removing packages from <file>Incoming</file>
<p>
-In the past, it was possible to remove packages from <tt>incoming</tt>.
-With the introduction of the New Incoming system this is no longer
+In the past, it was possible to remove packages from <file>incoming</file>.
+However, with the introduction of the new incoming system, this is no longer
possible. Instead, you have to upload a new revision of your package with
a higher version as the package you want to replace. Both versions will be
installed in the archive but only the higher version will actually be
won't indicate the bug number).
<p>
If the package is especially crucial to Debian, you should instead submit
-a bug against <tt>wnpp</tt> and title it <tt>RFA: <var>package</var> --
+a bug against <package>wnpp</package> and title it <tt>RFA: <var>package</var> --
<var>short description</var></tt> and set its severity to
<em>important</em>. <tt>RFA</tt> stands for <em>Request For Adoption</em>.
Definitely copy the message to debian-devel in this case, as described
<url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
packages. The BTS contains all the open bugs against your packages.
You can check them by browsing this page:
-<tt>http://&bugs-host;/yourlogin@debian.org</tt>.
+<tt>http://&bugs-host;/<var>yourlogin</var>@debian.org</tt>.
<p>
Maintainers interact with the BTS via email addresses at
-<tt>bugs.debian.org</tt>. Documentation on available commands can be
+<tt>&bugs-host;</tt>. Documentation on available commands can be
found at <url id="&url-bts;">, or, if you have installed the
<package>doc-debian</package> package, you can look at the local files
&file-bts-docs;.
<p>
Filing bugs for problems that you find in other packages is one of
the "civic obligations" of maintainership, see <ref id="submit-bug">
-for details.
+for details. However handling the bugs on your own packages is
+even more important.
<p>
-&FIXME;Talk about tags, forwarding bugs, or else break it into
-different sections...
+Here's a list of steps that you may follow to handle a bug report:
+<enumlist>
+ <item>
+Decide whether the report corresponds to a real bug or not. Sometimes
+users are just calling a program in the wrong way because they haven't
+read the documentation. If you diagnose this, just close the bug with
+enough information to let the user correct his problem (give pointers
+to the good documentation and so on). If the same report comes up
+again and again you may ask yourself if the documentation is good
+enough or if the program shouldn't detect its misuse in order to
+give an informatory error message. This is an issue that may need
+to be brought to the upstream author.
+ <p>
+If the bug submitter disagree with your decision to close the bug,
+he may reopen it until you find an agreement on how to handle it.
+If you don't find any, you may want to tag the bug <tt>wontfix</tt>
+to let people know that the bug exists but that it won't be corrected.
+If this situation is inacceptable, you (or the submitter) may want to
+require a decision of the technical committee by reassigning the bug
+to <package>tech-ctte</package> (you may use the clone command of
+the BTS if you wish to keep it reported against your package).
+<!-- FIXME: Follow the procedure described at
+ tech-ctte-url (there's no such url yet). -->
+ <item>
+If the bug is real but it's caused by another package, just reassign
+the bug the right package. If you don't know which package it should
+be reassigned to, you may either ask for help on &email-debian-devel; or
+reassign it to <package>debian-policy</package> to let them decide which
+package is in fault.
+ <p>
+Sometimes you also have to adjust the severity of the bug so that it
+matches our definition of the severity. That's because people tend to
+inflate the severity of bugs to make sure their bugs are fixed quickly.
+Some bugs may even be dropped to wishlist severity when the requested
+change is just cosmetic.
+ <item>
+The bug submitter may have forgotten to provide some information, in that
+case you have to ask him the information required. You may use the
+<tt>moreinfo</tt> tag to mark the bug as such. Moreover if you can't
+reproduce the bug, you tag it <tt>unreproducible</tt>. Anyone who
+can reproduce the bug is then invited to provide more information
+on how to reproduce it. After a few months, if this information has not
+been sent by someone, the bug may be closed.
+ <item>
+If the bug is related to the packaging, you just fix it. If you are not
+able to fix it yourself, then tag the bug as <tt>help</tt>. You can
+also ask for help on &email-debian-devel; or &email-debian-qa;. If it's an
+upstream problem, you have to forward it to the upstream author.
+Forwarding a bug is not enough, you have to check at each release if
+the bug has been fixed or not. If it has, you just close it, otherwise
+you have to remind the author about it. If you have the required skills
+you can prepare a patch that fixes the bug and that you send at the
+same time to the author. Make sure to send the patch in the BTS and to
+tag the bug as <tt>patch</tt>.
+ <item>
+If you have fixed a bug in your local copy, or if a fix has been
+committed to the CVS repository, you may tag the bug as
+<tt>pending</tt> to let people know that the bug is corrected and that
+it will be closed with the next upload (add the <tt>closes:</tt> in
+the <file>changelog</file>). This is particularly useful if you
+are several developers working on the same package.
+ <item>
+Once a corrected package is availabe in the <em>unstable</em>
+distribution, you can close the bug. This can be done automatically,
+read <ref id="upload-bugfix">.
+</enumlist>
<sect1 id="upload-bugfix">When bugs are closed by new uploads
<file>changelog</file>.
<p>
If you want to close bugs the old fashioned, manual way, it is usually
-sufficient to mail the <tt>.changes</tt> file to
+sufficient to mail the <file>.changes</file> file to
<email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your
bug number.
several mailing lists. By following them, you will make Debian's quality
even better.
+ <sect id="packaging-tools">
+ <heading>Packaging tools and common cases</heading>
+
+ <sect1 id="helper-scripts">Helper scripts
+ <p>
+To help you in your packaging effort, you can use helper scripts.
+The best scripts available are provided by <package>debhelper</package>.
+With <prgn>dh_make</prgn> (package <package>dh-make</package>), you can
+generate in a few seconds a package that is mostly ready. However that
+apparent simplicity is hiding many things done by the helper scripts.
+You have to know what is done by them, that's why you are strongly
+encouraged to read the corresponding manual pages, starting with
+<tt>debhelper(1)</tt>. That's required because you'll have to
+understand what is going on to be able to use them wisely and to
+fix bugs in a pretty way.
+ <p>
+debhelper is very useful because it lets you follow the latest Debian policy
+without doing many modifications since the changes that can be automated are
+almost always automatically done by a debhelper script. Furthermore it
+offers enough flexibility to be able to use it in conjunction with
+some hand crafted shell invocations within the <file>rules</file> file.
+ <p>
+You can however decide to not use any helper script, and still write
+some very good <file>rules</file> file. Many examples are available
+at <url id="&url-rules-files;">.
+
+<!--
+ <sect1 id="pkg-mgmt-cvs">Managing a package with CVS
+ <p>
+ &FIXME; presentation of cvs-buildpackage, updating sources
+ via CVS (debian/rules refresh).
+-->
+
+ <sect1 id="multiple-patches">Package with multiple patches
+ <p>
+Big packages tend to have many upstream bugs that you want to fix within
+the Debian package. If you just correct the bug in the source, all the
+fixes are directly integrated in the <file>.diff.gz</file> file and you
+can't easily differentiate the various patches that you applied. It gets
+very messy when you have to update the package to a new upstream version
+which integrates some of the fixes (but not all).
+ <p>
+The good solution is to keep separate patches within the
+<file>debian/patches</file> directory and to apply them on the fly at
+build time. The package <package>dbs</package> provides an
+implementation of such a system, you just have to build-depend on dbs to
+be able to use its functionnalities. The package
+<package>hello-dbs</package> is a simple example that demonstrates how to
+use <package>dbs</package>.
+ <p>
+Additionnaly, dbs provides facilities to create the patches and to keep
+track of what they are for.
+
+ <sect1 id="multiple-binary">Multiple binary packages
+ <p>
+A single source package will often build several binary packages, either
+to provide several flavors of the same software (examples are the
+vim-* packages) or to make several small packages instead of a big one
+(it's interesting if the user doesn't need all the packages and can thus
+save some diskspace).
+ <p>
+The second case can be easily managed by <prgn>dh_install</prgn> (from
+<package>debhelper</package>) to move files from the build directory to
+the package's temporary trees.
+ <p>
+The first case is a bit more difficult since it involves multiple recompiles
+of the same software but with different configure options. The
+<package>vim</package> is an example of how to manage this with an
+hand crafted rules file.
+<!-- &FIXME; Find a good debhelper example with multile configure/make
+ cycles -->
+
+ <sect1 id="handling-debconf-translations">Handling debconf translations
+ <p>
+ &FIXME; Denis Barbier is going to write it.
+
+
+ <sect id="specific-practices">
+ <heading>Specific packaging practices</heading>
+
+<!--
+ <sect1 id="bpp-kernel">Kernel modules/patches
+ <p>
+ &FIXME; Heavy use of kernel-package. provide files in
+ /etc/modutils/ for module configuration.
+-->
+
+ <sect1 id="bpp-libraries">Libraries
+ <p>
+Libraries are always difficult to package for various reasons. The policy
+imposes many constraints to ease their maintenance and to make sure
+upgrades are as simple as possible when a new upstream version comes out.
+A breakage in a library can result in dozens of dependent packages to
+break...
+ <p>
+Good practices for library packaging have been grouped in
+<url id="&url-libpkg-guide;" name="the library packaging guide">.
+
+ <sect1 id="bpp-other-specific-practices">Other specific packages
+ <p>
+Several subsets of packages have special subpolicies and corresponding
+packaging rules and practices :
+<list>
+ <item>
+Perl related packages have a <url name="perl policy" id="&url-perl-policy;">,
+some examples of packages following that policy are
+<package>libdbd-pg-perl</package> (binary perl module) or
+<package>libmldbm-perl</package> (arch independent perl module).
+ <item>
+Python related packages have their python policy :
+&file-python-policy; (in the python package).
+ <item>
+Emacs related packages have the <url id="&url-emacs-policy;"
+name="emacs policy">.
+ <item>
+Java related packages have their <url id="&url-java-policy;"
+name="java policy">.
+ <item>
+Ocaml related packages have their ocaml policy : &file-ocaml-policy; (in
+the ocaml package). A good example is the <package>camlzip</package>
+source package.
+</list>
+
+ <sect id="config-mgmt">
+ <heading>Configuration management</heading>
+
+ <sect1 id="config-wise-debconf">The wise use of debconf
+ <p>
+Debconf is a configuration management system, it is used by all the
+various packaging scripts (postinst mainly) to request feedback from the
+user in the intent to configure the package. Direct user interactions
+must now be avoided in favor of debconf interaction. This will enable
+non-interactive installations in the future.
+ <p>
+Debconf is a great tool but it is often badly used ... many common mistakes
+are listed in the <manref name="debconf-devel" section="8"> manpage.
+It is something that you must have read if you decide to use debconf.
+
+<!--
+ <sect1 id="custom-config-files">Custom configuration files
+ <p>
+ &FIXME; speak of "ucf", explain solution with a template,
+ explain conf.d directories
+
+ <sect1 id="config-with-db">Use of an external database
+ <p>
+ &FIXME; The software may require a database that you need to setup.
+ But the database may be local or distant. Thus you can't depend
+ on a database server but just on the corresponding library.
+
+ sympa may be an example package
+-->
+
<sect id="misc-advice">
<heading>Miscellaenous advice</heading>
website if there's any. If the package is not yet considered stable
by the author, you may also want to warn the user that the
package is not ready for production use.
+ <p>
+Last but not least, since the first user impression is based on
+that description, you should be careful to avoid english
+mistakes. Ensure that you spell check it.
+<prgn>ispell</prgn> has a special option (<tt>-g</tt>) for that :
+<example>ispell -d american -g debian/control</example>
with the bug reports that you submitted. Take this opportunity to
close those that you can't reproduce anymore. To find
out all the bugs you submitted, you just have to visit
-<tt>http://&bugs-host;/your-email@your-isp.com</tt>.
+<tt>http://&bugs-host;/from:<your-email-addr></tt>.
<sect1 id="submit-many-bugs">Reporting lots of bugs at once
<p>
simply remind someone that a new upstream version is available
and that you need it.
<p>
-Whatever the reason, it is a pain to lookup the email address of the
-maintainer of the package that you are interested in. Fortunately, you
-can use a simple email alias : <tt><package>@&packages-host;</tt>.
-<tt><package></tt> can be the name of a source or a binary package.
+Looking up the email address of the maintainer for the package can be
+distracting. Fortunately, there is a simple email alias,
+<tt><package>@&packages-host;</tt>, which provides a way to
+email the maintainer, whatever their individual email address (or
+addresses) may be. Replace <tt><package></tt> with the name of
+a source or a binary package.
<p>
You may also be interested by contacting the persons who are
subscribed to a given source package via <ref id="pkg-tracking-system">.
-You can do so by using the <tt><package>@&pts-host;</tt>
+You can do so by using the <tt><package-name>@&pts-host;</tt>
email address.
the package meets minimum Debian standards. That implies that you
must build and test the package on your own system before uploading.
<p>
-You can not simply upload a binary <tt>.deb</tt> from the sponsoree. In
+You can not simply upload a binary <file>.deb</file> from the sponsoree. In
theory, you should only ask only for the diff file, and the location of the
original source tarball, and then you should download the source and apply
the diff yourself. In practice, you may want to use the source package
built by your sponsoree. In that case you have to check that he hasn't
-altered the upstream files in the <tt>.orig.tar.gz</tt> file that he's
+altered the upstream files in the <file>.orig.tar.gz</file> file that he's
providing.
<p>
Do not be afraid to write the sponsoree back and point out changes
<p>
Once the package meets Debian standards, build the package with
<example>dpkg-buildpackage -us -uc</example> and sign it
-with <example>debsign -m your@email.com <var>changes file</var></example>
+with <example>debsign -m <your-email-addr> <changes-file></example>
before uploading it to the incoming directory.
<p>
-The Maintainer field of the <tt>control</tt> file and the
-<tt>changelog</tt> should list the person who did the packaging, i.e. the
+The Maintainer field of the <file>control</file> file and the
+<file>changelog</file> should list the person who did the packaging, i.e. the
sponsoree. The sponsoree will therefore get all the BTS mail about the
package.
<p>
Most of the descriptions of these packages come from the actual
package descriptions themselves. Further information can be found in
the package documentation itself. You can also see more info with the
-command <tt>apt-cache show <var>package_name</var></tt>.
+command <tt>apt-cache show <package-name></tt>.
<sect id="dpkg-dev">
thing as <package>dupload</package>, but in a different way. It has
some features over <package>dupload</package>, such as the ability to
check the GnuPG signature and checksums before uploading, and the
-possibility of running <tt>dinstall</tt> in dry-run mode after the
+possibility of running <prgn>dinstall</prgn> in dry-run mode after the
upload.
into a bare base system.
+ <sect id="pbuilder">
+ <heading><package>pbuilder</package>
+ <p>
+<package>pbuilder</package> constructs a chrooted system, and builds
+a package inside the chroot. It is very useful to check that
+a package's build-dependencies are correct, and to be sure that
+unnecessary and wrong build dependencies will not exist in the
+resulting package.
+
+
<sect id="devscripts">
<heading><package>devscripts</package>
<p>
<package>devscripts</package> is a package containing a few wrappers
-and tools which you may find helpful for maintaining your Debian
+and tools which are very helpful for maintaining your Debian
packages. Example scripts include <prgn>debchange</prgn> and
<prgn>dch</prgn>, which manipulate your <file>debian/changelog</file>
file from the command-line, and <prgn>debuild</prgn>, which is a
-wrapper around <prgn>dpkg-buildpackage</prgn>.
-
+wrapper around <prgn>dpkg-buildpackage</prgn>. The <prgn>bts</prgn>
+utility is also very helpful to update the state of bug reports on the
+command line, as is <prgn>uscan</prgn> to watch for new upstream
+versions of your packages. Check the <tt>devscripts(1)</tt> manual
+page for a complete list of available scripts.
<sect id="dpkg-dev-el">
<package>debget</package> is a package containing a convenient script
which can be helpful in downloading files from the Debian archive.
You can use it to download source packages, for instance (although
-<tt>apt-get source <var>package</var></tt> does pretty much the same
+<tt>apt-get source <package-name></tt> does pretty much the same
thing).
alien
dpkg-repack
grep-dctrl
- pbuilder -->
+-->
</book>
~ianmdlvl / developers-reference.git / blobdiff