<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.106 $">
+ <!entity cvs-rev "$Revision: 1.109 $">
<!-- 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 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>
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>
<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.
<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
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>
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