<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.107 $">
+ <!entity cvs-rev "$Revision: 1.114 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<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 additional 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>
<p>
&email-debian-private; is a special mailing list for private
discussions amongst Debian developers. It is meant to be used for
-posts which for whatever reason should not be published publically.
+posts which for whatever reason should not be published publicly.
As such, it is a low volume list, and users are urged not to use
&email-debian-private; unless it is really necessary. Moreover, do
<em>not</em> forward email from that list to anyone. Archives of this
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 additional 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
+occasionally 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-cvs">The CVS server
<p>
<tt>cvs.debian.org</tt> is also known as <tt>klecker.debian.org</tt>,
-discussed above. If you need to use a publically accessible CVS
+discussed above. If you need to use a publicly accessible CVS
server, for instance, to help coordinate work on a package between
many different developers, you can request a CVS area on the server.
<p>
ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and
<em>sparc</em> architectures. Debian 2.2 added support for the
<em>powerpc</em> and <em>arm</em> architectures. Debian 3.0 adds
-support of five new architectures : <em>ia64</em>, <em>hppa</em>,
+support of five new architectures: <em>ia64</em>, <em>hppa</em>,
<em>s390</em>, <em>mips</em> and <em>mipsel</em>.
<p>
Information for developers or uses about the specific ports are
<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
-and the autobuilders may start recompiling it. The package is now publically
+and the auto-builders may start recompiling it. The package is now publicly
accessible at <url id="&url-incoming;"> (there is no
such URL for packages in the non-US archive) until it is really installed
in the Debian archive. This happens only once a day, the package
<sect1 id="delayed-incoming">Delayed incoming
<p>
The <file>unchecked</file> directory has a special <file>DELAYED</file>
-subdirectory. It is itself subdivised in nine directories
+subdirectory. It is itself subdivided in nine directories
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.
fqdn => "&ftp-master-host;",
login => "yourdebianlogin",
incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
- visibleuser => "yourdebianlogin",
- visiblename => "debian.org",
- fullname => "Your Full Name",
dinstall_runs => 1,
method => "scpb"
};
the <em>testing</em> distribution, but they do so in an intelligent manner
trying to avoid any inconsistency and trying to use only
non-buggy packages.
- <p>The inclusion of a package from <em>unstable</em> is conditionned:
+ <p>The inclusion of a package from <em>unstable</em> is conditional on the following:
<list>
<item>
The package must have been available in <em>unstable</em> for several days;
-the precise number depends on the urgency field's value of the upload. It
+the precise number depends on the upload's urgency field. It
is 10 days for low urgency, 5 days for medium urgency and 2 days for high
urgency. Those delays may be doubled during a freeze;
<item>
the keyword listed below. This will let you select the mails that
you want to receive.
<p>
-By default you will get :
+By default you will get:
<taglist>
<tag><tt>bts</tt>
<item>
progression in testing, ...).
</taglist>
<p>
-You can also decide to receive some more information :
+You can also decide to receive some more information:
<taglist>
<tag><tt>upload-binary</tt>
<item>
Tells you the keywords that you are accepting. Each mail sent through
the Package Tracking System is associated to a keyword and you receive
only the mails associated to keywords that you are accepting. Here is
- the list of available keywords :
+ the list of available keywords:
<list>
- <item><tt>bts</tt> : mails coming from the Debian Bug Tracking System
- <item><tt>bts-control</tt> : reply to mails sent to
+ <item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
+ <item><tt>bts-control</tt>: reply to mails sent to
<email>control@bugs.debian.org</email>
- <item><tt>summary</tt> : automatic summary mails about the state of a package
- <item><tt>cvs</tt> : notification of cvs commits
- <item><tt>upload-source</tt> : announce of a new source upload that
+ <item><tt>summary</tt>: automatic summary mails about the state of a package
+ <item><tt>cvs</tt>: notification of CVS commits
+ <item><tt>upload-source</tt>: announce of a new source upload that
has been accepted
- <item><tt>upload-binary</tt> : announce of a new binary-only upload (porting)
- <item><tt>katie-other</tt> : other mails from ftpmasters
+ <item><tt>upload-binary</tt>: announce of a new binary-only upload (porting)
+ <item><tt>katie-other</tt>: other mails from ftpmasters
(override disparity, etc.)
- <item><tt>default</tt> : all the other mails (those which aren't "automatic")
+ <item><tt>default</tt>: all the other mails (those which aren't "automatic")
</list>
<tag><tt>keyword <srcpackage> [<email>]</tt>
<tt>X-Unsubscribe</tt>.
<p>
Here is an example of added headers for a source upload notification
-on the <package>dpkg</package> package :
+on the <package>dpkg</package> package:
<example>
X-Loop: dpkg@&pts-host;
X-PTS-Package: dpkg
<sect1 id="pts-cvs-commit">Forwarding CVS commits in the PTS
<p>
-If you use a publically accessible CVS repository for maintaining
+If you use a publicly accessible CVS repository for maintaining
your Debian package you may want to forward the commit notification
to the PTS so that the subscribers (possible co-maintainers) can
closely follow the package's evolution.
<p>
-It's very easy to setup. Once your cvs repository generates commit
+It's very easy to setup. Once your CVS repository generates commit
notifications, you just have to make sure it sends a copy of those mails
to <tt><var>srcpackage</var>_cvs@&pts-host;</tt>. Only people who
accepts the <em>cvs</em> keyword will receive the notifications.
to <tt>ftp-master</tt>. Instead, upload the package to
<ftpsite>non-us.debian.org</ftpsite>, placing the files in
&non-us-upload-dir; (again, both <ref id="dupload"> and <ref
-id="dput"> can do this for you if invocated properly). By default,
+id="dput"> can do this for you if invoked 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 &upload-queue;.
<p>
Bug fixes to unstable by non-maintainers are also acceptable, but only
as a last resort or with permission. The following protocol should
-be respected to do an NMU :
+be respected to do an NMU:
<p>
<list>
<item>
<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.
which simply check out and attempt to auto-build packages which need
to be ported. There is also an email interface to the system, which
allows porters to ``check out'' a source package (usually one which
-cannot yet be autobuilt) and work on it.
+cannot yet be auto-built) and work on it.
<p>
<package>buildd</package> is not yet available as a package; however,
most porting efforts are either using it currently or planning to use
enhanced to support cross-compiling.
- <sect id="collaborative-maint">Collaborative maintenance
- <p>
-&FIXME; Speak about Uploaders: field, about the intelligent use
-of the PTS. Insist that it's a "must have" for base and standard
-packages.
-
+ <sect id="collaborative-maint">
+ <heading>Collaborative maintenance</heading>
+ <p>
+"Collaborative maintenance" is a term describing the sharing of Debian
+package maintenance duties by several people. This collaboration is
+almost a good idea, since it generally results in higher quality and
+faster bug fix turnaround time. It is strongly recommended that
+packages in which a priority of <tt>Standard</tt> or which are part of
+the base set have co-maintainers.</p>
+ <p>
+Generally there is a primary maintainer and one or more
+co-maintainers. The primary maintainer is the whose name is listed in
+the <tt>Maintainer</tt> field of the <file>debian/control</file> file.
+Co-maintainers are all the other maintainers.</p>
+ <p>
+In its most basic form, the process of adding a new co-maintainer is
+quite easy:<list>
+ <item>
+ <p>
+Setup the co-maintainer with access to the sources you build the
+package from. Generally this implies you are using a network-capable
+version control system, such as <prgn>CVS</prgn> or
+<prgn>Subversion</prgn>.</p>
+ </item>
+ <item>
+ <p>
+Add the co-maintainer's correct maintainer name and address to the
+<tt>Uploaders</tt> field in the global part of the
+<file>debian/control</file> file.</p>
+ </item>
+ <item>
+ <p>
+Using the PTS (<ref id="pkg-tracking-system">), the co-maintainers
+should subscribe themselves to the appropriate source package.</p>
+ </item>
+ </list></p>
+ </sect>
<sect id="archive-manip">
<heading>Moving, Removing, Renaming, Adopting, and Orphaning
<tt>Maintainer:</tt> field, although it can take a few hours after the
upload is done. If you do not expect to upload a new version for a while,
you can use <ref id="pkg-tracking-system"> to get the bug reports. However,
-make sure that the old maintainer is not embarassed by the fact that
+make sure that the old maintainer is not embarrassed by the fact that
he will continue to receive the bugs during that time.
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
+give an informative 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
+If this situation is unacceptable, 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).
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>
+Once a corrected package is available in the <em>unstable</em>
distribution, you can close the bug. This can be done automatically,
read <ref id="upload-bugfix">.
</enumlist>
<sect1 id="helper-scripts">Helper scripts
<p>
- &FIXME; debhelper best, debmake obsolete, yada exists. Custom
- rules files are ok too: http://people.debian.org/~srivasta/rules
- Tools are great but you still have to understand what they do
- => read their documentation.
+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>
- &FIXME; presentation of "dbs", example package: hello-dbs
+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 functionalities. The package
+<package>hello-dbs</package> is a simple example that demonstrates how to
+use <package>dbs</package>.
+ <p>
+Additionally, dbs provides facilities to create the patches and to keep
+track of what they are for.
<sect1 id="multiple-binary">Multiple binary packages
<p>
- &FIXME; dh_install, example of packages with multiple
- configure/make cycles
- Example packages: vim (custom system)
+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 disk space).
+ <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.
+Like porters, translators have a difficult task. Since they work on many
+packages, they cannot keep track of every change in packages in order to
+be informed when a translated string is outdated. Fortunately
+<package>debconf</package> can automatically report outdated translations,
+if package maintainers follow some basic guidelines described below.
+ <p>
+Translators can use <prgn>debconf-getlang</prgn> (package
+<package>debconf-utils</package>) to write a <file>templates.xx</file>
+file containing both English and localized fields (where <em>xx</em> is
+the language code, may be followed by a country code). This file can be
+put into the <file>debian</file> subdirectory without any change.
+ <p>
+When building a binary package, <file>debian/templates.xx</file> files are
+merged along with <file>debian/templates</file> to generate the
+<file>templates</file> file contained in the binary package. This is
+automatically done by <prgn>dh_installdebconf</prgn> (package
+<package>debhelper</package>). If you do not use debhelper, you can
+do the same with <prgn>debconf-mergetemplate</prgn>
+(package <package>debconf-utils</package>).
+ <p>
+When the package maintainer needs to update the templates file, he only
+changes <file>debian/templates</file>. When English strings in this file
+and in <file>debian/templates.xx</file> differ, translators do know that
+their translation is outdated.
+ <p>
+Please see the page about
+<url id="&url-debconf-l10n-help;" name="localizing debconf templates files">
+at the Debian web site, it contains more detailed instructions, including a
+full example.
<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>
- &FIXME; http://www.netfort.gr.jp/~dancer/column/libpkg-guide/
+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>
- &FIXME; perl, python, ocaml, java, emacs.
- ocaml:
- /usr/share/doc/ocaml/ocaml_packaging_policy.gz
- a good example are packages libzip-ocaml{,-dev}
- perl:
- http://www.debian.org/doc/packaging-manuals/perl-policy/
- libdbd-pg-perl binary package, libmldbm-perl arch all package
- emacs:
- http://www.debian.org/doc/packaging-manuals/debian-emacs-policy
- java:
- http://people.debian.org/~opal/java/policy.html/
- python:
- /usr/share/doc/python/python-policy.txt.gz in python package
+Several subsets of packages have special sub-policies 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 <package>ocaml</package> 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>
- &FIXME; debconf-devel(8) is a MUST read
+Debconf is a configuration management system, it is used by all the
+various packaging scripts (postinst mainly) to request feedback from the
+user concerning how 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"> man page.
+It is something that you must 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,
on a database server but just on the corresponding library.
sympa may be an example package
-
+-->
<sect id="misc-advice">
- <heading>Miscellaenous advice</heading>
+ <heading>Miscellaneous advice</heading>
<sect1 id="writing-desc">
<heading>Writing useful descriptions</heading>
<p>
For example, apart from the usual description that you adapt from the
upstream <file>README</file>, you should include the URL of the
-website if there's any. If the package is not yet considered stable
+web site 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>
+For consistency and for an aesthetic concern, you should capitalize the
+first letter of the description.
+ <p>
Last but not least, since the first user impression is based on
-that description, you should be careful to avoid english
+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>
+<prgn>ispell</prgn> has a special option (<tt>-g</tt>) for that:
+<example>ispell -d american -g debian/control</example>.
+
New maintainers usually have certain difficulties creating Debian packages
— this is quite understandable. That is why the sponsor is there, to check
the package and verify that it is good enough for inclusion in Debian.
-(Note that if the sponsored package is new, the FTP admins will also have to
+(Note that if the sponsored package is new, the ftpmasters will also have to
inspect it before letting it in.)
<p>
Sponsoring merely by signing the upload or just recompiling is
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">
alien
dpkg-repack
grep-dctrl
- pbuilder -->
+-->
</book>
~ianmdlvl / developers-reference.git / blobdiff