also update list of authors

[developers-reference.git] / pkgs.dbk

diff --git a/pkgs.dbk b/pkgs.dbk
index 4730898462f5892c3db41740bf8abf040e34a785..d628f6664207ebe8af8668147393ffec5b24c39d 100644 (file)
--- a/pkgs.dbk
+++ b/pkgs.dbk
@@ -48,6 +48,12 @@ new package in order for the bug report to be automatically closed once the new
 package is installed in the archive (see <xref linkend="upload-bugfix"/> ).
 </para>
 <para>
 package is installed in the archive (see <xref linkend="upload-bugfix"/> ).
 </para>
 <para>

+If you think your package needs some explanations for the administrators of the
+NEW package queue, include them in your changelog, send to ftpmaster@debian.org
+a reply to the email you receive as a maintainer after your upload, or reply to
+the rejection email in case you are already re-uploading.
+</para>
+<para>

 When closing security bugs include CVE numbers as well as the Closes: #nnnnn.
 This is useful for the security team to track vulnerabilities.  If an upload is
 made to fix the bug before the advisory ID is known, it is encouraged to modify
 When closing security bugs include CVE numbers as well as the Closes: #nnnnn.
 This is useful for the security team to track vulnerabilities.  If an upload is
 made to fix the bug before the advisory ID is known, it is encouraged to modify


@@ -827,15 +833,13 @@ outstanding security problems, helping maintainers with security problems or
 fixing them themselves, sending security advisories, and maintaining
 <literal>security.debian.org</literal>.
 </para>
 fixing them themselves, sending security advisories, and maintaining
 <literal>security.debian.org</literal>.
 </para>

-<!-- information about the security database goes here once it's ready -->
-<!-- (mdz) -->

 <para>
 When you become aware of a security-related bug in a Debian package, whether or
 not you are the maintainer, collect pertinent information about the problem,
 and promptly contact the security team at
 &email-security-team; as soon as possible.  <emphasis
 <para>
 When you become aware of a security-related bug in a Debian package, whether or
 not you are the maintainer, collect pertinent information about the problem,
 and promptly contact the security team at
 &email-security-team; as soon as possible.  <emphasis

-role="strong">DO NOT UPLOAD</emphasis> any packages for <literal>stable</literal>;
- the security team will do that.  Useful information includes, for example:
+role="strong">DO NOT UPLOAD</emphasis> any packages for <literal>stable</literal>
+without contacting the team.  Useful information includes, for example:

 </para>
 <itemizedlist>
 <listitem>
 </para>
 <itemizedlist>
 <listitem>


@@ -870,6 +874,29 @@ linkend="bug-security-advisories"/> )
 </para>
 </listitem>
 </itemizedlist>
 </para>
 </listitem>
 </itemizedlist>

+<para>As the maintainer of the package, you have the responsibility to
+maintain it, even in the stable release. You are in the best position
+to evaluate patches and test updated packages, so please see the sections
+below on how to prepare packages for the Security Team to handle.</para>
+
+<section id="bug-security-tracker">
+<title>The Security Tracker</title>
+<para>
+The security team maintains a central database, the
+<ulink url="http://security-tracker.debian.net/">Debian Security Tracker</ulink>.
+This contains all public information that is known about security issues:
+which packages and versions are affected or fixed, and thus whether stable,
+testing and/or unstable are vulnerable. Information that is still confidential
+is not added to the tracker.
+</para>
+<para>
+You can search it for a specific issue, but also on package name. Look
+for your package to see which issues are still open. If you can, please provide
+more information about those issues, or help to address them in your package.
+Instructions are on the tracker web pages.
+</para>
+</section>
+

 <section id="bug-security-confidentiality">
 <title>Confidentiality</title>
 <para>
 <section id="bug-security-confidentiality">
 <title>Confidentiality</title>
 <para>


@@ -939,6 +966,10 @@ There are two reasons for releasing information even though secrecy is
 requested: the problem has been known for a while, or the problem or exploit
 has become public.
 </para>
 requested: the problem has been known for a while, or the problem or exploit
 has become public.
 </para>

+<para>
+The Security Team has a PGP-key to enable encrypted communication about
+sensitive issues. See the <ulink url="http://www.debian.org/security/faq.en.html#contact">Security Team FAQ</ulink> for details.
+</para>

 </section>
 
 <section id="bug-security-advisories">
 </section>
 
 <section id="bug-security-advisories">


@@ -1075,7 +1106,8 @@ Be sure to verify the following items:
 <itemizedlist>
 <listitem>
 <para>
 <itemizedlist>
 <listitem>
 <para>

-Target the right distribution in your <filename>debian/changelog</filename>.
+<emphasis role="strong">Target the right distribution</emphasis>
+in your <filename>debian/changelog</filename>.

 For <literal>stable</literal> this is <literal>stable-security</literal> and
 for testing this is <literal>testing-security</literal>, and for the previous
 stable release, this is <literal>oldstable-security</literal>.  Do not target
 For <literal>stable</literal> this is <literal>stable-security</literal> and
 for testing this is <literal>testing-security</literal>, and for the previous
 stable release, this is <literal>oldstable-security</literal>.  Do not target


@@ -1085,67 +1117,58 @@ stable release, this is <literal>oldstable-security</literal>.  Do not target
 </listitem>
 <listitem>
 <para>
 </listitem>
 <listitem>
 <para>

-The upload should have urgency=high.
+The upload should have <emphasis role="strong">urgency=high</emphasis>.

 </para>
 </listitem>
 <listitem>
 <para>
 Make descriptive, meaningful changelog entries.  Others will rely on them to
 </para>
 </listitem>
 <listitem>
 <para>
 Make descriptive, meaningful changelog entries.  Others will rely on them to

-determine whether a particular bug was fixed.  Always include an external
-reference, preferably a CVE identifier, so that it can be cross-referenced.
-Include the same information in the changelog for <literal>unstable</literal>,
-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.
+determine whether a particular bug was fixed.  Add <literal>closes:</literal>
+statements for any <emphasis role="strong">Debian bugs</emphasis> filed.
+Always include an external reference, preferably a <emphasis role="strong">CVE
+identifier</emphasis>, so that it can be cross-referenced. However, if a CVE
+identifier has not yet been assigned, do not wait for it but continue the
+process. The identifier can be cross-referenced later.

 </para>
 </listitem>
 <listitem>
 <para>
 </para>
 </listitem>
 <listitem>
 <para>

-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 <literal>dpkg --compare-versions</literal>.  Be careful not to
-re-use a version number that you have already used for a previous upload.  For
-<literal>testing</literal>, there must be a higher version in
-<literal>unstable</literal>.  If there is none yet (for example, if
-<literal>testing</literal> and <literal>unstable</literal> have the same
-version) you must upload a new version to <literal>unstable</literal> first.
-</para>
-</listitem>
-<listitem>
-<para>
-Do not make source-only uploads if your package has any binary-all packages (do
-not use the <literal>-S</literal> option to
-<command>dpkg-buildpackage</command>).  The <command>buildd</command>
-infrastructure will not build those.  This point applies to normal package
-uploads as well.
+Make sure the <emphasis role="strong">version number</emphasis> is proper. 
+It must be greater than the current package, but less than package versions in
+later distributions.  If in doubt, test it with <literal>dpkg
+--compare-versions</literal>.  Be careful not to re-use a version number that
+you have already used for a previous upload, or one that conflicts with a
+binNMU. The convention is to append
+<literal>+</literal><replaceable>codename</replaceable><literal>1</literal>, e.g.
+<literal>1:2.4.3-4+etch1</literal>, of course increasing 1 for any subsequent
+uploads.

 </para>
 </listitem>
 <listitem>
 <para>
 Unless the upstream source has been uploaded to <literal>security.debian.org
 </para>
 </listitem>
 <listitem>
 <para>
 Unless the upstream source has been uploaded to <literal>security.debian.org

-</literal> before (by a previous security update), build the upload with full
-upstream source (<literal>dpkg-buildpackage -sa</literal>).  If there has been
-a previous upload to <literal>security.debian.org</literal> with the same
-upstream version, you may upload without upstream source (<literal>
-dpkg-buildpackage -sd</literal>).
+</literal> before (by a previous security update), build the upload <emphasis
+role="strong">with full upstream source</emphasis> (<literal>dpkg-buildpackage
+-sa</literal>).  If there has been a previous upload to
+<literal>security.debian.org</literal> with the same upstream version, you may
+upload without upstream source (<literal> dpkg-buildpackage -sd</literal>).

 </para>
 </listitem>
 <listitem>
 <para>
 </para>
 </listitem>
 <listitem>
 <para>

-Be sure to use the exact same <filename>*.orig.tar.gz</filename> as used in the
+Be sure to use the <emphasis role="strong">exact same
+<filename>*.orig.tar.gz</filename></emphasis> as used in the

 normal archive, otherwise it is not possible to move the security fix into the
 main archives later.
 </para>
 </listitem>
 <listitem>
 <para>
 normal archive, otherwise it is not possible to move the security fix into the
 main archives later.
 </para>
 </listitem>
 <listitem>
 <para>

-Build the package on a clean system which only has packages installed from the
-distribution you are building for.  If you do not have such a system yourself,
-you can use a debian.org machine (see <xref linkend="server-machines"/> ) or
-setup a chroot (see <xref linkend="pbuilder"/> and <xref
-linkend="debootstrap"/> ).
+Build the package on a <emphasis role="strong">clean system</emphasis> which only
+has packages installed from the distribution you are building for. If you do not
+have such a system yourself, you can use a debian.org machine (see
+<xref linkend="server-machines"/> ) or setup a chroot (see
+<xref linkend="pbuilder"/> and <xref linkend="debootstrap"/> ).

 </para>
 </listitem>
 </itemizedlist>
 </para>
 </listitem>
 </itemizedlist>


@@ -1178,7 +1201,7 @@ archives.  For security uploads, the place to upload to is
 </para>
 <para>
 Once an upload to the security queue has been accepted, the package will
 </para>
 <para>
 Once an upload to the security queue has been accepted, the package will

-automatically be rebuilt for all architectures and stored for verification by
+automatically be built for all architectures and stored for verification by

 the security team.
 </para>
 <para>
 the security team.
 </para>
 <para>


@@ -1321,6 +1344,10 @@ should either be reassigned to another package in the case where the actual
 code has evolved into another package (e.g.  <literal>libfoo12</literal> was
 removed because <literal>libfoo13</literal> supersedes it) or closed if the
 software is simply no longer part of Debian.
 code has evolved into another package (e.g.  <literal>libfoo12</literal> was
 removed because <literal>libfoo13</literal> supersedes it) or closed if the
 software is simply no longer part of Debian.

+When closing the bugs,
+to avoid marking the bugs as fixed in versions of the packages
+in previous Debian releases, they should be marked as fixed
+in the version <literal>&lt;most-recent-version-ever-in-Debian&gt;+rm</literal>.

 </para>
 <section id="s5.9.2.1">
 <title>Removing packages from <filename>Incoming</filename></title>
 </para>
 <section id="s5.9.2.1">
 <title>Removing packages from <filename>Incoming</filename></title>


@@ -1764,9 +1791,17 @@ flavor of Debian built with <command>gcc</command> bounds checking).  It will
 also enable Debian to recompile entire distributions quickly.
 </para>
 <para>
 also enable Debian to recompile entire distributions quickly.
 </para>
 <para>

-The buildds admins of each arch can be contacted at the mail address
-<literal><replaceable>arch</replaceable>@buildd.debian.org</literal>.
+The wanna-build team, in charge of the buildds,
+can be reached at <literal>debian-wb-team@lists.debian.org</literal>.
+To determine who (wanna-build team, release team) and how (mail, BTS)
+to contact, refer to <ulink url="&url-wb-team;"></ulink>.

 </para>
 </para>

+
+<para>
+When requesting binNMUs or give-backs (retries after a failed build),
+please use the format described at <ulink url="&url-release-wb;"/>.
+</para>
+

 </section>
 
 </section>
 </section>
 
 </section>


@@ -1966,18 +2001,33 @@ upload.  The first line of this entry must explicitely mention that this upload
 </screen>
 
 <para>
 </screen>
 
 <para>

-The version must be the version of the last maintainer upload, plus
+The way to version NMUs differs for native and non-native packages.
+</para>
+<para>
+If the package is a native package (without a debian revision in the version number), 
+the version must be the version of the last maintainer upload, plus

 <literal>+nmu<replaceable>X</replaceable></literal>, where
 <literal>+nmu<replaceable>X</replaceable></literal>, where

-<replaceable>X</replaceable> is a counter starting at <literal>1</literal>.  If
+<replaceable>X</replaceable> is a counter starting at <literal>1</literal>.
+If

 the last upload was also an NMU, the counter should be increased.  For example,
 the last upload was also an NMU, the counter should be increased.  For example,

-if the current version is <literal>1.5-1</literal>, then an NMU would get
-version <literal>1.5-1+nmu1</literal>.  If the current version is
-<literal>1.5+nmu3</literal> (a native package which has already been NMUed), the
-NMU would get version <literal>1.5+nmu4</literal>.  If a new upstream version
+if the current version is <literal>1.5</literal>, then an NMU would get
+version <literal>1.5+nmu1</literal>.
+</para>
+<para>
+If the package is a not a native package, you should add a minor version number
+to the debian revision part of the version number (the portion after the last
+hyphen). This extra number must start at 1.  For example,
+if the current version is <literal>1.5-2</literal>, then an NMU would get
+version <literal>1.5-2.1</literal>. If a new upstream version

 is packaged in the NMU, the debian revision is set to <literal>0</literal>, for
 is packaged in the NMU, the debian revision is set to <literal>0</literal>, for

-example <literal>1.6-0+nmu1</literal>.
+example <literal>1.6-0.1</literal>.
+</para>
+<para>
+In both cases, if the last upload was also an NMU, the counter should
+be increased. For example, if the current version is
+<literal>1.5+nmu3</literal> (a native package which has already been
+NMUed), the NMU would get version <literal>1.5+nmu4</literal>.  .

 </para>
 </para>

-

 <para>
 A special versioning scheme is needed to avoid disrupting the maintainer's
 work, since using an integer for the Debian revision will potentially
 <para>
 A special versioning scheme is needed to avoid disrupting the maintainer's
 work, since using an integer for the Debian revision will potentially