<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.108 $">
+ <!entity cvs-rev "$Revision: 1.114 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
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
+web at <url id="url-vote">. You will find there additional information
about how to make a vote proposal.
<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
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.
+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
-occasionnaly used to work on documentation like the one you are
+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>,
+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.
+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
<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>
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>
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