<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.110 $">
+ <!entity cvs-rev "$Revision: 1.121 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<copyright>
<copyrightsummary>
-copyright ©1998–2002 Adam Di Carlo</copyrightsummary>
+copyright ©1998—2002 Adam Di Carlo</copyrightsummary>
<copyrightsummary>
copyright ©1997, 1998 Christian Schwarz</copyrightsummary>
<p>
<p>
A copy of the GNU General Public License is available as &file-GPL; in
the &debian-formal; distribution or on the World Wide Web at <url
-id="&url-gpl;" name="the GNU website">. You can also obtain it by
+id="&url-gpl;" name="the GNU web site">. You can also obtain it by
writing to the &fsf-addr;.
<toc detail="sect1">
administrator at &email-listmaster;. More information on available
mailing lists can be found in <ref id="mailing-lists">.
&email-debian-devel-announce; is another list which is mandatory
-for anyone who wish to follow Debian's development.
+for anyone who wishes to follow Debian's development.
<p>
You should subscribe and lurk (that is, read without posting) for a
bit before doing any coding, and you should post about your intentions
on similar tasks. That way, you can learn from experienced developers.
For example, if you are interested in packaging existing software for
Debian you should try to get a sponsor. A sponsor will work together
-with you on your package and upload it to the Debian archive once he
-is happy with the packaging work you have done. You can find a sponsor
+with you on your package and upload it to the Debian archive once they
+are happy with the packaging work you have done. You can find a sponsor
by mailing the &email-debian-mentors; mailing list, describing your
package and yourself and asking for a sponsor (see <ref id="sponsoring">
for more information on sponsoring). On the other hand, if you are
2440">.
<p>
The recommended public key algorithm for use in Debian development
-work is the DSA (sometimes call ``DSS'' or ``DH/ElGamal''). Other key
+work is DSA (sometimes call ``DSS'' or ``DH/ElGamal''). Other key
types may be used however. Your key length must be at least 1024
bits; there is no reason to use a smaller key, and doing so would be
much less secure. Your key must be signed with at least your own user
<sect id="user-maint">Maintaining your Debian information
<p>
-There's a LDAP database containing many informations concerning all
+There's a LDAP database containing information about all
developers, you can access it at <url id="&url-debian-db;">. You can
update your password (this password is propagated to most of the machines
that are accessible to you), your address, your country, the latitude and
<sect id="key-maint">Maintaining your public key
<p>
Be very careful with your private keys. Do not place them on any
-public servers or multiuser machines, such as
-<tt>&master-host;</tt>. Back your keys up; keep a copy offline.
+public servers or multiuser machines, such as the Debian servers
+(see <ref id="server-machines">). 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>
If you add signatures to your public key, or add user identities, you
-can update the debian key ring by sending your key to the key server at
+can update the Debian key ring by sending your key to the key server at
<tt>&keyserver-host;</tt>. If you need to add a completely new key,
or remove an old key, send mail to &email-debian-keyring;. The same
key extraction routines discussed in <ref id="registering"> apply.
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.
+<url id="&url-vote;" name="Debian Voting Information"> page. You will find
+there additional information about how to make a vote proposal.
<sect id="inform-vacation">Going on vacation gracefully
<chapt id="resources">Resources for Debian Developers
<p>
In this chapter you will find a very brief road map of the Debian
-mailing lists, the main Debian servers, other Debian machines
+mailing lists, the Debian machines
which may be available to you as a developer, and all the other
resources that are available to help you in your maintainer work.
<sect id="mailing-lists">Mailing lists
<p>
-The mailing list server is at <tt>&lists-host;</tt>. Mail
+The mailing list server is at <tt>&lists-host;</tt>.
+ <p>
+Online archives of mailing lists are available at <url
+id="&url-lists-archives;">.
+
+ <sect1 id="core-devel-mailing-lists">Core development mailing lists
+ <p>
+The core Debian mailing lists that developers should use are:
+<list>
+ <item>&email-debian-devel-announce;, used to announce important things to
+ developers.
+ All developers are expected to be subscribed to this list.
+ </item>
+ <item>&email-debian-devel;, used to discuss various development related
+ technical issues.
+ </item>
+ <item>&email-debian-policy;, where the Debian Policy is discussed and
+ voted on.
+ </item>
+ <item>&email-debian-project;, used to discuss various non-technical
+ issues related to the project.
+ </item>
+</list>
+ <p>
+There are
+other mailing lists available for a variety of special topics; see
+<url id="&url-debian-lists-subscribe;"> for a list.
+
+ <sect1 id="mailing-lists-subunsub">Subscribing and unsubscribing
+ <p>
+To subscribe to or unsubscribe from any of the Debian mailing lists, email
<tt>debian-<var>foo</var>-REQUEST@&lists-host;</tt>, where
<tt>debian-<var>foo</var></tt> is the name of the list, with the word
<tt>subscribe</tt> in the <em>Subject</em> to subscribe to the list or
-<tt>unsubscribe</tt> to unsubscribe. More detailed instructions on
-how to subscribe and unsubscribe to the mailing lists can be found at
-<url id="&url-debian-lists-subscribe;">, <url id="&url-debian-lists;">
-or locally in &file-mail-lists; if you have the
-<package>doc-debian</package> package installed.
+<tt>unsubscribe</tt> to unsubscribe.
+ <p>
+If you prefer to use a web page to subscribe to multiple mailing lists,
+there's one at <url id="&url-debian-lists-subscribe;">.
+ <p>
+You can download the current list of mailing lists and basic usage
+instructions from <url id="&url-debian-lists;">
+or install the <package>doc-debian</package> package and have it
+locally in &file-mail-lists;.
+
+ <sect1 id="mailing-lists-rules">Basic rules for use
<p>
When replying to messages on the mailing list, please do not send a
carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
request to be copied. Anyone who posts to a mailing list should read
it to see the responses.
<p>
-The following are the core Debian mailing lists: &email-debian-devel;,
-&email-debian-policy;, &email-debian-user;, &email-debian-private;,
-&email-debian-announce;, and &email-debian-devel-announce;. All
-developers are expected to be subscribed to at least
-&email-debian-devel-announce;. There are
-other mailing lists available for a variety of special topics; see
-<url id="&url-debian-lists-subscribe;"> for a list. Cross-posting
-(sending the same message to multiple lists) is discouraged.
+Cross-posting (sending the same message to multiple lists) is discouraged.
+As ever on the net, please trim down the quoting of articles you're
+replying to. In general, please adhere to the usual conventions for
+posting messages. Please read the <url name="code of conduct"
+id="&url-debian-lists;"> for more information.
+
+ <sect1 id="mailing-lists-special">Special lists
<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
list are not available on the web for obvious reasons, but you can see
-them using your shell account on <tt>&master-host;</tt> and looking
+them using your shell account on <tt>lists.debian.org</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
for Debian related correspondence such as contacting upstream authors
about licenses, bugs, etc. or discussing the project with others where it
might be useful to have the discussion archived somewhere.
- <p>
-As ever on the net, please trim down the quoting of articles you're
-replying to. In general, please adhere to the usual conventions for
-posting messages.
- <p>
-Online archives of mailing lists are available at <url
-id="&url-lists-archives;">.
<sect id="irc-channels">IRC channels
<p>
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
+always full of interesting information. 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
+in the archives of debian-private in
+<file>master.debian.org:&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
<p>
-This document contains many informations very useful to Debian developers,
+This document contains a lot of information 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
+
+ <sect id="server-machines">Debian machines
+ <p>
+Debian has several computers working as servers, most of which serve
+critical functions in the Debian project. Most of the machines are used
+for porting activities, and they all have a permanent connection to the
+Internet.
+ <p>
+Most of the machines are available for individual developers to use,
+as long as the developers follow the rules set forth in the
+<url name="Debian Machine Usage Policies" id="&url-dmup;">.
+ <p>
+Generally speaking, you can use these machines for Debian-related purposes
+as you see fit. Please be kind to system administrators, and do not use
+up tons and tons of disk space, network bandwidth, or CPU without first
+getting the approval of the admins. Usually these machines are run by
+volunteers.
<p>
-Debian servers are well known servers which serve critical functions
-in the Debian project. Every developer should know what these servers
-are and what they do.
+Please take care to protect your Debian passwords and SSH keys installed on
+Debian machines. Avoid login or upload methods which send passwords over
+the Internet in the clear, such as telnet, FTP, POP etc.
+ <p>
+Please do not put any material that doesn't relate to Debian on the Debian
+servers, unless you have prior permission.
+ <p>
+The current list of Debian machines is available at
+<url id="&url-devel-machines;">. That web page contains machine names,
+contact information, information about who can log in, SSH keys etc.
<p>
If you have a problem with the operation of a Debian server, and you
think that the system operators need to be notified of this problem,
-please find the contact address for the particular machine at <url
-id="&url-devel-machines;">. If you have a non-operating problems
-(such as packages to be remove, suggestions for the web site, etc.),
+the Debian system administrator team is reachable at
+<email>debian-admin@lists.debian.org</email>.
+ <p>
+If you have a problem with a certain service, not related to the system
+administration (such as packages to be removed from the archive,
+suggestions for the web site, etc.),
generally you'll report a bug against a ``pseudo-package''. See <ref
id="submit-bug"> for information on how to submit bugs.
- <sect1 id="servers-master">The master server
+ <sect1 id="servers-bugs">The bugs server
<p>
-<tt>&master-host;</tt> is the canonical location for the Bug Tracking
+<tt>bugs.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
anything, however, to reduce unnecessary duplication of effort or
wasted processing time.
<p>
-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-host;</tt> such as disk
-full, suspicious activity, or whatever, send an email to
-&email-debian-admin;.
+All Debian developers have accounts on <tt>bugs.debian.org</tt>.
<sect1 id="servers-ftp-master">The ftp-master server
<p>
-The ftp-master server, <tt>&ftp-master-host;</tt> (or
-<tt>auric.debian.org</tt>), holds the canonical copy of the Debian
+The <tt>ftp-master.debian.org</tt> server holds the canonical copy of the Debian
archive (excluding the non-US packages). Generally, package uploads
go to this server; see <ref id="upload">.
<p>
an email to &email-ftpmaster;, but also see the procedures in
<ref id="archive-manip">.
- <sect1 id="servers-www">The WWW server
+ <sect1 id="servers-non-us">The non-US server
<p>
-The main web server, <tt>&www-host;</tt>, is also known as
-<tt>klecker.debian.org</tt>. All developers are given accounts on this
-machine.
+The non-US server, <tt>non-us.debian.org</tt>,
+holds the canonical copy of the non-US part of the Debian archive.
+If you need to upload a package into one of the non-US sections, upload it
+to this server; see <ref id="upload-non-us">.
<p>
-If you have some Debian-specific information which you want to serve
-up on the web, you can do this by putting material in the
-<file>public_html</file> directory under your home directory. You should
-do this on <tt>klecker.debian.org</tt>. Any material you put in those areas
-are accessible via the URL
-<tt>http://people.debian.org/~<var>user-id</var>/</tt>.
-You should only use this particular location because it will be backed up,
-whereas on other hosts it won't. Please do not put any material on Debian
-servers not relating to Debian, unless you have prior permission.
-Send mail to &email-debian-devel; if you have any questions.
+Problems with the non-US package archive should generally be submitted as
+bugs against the <package>nonus.debian.org</package> pseudo-package (notice
+the lack of hyphen between "non" and "us" in the pseudo-package name
+— that's for backwards compatibility). Remember to check whether or
+not someone else has already reported the problem on the
+<url id="http://bugs.debian.org/nonus.debian.org" name="Bug Tracking System">.
+
+ <sect1 id="servers-www">The www-master server
+ <p>
+The main web server is <tt>www-master.debian.org</tt>.
+It holds the official web pages, the face
+of Debian for most newbies.
<p>
If you find a problem with the Debian web server, you should generally
submit a bug against the pseudo-package,
-<package>www.debian.org</package>. First check whether or not someone
+<package>www.debian.org</package>. Remember to check whether or not someone
else has already reported the problem on the
<url id="http://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
+ <sect1 id="servers-people">The people web server
+ <p>
+<tt>people.debian.org</tt> is the server used
+for developers' own web pages about anything related to Debian.
+ <p>
+If you have some Debian-specific information which you want to serve
+on the web, you can do this by putting material in the
+<file>public_html</file> directory under your home directory on
+<tt>people.debian.org</tt>.
+This will be accessible at the URL
+<tt>http://people.debian.org/~<var>your-user-id</var>/</tt>.
+ <p>
+You should only use this particular location because it will be backed up,
+whereas on other hosts it won't.
+ <p>
+Usually the only reason to use a different host is when you need to publish
+materials subject to the U.S. export restrictions, in which case you can use
+one of the other servers located outside the United States, such as the
+aforementioned <tt>non-us.debian.org</tt>.
+ <p>
+Send mail to &email-debian-devel; if you have any questions.
<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
+Our CVS server is located on <tt>cvs.debian.org</tt>.
+ <p>
+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>
the Debian account that should own the CVS root area, and why you need it.
- <sect1 id="devel-db">The Developers Database
+ <sect id="devel-db">The Developers Database
<p>
The Developers Database, at <url id="&url-debian-db;">, is an LDAP
directory for managing Debian developer attributes. You can use this
have accounts on these machines.
- <sect id="other-machines">Other Debian developer machines
- <p>
-There are other Debian machines which may be made available to you.
-You can use these for Debian-related purposes as you see fit. Please
-be kind to system administrators, and do not use up tons and tons of
-disk space, network bandwidth, or CPU without first getting the
-approval of the local maintainers. Usually these machines are run by
-volunteers. Generally, these machines are for porting activities.
- <p>
-Aside from the servers mentioned in <ref id="server-machines">, there
-is a list of machines available to Debian developers at <url
-id="&url-devel-machines;">.
-
-
-
<sect id="archive">The Debian archive
<p>
The &debian-formal; distribution consists of a lot of packages
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 <file>Packages</file> and <file>Sources</file> files in the
+The <file>Packages</file> and <file>Sources</file> files in the
distribution subdirectories can reference files in the <file>pool/</file>
-directory.
+directory. The directory tree below each of the distributions is arranged
+in an identical manner. What we describe below for <em>stable</em> is
+equally applicable to the <em>unstable</em> and <em>testing</em>
+distributions.
<p>
<file>dists/stable</file> contains three directories, namely <file>main</file>,
-<file>contrib</file>, and <file>non-free</file>.
+<file>contrib</file>, and <file>non-free</file>.
<p>
In each of the areas, there is a directory for the source packages
(<file>source</file>) and a directory for each supported architecture
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
This development cycle is based on the assumption that the
<em>unstable</em> distribution becomes <em>stable</em> after passing a
period of being in <em>testing</em>. Even once a distribution is
-considered stable, a few bugs inevitably remain &mdash that's why the
+considered stable, a few bugs inevitably remain — that's why the
stable distribution is updated every now and then. However, these
updates are tested very carefully and have to be introduced into the
archive individually to reduce the risk of introducing new bugs. You
<em>unstable</em>.
<p>
An alternative to <em>experimental</em> is to use your personal web space
-on <tt>people.debian.org</tt> (<tt>klecker.debian.org</tt>).
+on <tt>people.debian.org</tt>.
<sect1 id="codenames">Release code names
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 <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 <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 <file>byhand</file> directory waiting a manual
-installation by the ftpmasters. Otherwise, if any error has been detected,
+Packages are uploaded by all the maintainers into a directory called
+<file>unchecked</file>. This directory is scanned every 15 minutes by the katie script
+that verifies the integrity of the uploaded packages and the cryptographic
+signatures. If the package is considered ready to be installed, it
+is moved into the <file>accepted</file> directory. If this is the first upload of
+the package, it is moved in the <file>new</file> directory, where it waits
+for an approval of the ftpmasters. If the package contains files to be installed
+"by-hand" is is moved in the <file>byhand</file> directory, where it waits
+for a manual installation by the ftpmasters. Otherwise, if any error has been detected,
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
-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.
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 <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.
+That leaves the corresponding number of days for the maintainer
+to react and upload another fix themselves if they are not
+completely satisfied with the NMU. Alternatively they can remove
+the NMU.
<p>
The use of that delayed feature can be simplified with a bit
of integration with your upload tool. For instance, if you use
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>
to keep someone informed of the progression of his packages in testing.
<p>
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
+why the package is refused, one may have to find it on their own by looking
what would break with the inclusion of the package. The <url
id="&url-testing-faq;" name="testing FAQ"> gives some more information
about the usual problems which may be causing such troubles.
<sect1 id="pkg-info-web">On the web
<p>
-Each package has several dedicated web pages that contains many
-informations. <tt>http://&packages-host;/<var>package-name</var></tt>
+Each package has several dedicated web pages that contain a lot of
+information. <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 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.
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)
+ <sect2 id="upload-non-us">Uploading to <tt>non-US</tt>
<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
&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>
<item>
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.
+the BTS, and explain to them that they have 7 days to react if they want
+to cancel the NMU.
<item>
Follow what happens, you're responsible for any bug that you introduced
with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS)
make a release based on a new upstream version then the person making
the release should start with the <var>debian-revision</var> value
`0.1'. The usual maintainer of a package should start their
-<var>debian-revision</var> numbering at `1'. Note that if you do
-this, you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the
-<tt>-sa</tt> switch to force the build system to pick up the new
-source package (normally it only looks for Debian revisions of '0' or
-'1' — it's not yet clever enough to know about `0.1').
+<var>debian-revision</var> numbering at `1'.
<sect2 id="nmu-changelog">
entry of your next upload.
<p>
In any case, you should not be upset by the NMU. An NMU is not a
-personal attack against the maintainer. It is just the proof that
-someone cares enough about the package and was willing to help
-you in your work. You should be thankful to him and you may want to
-ask him if he would be interested to help you on a more frequent
+personal attack against the maintainer. It is a proof that
+someone cares enough about the package and that they were willing to help
+you in your work, so you should be thankful. You may also want to
+ask them if they would be interested to help you on a more frequent
basis as co-maintainer or backup maintainer
(see <ref id="collaborative-maint">).
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
-he will continue to receive the bugs during that time.
+make sure that the old maintainer has no problem with the fact that
+they will continue to receive the bugs during that time.
<sect id="bug-handling">Handling package bugs
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.
+they 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>
<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
+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>
-Additionnaly, dbs provides facilities to create the patches and to keep
+Additionally, dbs provides facilities to create the patches and to keep
track of what they are for.
<sect1 id="multiple-binary">Multiple binary packages
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).
+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
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
+When the package maintainer needs to update the templates file, they only
+change <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>
<sect1 id="bpp-other-specific-practices">Other specific packages
<p>
-Several subsets of packages have special subpolicies and corresponding
-packaging rules and practices :
+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;">,
<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 :
+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;"
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>
+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>
<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
+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"> manpage.
-It is something that you must have read if you decide to use debconf.
+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
-->
<sect id="misc-advice">
- <heading>Miscellaenous advice</heading>
+ <heading>Miscellaneous advice</heading>
<sect1 id="writing-desc">
<heading>Writing useful descriptions</heading>
<p>
The description of the package (as defined by the corresponding field
in the <file>control</file> file) is usually the first information
-available to the user before he installs it. As such, it should
+available to the user before they install it. As such, it should
provide all the required information to let him decide whether
to install the package.
<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>.
+
<sect1 id="submit-many-bugs">Reporting lots of bugs at once
<p>
Reporting a great number of bugs for the same problem on a great
-number of different packages &mdash i.e., more than 10 &mdash is a deprecated
+number of different packages — i.e., more than 10 — is a deprecated
practice. Take all possible steps to avoid submitting bulk bugs at
all. For instance, if checking for the problem can be automated, add
a new check to <package>lintian</package> so that an error or warning
useful information about this maintainer. Start by logging into
the <url id="&url-debian-db;" name="Debian Developer's Database">
and doing a full search to check whether the maintainer is on vacation
-and when he was last seen. Collect any important package names
-he maintains and any Release Critical bugs filled against them.
+and when they were last seen. Collect any important package names
+they maintain and any Release Critical bugs filed against them.
<p>
Send all this information to &email-debian-qa;, in order to let the
QA people do whatever is needed.
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
+You may also be interested in 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-name>@&pts-host;</tt>
email address.
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
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 <file>.orig.tar.gz</file> file that he's
-providing.
+built by your sponsoree. In that case, you have to check that they haven't
+altered the upstream files in the <file>.orig.tar.gz</file> file that
+they're providing.
<p>
Do not be afraid to write the sponsoree back and point out changes
that need to be made. It often takes several rounds of back-and-forth
~ianmdlvl / developers-reference.git / blobdiff