<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
<!-- include version information so we don't have to hard code it
within the document -->
- <!entity % versiondata SYSTEM "version.ent"> %versiondata;
+ <!ENTITY % versiondata SYSTEM "version.ent"> %versiondata;
<!-- common, language independant entities -->
- <!entity % commondata SYSTEM "common.ent" > %commondata;
+ <!ENTITY % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.204 $">
+ <!ENTITY cvs-rev "$Revision: 1.219 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
- <!entity cvs-en-rev "X.YY">
+ <!ENTITY cvs-en-rev "X.YY">
-->
- <!-- -->
- <!entity FIXME "<em>FIXME:</em> ">
+ <!-- how to mark a section that needs more work -->
+ <!ENTITY FIXME "<em>FIXME:</em> ">
]>
<debiandoc>
preparations you have to do before you can register to become a Debian
developer.
-For example, before you apply, you have to to read the <url
+For example, before you apply, you have to read the <url
id="&url-social-contract;" name="Debian Social Contract">.
Registering as a developer means that you agree with and pledge to
uphold the Debian Social Contract; it is very important that
<p>
A big part of your job as Debian maintainer will be to stay in contact
with the upstream developers. Debian users will sometimes report bugs
-to the Bug Tracking System that are not specific to Debian. You
-must forward these bug reports to the upstream developers so that
-they can be fixed in a future release. It's not your job to fix
-non-Debian specific bugs. However, if you are able to do so, you are
-encouraged to contribute to upstream development of the package by
-providing a fix for the bug. Debian users and developers will often
-submit patches to fix upstream bugs, and you should evaluate and
-forward these patches upstream.
+that are not specific to Debian to our bug tracking system. You
+have to forward these bug reports to the upstream developers so that
+they can be fixed in a future upstream release.
+ <p>
+While it's not your job to fix non-Debian specific bugs, you may freely
+do so if you're able. When you make such fixes, be sure to pass them on
+to the upstream maintainers as well. Debian users and developers will
+sometimes submit patches to fix upstream bugs -- you should evaluate
+and forward these patches upstream.
<p>
If you need to modify the upstream sources in order to build a policy
compliant package, then you should propose a nice fix to the upstream
<sect id="mailing-lists">Mailing lists
<p>
-The mailing list server is at <tt>&lists-host;</tt>.
+Much of the conversation between Debian developers (and users) is managed
+through a wide array of mailing lists we host at
+<tt><url id="http://&lists-host;/" name="&lists-host;"></tt>.
+To find out more on how to subscribe or unsubscribe, how to post and how not
+to post, where to find old posts and how to search them, how to contact the
+list maintainers and see various other information about the mailing lists,
+please read <url id="&url-debian-lists;">. This section will only cover
+aspects of mailing lists that are of particular interest to developers.
+
+ <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>
+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.
<p>
-Online archives of mailing lists are available at <url
-id="&url-lists-archives;">.
+Please read the <url name="code of conduct" id="&url-debian-lists;#codeofconduct">
+for more information.
<sect1 id="core-devel-mailing-lists">Core development mailing lists
<p>
</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.
- <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-txt;">
-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>
-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.
- <p>
-Please read the <url name="code of conduct" id="&url-debian-lists;">
-for more information.
+There are other mailing lists available for a variety of special topics;
+see <url id="http://&lists-host;/"> for a list.
<sect1 id="mailing-lists-special">Special lists
<p>
about licenses, bugs, etc. or discussing the project with others where it
might be useful to have the discussion archived somewhere.
+ <sect1 id="mailing-lists-new">Requesting new development-related lists
+ <p>
+Before requesting a mailing list that relates to the development of a
+package (or a small group of related packages), please consider if using
+an alias (via a .forward-aliasname file on master.debian.org, which
+translates into a reasonably nice <var>you-aliasname@debian.org</var>
+address) or a self-managed mailing list on <qref id="alioth">Alioth</qref>
+is more appropriate.
+ <p>
+If you decide that a regular mailing list on lists.debian.org is really what
+you want, go ahead and fill in a request, following <url name="the HOWTO"
+id="&url-debian-lists-new;">.
<sect id="irc-channels">IRC channels
<p>
<sect id="pkg-tracking-system">The Package Tracking System
<p>
-The Package Tracking System (PTS) is basically a tool to track by mail
-the activity of a source package. You just have to subscribe
-to a source package to start getting the mails related to it.
-You get the same mails as the maintainer. Each mail
-sent through the PTS is classified and associated to one of
-the keyword listed below. This will let you select the mails that
+The Package Tracking System (PTS) is an email-based tool to track
+the activity of a source package. This really means that you can
+get the same emails that the package maintainer gets, simply by
+subscribing to the package in the PTS.
+ <p>
+Each email sent through the PTS is classified and associated to one of
+the keywords listed below. This will let you select the mails that
you want to receive.
<p>
By default you will get:
<tag><tt>bts-control</tt>
<item>
-The control mails notifying a status change in one of the bugs.
+The email notifications from <email>control@bugs.debian.org</email>
+about bug report status changes.
<tag><tt>upload-source</tt>
<item>
-The
confirmation mail from <prgn>katie</prgn> when an uploaded source
+The
email notification from <prgn>katie</prgn> when an uploaded source
package is accepted.
<tag><tt>katie-other</tt>
<item>
-Other warning and error mails from <prgn>katie</prgn> (like the
-override disparity for the section or priority field).
+Other warning and error emails from <prgn>katie</prgn> (such as an
+override disparity for the section and/or the priority field).
<tag><tt>default</tt>
<item>
-Any non-automatic mail sent to the PTS by people who wanted to
+Any non-automatic email sent to the PTS by people who wanted to
contact the subscribers of the package. This can be done by sending mail
-to <tt><var>srcpackage</var>@&pts-host;</tt>. In order to prevent spam,
-mails sent to these addresses must contain the header "X-PTS-Approved"
-with a non-empty string.
-
+to <tt><var>sourcepackage</var>@&pts-host;</tt>. In order to prevent spam,
+all messages sent to these addresses must contain the <tt>X-PTS-Approved</tt>
+header with a non-empty value.
<tag><tt>summary</tt>
<item>
-In the future, you may receive regular summary mails to keep you
-informed of the package's status (bug statistics, porting overview,
-progression in <em>testing</em>, ...).
+(This is a planned expansion.)
+The regular summary emails about the package's status (bug statistics,
+porting overview, progression in <em>testing</em>, ...).
</taglist>
+
<p>
-You can also decide to receive some more information:
+You can also decide to receive additional information:
<taglist>
<tag><tt>upload-binary</tt>
<item>
-The confirmation mail from <prgn>katie</prgn> when an uploaded binary
-package is accepted (to check that your package is recompiled for all
-architectures).
+The email notification from <prgn>katie</prgn> when an uploaded binary
+package is accepted. In other words, whenever a build daemon or a porter
+uploads your package for another architecture, you can get an email to
+track how your package gets recompiled for all architectures.
<tag><tt>cvs</tt>
<item>
-CVS commits if the maintainer has setup a system to forward commit
-notification to the PTS.
+CVS commit notifications, if the package has a CVS repository and the
+maintainer has set up forwarding commit notifications to the PTS.
<tag><tt>ddtp</tt>
<item>
<taglist>
-<tag><tt>subscribe <srcpackage> [<email>]</tt>
+<tag><tt>subscribe <sourcepackage> [<email>]</tt>
<item>
Subscribes <var>email</var> to communications related to the source package
- <var>srcpackage</var>. Sender address is used if the second argument is
- not present. If <var>srcpackage</var> is not a valid source package,
+ <var>sourcepackage</var>. Sender address is used if the second argument is
+ not present. If <var>sourcepackage</var> is not a valid source package,
you'll get a warning. However if it's a valid binary package, the PTS
will subscribe you to the corresponding source package.
-<tag><tt>unsubscribe <srcpackage> [<email>]</tt>
+<tag><tt>unsubscribe <sourcepackage> [<email>]</tt>
<item>
- Removes a previous subscription to the source package <var>srcpackage</var>
+ Removes a previous subscription to the source package <var>sourcepackage</var>
using the specified email address or the sender address if the second
argument is left out.
<tag><tt>keyword [<email>]</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:
+ Tells you the keywords that you are accepting.
+ For an explanation of keywords, <qref id="pkg-tracking-system">see
+ above</qref>. Here's a quick summary:
<list>
<item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
<item><tt>bts-control</tt>: reply to mails sent to &email-bts-control;
<item><tt>default</tt>: all the other mails (those which aren't "automatic")
</list>
-<tag><tt>keyword <srcpackage> [<email>]</tt>
+<tag><tt>keyword <sourcepackage> [<email>]</tt>
<item>
- Same as previous item but for the given source package since
+ Same as the previous item but for the given source package, since
you may select a different set of keywords for each source package.
<tag><tt>keyword [<email>] {+|-|=} <list of keywords></tt>
Accept (+) or refuse (-) mails associated to the given keyword(s).
Define the list (=) of accepted keywords.
-<tag><tt>keyword <srcpackage> [<email>] {+|-|=} <list of keywords></tt>
+<tag><tt>keyword <sourcepackage> [<email>] {+|-|=} <list of keywords></tt>
<item>
Same as previous item but overrides the keywords list for the
indicated source package.
<sect1 id="pts-mail-filtering">Filtering PTS mails
<p>
Once you are subscribed to a package, you will get the mails sent to
-<tt><var>srcpackage</var>@packages.qa.debian.org</tt>. Those mails
+<tt><var>sourcepackage</var>@packages.qa.debian.org</tt>. Those mails
have special headers appended to let you filter them in a special
-mailbox with <prgn>procmail</prgn>. The added headers are
+mailbox (e.g. with <prgn>procmail</prgn>). The added headers are
<tt>X-Loop</tt>, <tt>X-PTS-Package</tt>, <tt>X-PTS-Keyword</tt> and
<tt>X-Unsubscribe</tt>.
<p>
<p>
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
+to the PTS so that the subscribers (and possible co-maintainers) can
closely follow the package's evolution.
<p>
-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.
+Once you set up the CVS repository to generate commit notifications,
+you just have to make sure it sends a copy of those mails
+to <tt><var>sourcepackage</var>_cvs@&pts-host;</tt>. Only the people
+who accept the <em>cvs</em> keyword will receive these notifications.
<sect1 id="pts-web">The PTS web interface
<p>
-The PTS has been extended with a web interface that puts together
-many information about each source package. It features many useful
+The PTS has a web interface at <url id="http://&pts-host;/"> that puts
+together a lot of information about each source package. It features many useful
links (BTS, QA stats, contact information, DDTP translation status,
-buildd logs) and gathers many more information from various places
+buildd logs) and gathers much more information from various places
(30 latest changelog entries, testing status, ...). It's a very useful
tool if you want to know what's going on with a specific source
-package. Furthermore there's a form that let you easily subscribe to
-the mail service offered by the PTS.
+package. Furthermore there's a form that allows easy subscription to
+the PTS via email.
<p>
You can jump directly to the web page concerning a specific source package
-with an url like <tt>http://&pts-host;/<var>srcpackage</var></tt>. Otherwise
-you can go through the <url id="http://&pts-host;" name="main page">.
+with a URL like <tt>http://&pts-host;/<var>sourcepackage</var></tt>.
<p>
This web interface has been designed like a portal for the development of
-packages: you can add custom content on the pages of your packages. You can
-add "static information" (news item that are meant to stay available
+packages: you can add custom content on your packages' pages. You can
+add "static information" (news items that are meant to stay available
indefinitely) and news items in the "latest news" section.
<p>
-Static news can be used to indicate:
+Static news items can be used to indicate:
<list>
-<item>the availability of a project hosted on alioth.debian.org for co-maintaining the package
-<item>a link to the upstream website
-<item>a link to the upstream bugtracker
+<item>the availability of a project hosted on <qref id="alioth">Alioth</qref> for co-maintaining the package
+<item>a link to the upstream web site
+<item>a link to the upstream bug tracker
<item>the existence of an IRC channel dedicated to the software
<item>any other available resource that could be useful in the maintenance of the package
</list>
-Usual news item may be used to announce that:
+Usual news items may be used to announce that:
<list>
-<item>beta packages are available for test
+<item>beta packages are available for testing
<item>final packages are expected for next week
<item>the packaging is about to be redone from scratch
<item>backports are available
-<item>the maintainer is on vacation (if he wishes to publish this information)
+<item>the maintainer is on vacation (if they wish to publish this information)
<item>a NMU is being worked on
<item>something important will affect the package
</list>
<p>
-Both kind of news are generated in a similar manner: you just have to send a mail
-either to <email>pts-static-news@qa.debian.org</email> or to
-<email>pts-news@qa.debian.org</email>. The mail should indicate which package is
-concerned by the news by giving the name of the source package in a
+Both kind of news are generated in a similar manner: you just have to send
+an email either to <email>pts-static-news@qa.debian.org</email> or to
+<email>pts-news@qa.debian.org</email>. The mail should indicate which
+package is concerned by having the name of the source package in a
<tt>X-PTS-Package</tt> mail header or in a <tt>Package</tt> pseudo-header (like the
-BTS reports). If an URL is available in the <tt>X-PTS-Url</tt> mail header or in
+BTS reports). If a URL is available in the <tt>X-PTS-Url</tt> mail header or in
the <tt>Url</tt> pseudo-header, then the result is a link to that URL instead
of a complete news item.
<p>
-Some examples of valid mails used to generate news item in the PTS are following. The first one
-adds a link to the cvsweb interface of debian-cd in the "Static information" section.
+Here are a few examples of valid mails used to generate news items in
+the PTS. The first one adds a link to the cvsweb interface of debian-cd
+in the "Static information" section:
<example>
From: Raphael Hertzog <hertzog@debian.org>
To: pts-static-news@qa.debian.org
Package: debian-cd
Url: http://cvs.debian.org/debian-cd/
</example>
-The second one is an announce sent to a mailing list which is also sent
+ <p>
+The second one is an announcement sent to a mailing list which is also sent
to the PTS so that it is published on the PTS web page of the package. Note the
-use of the BCC field to avoid answers sent to the PTS by mistake ...
+use of the BCC field to avoid answers sent to the PTS by mistake.
<example>
From: Raphael Hertzog <hertzog@debian.org>
To: debian-gtk-gnome@lists.debian.org
Subject: Galeon 2.0 backported for woody
X-PTS-Package: galeon
-Hello gnomers !
+Hello gnomers!
I'm glad to announce that galeon has been backported for woody. You'll find
everything here:
...
</example>
<p>
-Think twice before adding a news to the PTS because you won't be able to
-remove it later and you wan't be able to edit it either. The only thing that you
-can do is send a second news that will deprecate the information contained in
-the first news.
+Think twice before adding a news item to the PTS because you won't be able
+to remove it later and you wan't be able to edit it either. The only thing
+that you can do is send a second news item that will deprecate the
+information contained in the previous one.
<sect id="ddpo">Developer's packages overview
<p>
you don't forget any open bug, and so that you don't forget which
packages are under your responsibility.
+ <sect id="alioth">Debian *Forge: Alioth
+ <p>
+Alioth is a fairly new Debian service, based on a slightly modified version
+of the GForge software (which evolved from SourceForge). This software
+offers developers access to easy-to-use tools such as bug trackers, patch
+manager, project/task managers, file hosting services, mailing lists, CVS
+repositories etc. All these tools are managed via a web interface.
+ <p>
+It is intended to provide facilities to free software projects backed or led
+by Debian, facilitate contributions from external developers to projects
+started by Debian, and help projects whose goals are the promotion of Debian
+or its derivatives.
+ <p>
+For more information please visit <url id="&url-alioth;">.
+
<chapt id="pkgs">Managing Packages
<p>
In particular, it never makes sense to combine the <em>experimental</em>
distribution with anything else (see <ref id="experimental">).
- <sect1 id="upload-stable">Uploads to <em>stable</em>
+ <sect1 id="upload-stable">
+ <heading>Special case: uploads to the <em>stable</em> distribution</heading>
<p>
Uploading to <em>stable</em> means that the package will be placed into the
<file>stable-proposed-updates</file> directory of the Debian archive for further
<em>stable</em>, because otherwise the package won't be considered for
inclusion.
- <sect1 id="upload-t-p-u">Uploads to <em>testing-proposed-updates</em>
+ <sect1 id="upload-t-p-u">
+ <heading>Special case: uploads to <em>testing-proposed-updates</em></heading>
<p>
The testing distribution is fed with packages from unstable according to the rules
explained in <ref id="testing">. However, the release manager may stop the testing
if you use anonymous FTP to upload, place them into
&upload-queue;.
<p>
+If you want to use feature described in <ref id="delayed-incoming">,
+you'll have to upload to <tt>ftp-master</tt>. It is the only upload
+point that supports delayed incoming.
+ <p>
Please note that you should transfer
the changes file last. Otherwise, your upload may be rejected because the
archive maintenance software will parse the changes file and see that not
<p>
The bug tracking system's features interesting to developers are described
in the <url id="&url-bts-devel;" name="BTS documentation for developers">.
-This includes closing bugs, sending followup messages, assigning severities,
-tags, marking bugs as forwarded and other issues.
+This includes closing bugs, sending followup messages, assigning severities
+and tags, marking bugs as forwarded and other issues.
<p>
Operations such as reassigning bugs to other packages, merging separate
bug reports about the same issue, or reopening bugs when they are
<sect1 id="bug-answering">Responding to bugs
<p>
-Make sure that any discussion you have about bugs are sent both to
-the original submitter of the bug, and the bug itself (e.g.,
-<email>123@&bugs-host;</email>). If you're writing a new
+When responding to bugs, make sure that any discussion you have about
+bugs is sent both to the original submitter of the bug, and to the bug
+itself (e.g., <email>123@&bugs-host;</email>). If you're writing a new
mail and you don't remember the submitter email address, you can
use the <email>123-submitter@&bugs-host;</email> email to
contact the submitter <em>and</em> to record your mail within the
bug log (that means you don't need to send a copy of the mail to
<email>123@&bugs-host;</email>).
<p>
+If you get a bug which mentions "FTBFS", that means "Fails to build
+from source". Porters frequently use this acronym.
+ <p>
Once you've dealt with a bug report (e.g. fixed it), mark it as
<em>done</em> (close it) by sending an explanation message to
<email>123-done@&bugs-host;</email>. If you're fixing a bug by
<file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
testing this is <tt>testing-security</tt>, and for the previous
stable release, this is <tt>oldstable-security</tt>. Do not target
- <var>distribution</var>-proposed-updates!
+ <var>distribution</var>-proposed-updates or <tt>stable</tt>!
<item>Make descriptive, meaningful changelog entries. Others will
rely on them to determine whether a particular bug was fixed.
- Whenever possible, include an external reference, preferably a CVE
- identifier, so that it can be cross-referenced.
+ Always include an external reference, preferably a CVE
+ identifier, so that it can be cross-referenced. Include the same
+ information in the changelog for unstable, so that it is clear that
+ the same bug was fixed, as this is very helpful when verifying
+ that the bug is fixed in the next stable release. If a CVE
+ identifier has not yet been assigned, the security team will
+ request one so that it can be included in the package and in the advisory.
<item>Make sure the version number is proper. It must be greater
than the current package, but less than package versions in later
distributions. If in doubt, test it with <tt>dpkg
- --compare-versions</tt>. For <em>testing</em>, there must be
+ --compare-versions</tt>. Be careful not to re-use a version
+ number that you have already used for a previous upload. For
+ <em>testing</em>, there must be
a higher version in <em>unstable</em>. If there is none yet (for example,
if <em>testing</em> and <em>unstable</em> have the same version) you must upload a
new version to unstable first.
<sect2 id="bug-security-upload">Uploading the fixed package
<p>
-<em>DO NOT</em> upload a package to the security upload queue
+Do <strong>NOT</strong> upload a package to the security upload queue
(oldstable-security, stable-security, etc.) without
prior authorization from the security team. If the package does not
exactly meet the team's requirements, it will cause many problems and
delays in dealing with the unwanted upload.
<p>
-<em>DO NOT</em> upload your fix to proposed-updates without
+Do <strong>NOT</strong> upload your fix to proposed-updates without
coordinating with the security team. Packages from
security.debian.org will be copied into the proposed-updates directory
automatically. If a package with the same or a higher version number
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>
+quite easy:
+<list>
<item>
<p>
Setup the co-maintainer with access to the sources you build the
should subscribe themselves to the appropriate source package.</p>
</item>
</list></p>
+ <p>
+Collaborative maintenance can often be further eased with the use of
+tools on Alioth (see <ref id="alioth">).
</sect>
-
<chapt id="best-pkging-practices">
<heading>Best Packaging Practices</heading>
<p>
<p>
The following practices are relevant to the
<file>debian/control</file> file. They supplement the <url
-id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
+id="&url-debian-policy;ch-binary.html#s-descriptions"
name="Policy on package descriptions">.
<p>
The description of the package, as defined by the corresponding field
<example><var>package-name</var> are <var>synopsis</var>.</example>
-This way of forming a sentance from the package name and synopsis
+This way of forming a sentence from the package name and synopsis
should be considered as a heuristic and not a strict rule. There are
-some cases where it doesn't make sense to try to form a sentance.
+some cases where it doesn't make sense to try to form a sentence.
</sect1>
<sect1 id="bpp-pkg-desc">
~ianmdlvl / developers-reference.git / blobdiff