X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=6ffa1bac9fcb450ea0d876a5b7e52cc1d1e00199;hb=a2c790cb659d425284a524ce8dfd748dbc84f511;hp=dea325efb3d5bce8ef4e4639b8066c435aa5b040;hpb=e22ed8f4833f5a95c8b09504c2b19e93709c1120;p=developers-reference.git

diff --git a/developers-reference.sgml b/developers-reference.sgml
index dea325e..6ffa1ba 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.133 $">
+  <!entity cvs-rev "$Revision: 1.144 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -32,15 +32,18 @@
 
       <title>Debian Developer's Reference
       <author>Adam Di Carlo, current maintainer <email>aph@debian.org</email>
+      <author>Raphaël Hertzog, co-maintainer <email>hertzog@debian.org</email>
       <author>Christian Schwarz <email>schwarz@debian.org</email>
       <author>Ian Jackson <email>ijackson@gnu.ai.mit.edu</email>
       <version>ver. &version;, &date-en;
 
       <copyright>
 	<copyrightsummary>
-copyright &copy;1998&mdash;2002 Adam Di Carlo</copyrightsummary>
+copyright &copy; 1998&mdash;2002 Adam Di Carlo</copyrightsummary>
 	<copyrightsummary>
-copyright &copy;1997, 1998 Christian Schwarz</copyrightsummary>
+copyright &copy; 2002 Raphaël Hertzog</copyrightsummary>
+	<copyrightsummary>
+copyright &copy; 1997, 1998 Christian Schwarz</copyrightsummary>
 	<p>
 This manual is free software; you may redistribute it and/or modify it
 under the terms of the GNU General Public License as published by the
@@ -363,18 +366,23 @@ need, always try not to fork from the upstream sources.
 
       <sect id="rc-bugs">Managing release-critical bugs
         <p>
-Release-critical bugs (RCB) are all bugs that have severity
-<em>critical</em>, <em>grave</em> or <em>serious</em>.
+Generally you should deal with bug reports on your packages as described in
+<ref id="bug-handling">. However, there's a special category of bugs that
+you need to take care of -- the so-called release-critical bugs (RC bugs).
+All bug reports that have severity <em>critical</em>, <em>grave</em> or
+<em>serious</em> are considered to have an impact on whether the package can
+be released in the next stable release of Debian.
 Those bugs can delay the Debian release
 and/or can justify the removal of a package at freeze time. That's why
-these bugs need to be corrected as quickly as possible.  You must be
-aware that some developers who are part of the <url
-id="&url-debian-qa;" name="Debian Quality Assurance"> effort are
-following those bugs and try to help you whenever they are able. But if
-you can't fix such bugs within 2 weeks, you should either ask for help
+these bugs need to be corrected as quickly as possible.
+	<p>
+Developers who are part of the <url id="&url-debian-qa;"
+name="Quality Assurance"> group are following all such bugs, and trying
+to help whenever possible. If, for any reason, you aren't able fix an
+RC bug in a package of yours within 2 weeks, you should either ask for help
 by sending a mail to the Quality Assurance (QA) group
 &email-debian-qa;, or explain your difficulties and present a plan to fix
-them by sending a mail to the proper bug report. Otherwise, people
+them by sending a mail to the bug report. Otherwise, people
 from the QA group may want to do a Non-Maintainer Upload (see
 <ref id="nmu">) after trying to contact you (they might not wait as long as
 usual before they do their NMU if they have seen no recent activity from you
@@ -389,7 +397,7 @@ the following steps:
 	    <item>
 Orphan all your packages, as described in <ref id="orphaning">.
 	    <item>
-Send an email about how you are leaving the project to
+Send an email about why you are leaving the project to
 &email-debian-private;.
 	    <item>
 Notify the Debian key ring maintainers that you are leaving by
@@ -1112,14 +1120,15 @@ if they respect themselves all the criteria);
 The scripts are generating some output files to explain why some packages
 are kept out of testing. They are available at <url
 id="&url-testing-maint;">. Alternatively, it is possible to use
-the <prgn>grep-excuses</prgn> program part of the
-<package>devscripts</package> package. It can be easily put in a crontab
+the <prgn>grep-excuses</prgn> program which is in the
+<package>devscripts</package> package. It can be easily put in a
+<manref name="crontab" section="5">
 to keep someone informed of the progression of his packages in <em>testing</em>.
 	<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 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
+id="&url-testing-maint;" name="testing overview"> gives some more information
 about the usual problems which may be causing such troubles.
 	<p>
 Sometimes, some packages never enter <em>testing</em> because the set of
@@ -1170,7 +1179,7 @@ recompiled on most of the architectures.
 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 than the maintainer. Each mail
+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
 you want to receive.
@@ -2291,7 +2300,7 @@ enhanced to support cross-compiling.
         <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
+almost always 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>
@@ -2523,6 +2532,12 @@ 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.debian.org</email>).
 	<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.debian.org</email>. If you're fixing a bug by
+changing and uploading the package, you can automate bug closing as
+described in <ref id="upload-bugfix">.
+	<p>
 You should <em>never</em> close bugs via the bug server <tt>close</tt>
 command sent to &email-bts-control;.  If you do so, the original
 submitter will not receive any information about why the bug was
@@ -2532,15 +2547,17 @@ closed.
 	<p>
 As a package maintainer, you will often find bugs in other packages or
 have bugs reported against your packages which are actually bugs in
-other packages.  The <url id="&url-bts-control;" name="BTS
-instructions"> document the technical operations of the BTS, such as
-how to file, reassign, merge, and tag bugs.  This section contains
+other packages. The bug tracking system's features interesting to developers
+are described in the <url id="&url-bts-devel;" name="BTS documentation for
+Debian developers">. Operations such as reassigning, merging, and tagging
+bug reports are described in the <url id="&url-bts-control;" name="BTS
+control bot documentation">. This section contains
 some guidelines for managing your own bugs, based on the collective
 Debian developer experience.
         <p>
 Filing bugs for problems that  you find in other packages is one of
 the "civic obligations" of maintainership, see <ref id="submit-bug">
-for details. However handling the bugs on your own packages is
+for details. However, handling the bugs in your own packages is
 even more important.
         <p>
 Here's a list of steps that you may follow to handle a bug report:
@@ -2631,13 +2648,18 @@ Useful information includes, for example:
 
 <list compact>
   <item>What versions of the package are known to be affected by the
-  bug.
-
-  <item>The nature of the exposure (root compromise, user compromise,
-  remote/local attack)
+  bug.  Check each version that is present in a supported Debian
+  release, as well as testing and unstable.
 
   <item>The nature of the fix, if any is available (patches are
   especially helpful)
+
+  <item>Any fixed packages that you have prepared yourself (send only
+  the <tt>.diff.gz</tt> and <tt>.dsc</tt> files)
+
+  <item>Any information needed for the advisory (see <ref
+  id="bug-security-advisories">)
+
 </list>
 
         <sect2 id="bug-security-confidentiality">Confidentiality
@@ -2712,6 +2734,9 @@ text. Information that should be in an advisory includes:
   <item>Version numbers of affected packages
   <item>Version numbers of fixed packages
   <item>Information on where to obtain the updated packages
+  <item>References to upstream advisories, <url
+  id="http://cve.mitre.org" name="CVE"> identifiers, and any other
+  information useful in cross-referencing the vulnerability
 </list>
 
          <sect2 id="bug-security-building">
@@ -2746,13 +2771,19 @@ changes.  If you have an exploit available, try it and see if it
 indeed succeeds on the unpatched package and fails on the fixed
 package.  Test other, normal actions as well, as sometimes a security
 fix can break seemingly unrelated features in subtle ways.
+<p>
+Review and test your changes as much as possible.  Check the
+differences from the previous version repeatedly
+(<prgn>interdiff</prgn> and <prgn>debdiff</prgn> are useful tools for
+this).
 
 When packaging the fix, keep the following points in mind:
 
 <list>
     <item>Make sure you target the right distribution in your
     <file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
-    testing this is <tt>testing-security</tt>. Do not target
+    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!
 
     <item>Make sure the version number is proper. It must be greater
@@ -2769,8 +2800,11 @@ When packaging the fix, keep the following points in mind:
     not build those. This point applies to normal package uploads as
     well.
 
-    <item>Always build with full source (use the <tt>-sa</tt> option
-    for <prgn>dpkg-buildpackage</prgn>).
+    <item>If the upstream source has been uploaded to
+    security.debian.org before (by a previous security update), build
+    the upload without the upstream source (<tt>dpkg-buildpackage
+    -sd</tt>).  Otherwise, build with full source
+    (<tt>dpkg-buildpackage -sa</tt>).
 
     <item>Be sure to use the exact same <file>*.orig.tar.gz</file> as used in the
     normal archive, otherwise it is not possible to move the security
@@ -2791,6 +2825,14 @@ 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
+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
+is already installed into the archive, the security update will be
+rejected by the archive system.  That way, the stable distribution
+will end up without a security update for this package instead.
+<p>
 Once you have created and tested the new package and it has been
 approved by the security team, it needs to be uploaded so that it can
 be installed in the archives. For security uploads, the place to
@@ -2822,10 +2864,11 @@ been accepted into the Debian archive.  Therefore, once you get
 notification that your updated package has been installed into the
 archive, you can and should close the bug in the BTS.
 	<p>
-If you are using a new version of <package>dpkg-dev</package> and you do
-your changelog entry properly, the archive maintenance software will close
-the bugs automatically.  All you have to do is follow a certain syntax in
-your <file>debian/changelog</file> file:
+However, it's possible to avoid having to manually close bugs after the
+upload -- just list the fixed bugs in your <file>debian/changelog</file>
+file, following a certain syntax, and the archive maintenance software
+will close the bugs for you. For example:
+
 <example>
 acme-cannon (3.1415) unstable; urgency=low
 
@@ -2845,21 +2888,20 @@ The author prefers the <tt>closes: #<var>XXX</var></tt> syntax, as
 one of the most concise and easiest to integrate with the text of the
 <file>changelog</file>.
 	<p>
-If you want to close bugs the old fashioned, manual way, it is usually
-sufficient to mail the <file>.changes</file> file to
+If you happen to mistype a bug number or forget one in the changelog file,
+don't hesitate to undo any damage the error caused. To reopen wrongly closed
+bugs, send an <tt>reopen <var>XXX</var></tt> command in the bug tracking
+system's control bot. To close any remaining bugs that were fixed by your
+upload, email the <file>.changes</file> file to
 <email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your
 bug number.
+	<p>
+Bear in mind that it is not obligatory to close bugs using the changelog
+like described above -- if you simply want to close bugs that don't have
+anything to do with an upload of yours, do it simply by emailing an
+explanation to <email>XXX-done@bugs.debian.org</email>.
 
 
-      <sect1 id="lintian-reports">Lintian reports
-	<p>
-You should periodically get the new <package>lintian</package> from
-`unstable' and check over all your packages.  Alternatively you can
-check for your maintainer email address at the <url id="&url-lintian;"
-name="online lintian report">.  That report, which is updated
-automatically, contains <prgn>lintian</prgn> reports against the
-latest version of the distribution (usually from 'unstable') using the
-latest <package>lintian</package>.
 
 
   <chapt id="best-pkging-practices">
@@ -2882,7 +2924,7 @@ even better.
 	<p>
 To help you in your packaging effort, you can use helper scripts.
 The best scripts available are provided by <package>debhelper</package>.
-With <prgn>dh_make</prgn> (package <package>dh-make</package>), you can
+With <prgn>dh_make</prgn> (see <ref id="dh-make">), you can
 generate in a few seconds a package that is mostly ready. However that
 apparent simplicity is hiding many things done by the helper scripts.
 You have to know what is done by them, that's why you are strongly
@@ -2949,36 +2991,34 @@ hand crafted rules file.
 
 	<sect1 id="handling-debconf-translations">Handling debconf translations
 	<p>
-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, 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>
-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.
-
+Like porters, translators have a difficult task.  They work on many
+packages and must collaborate with many different
+maintainers. Moreover, most of the time, they are not native English
+speaker, so you may need to be particularly patient with them.
+	<p>
+The goal of <package>debconf</package> was to make packages
+configuration easier for maintainers and for users.  Originally,
+translation of debconf templates was handled with
+<prgn>debconf-mergetemplate</prgn> from the
+<package>debconf-utils</package> package.  Since
+<package>debconf</package> version 1.2.9,
+<prgn>debconf-mergetemplate</prgn> has been deprecated and a new
+system called <package>po-debconf</package> is strongly
+encouraged. This new method is much easier both for the maintainer and
+the translators, and you should upgrade your packages to use it.
+Transition scripts are provided.
+	<p>
+Using <package>po-debconf</package>, the translation is stored in
+<file>po</file> files (drawing from <prgn>gettext</prgn> translation
+techniques).  Special template files contain the original messages and
+mark which fields should be translated. When you change the original,
+calling the <prgn>debconf-updatepo</prgn> script with no argument is
+enough to mark the translation as needing attention from the
+translators. Then, at build time, use the
+<prgn>dh_installdebconf</prgn> program take care of all the needed
+magic to add the template along with the up-to-date translations into
+the binary packages.  Refer to the <manref name="po-debconf"
+section="7"> manual page for details.
 
     <sect id="specific-practices">
 	<heading>Specific packaging practices</heading>
@@ -3167,7 +3207,7 @@ list.
 Even though there is a dedicated group of people for Quality
 Assurance, QA duties are not reserved solely for them. You can
 participate in this effort by keeping your packages as bug-free as
-possible, and as lintian-clean (see <ref id="lintian-reports">) as
+possible, and as lintian-clean (see <ref id="lintian">) as
 possible. If you do not find that possible, then you should consider
 orphaning some of your packages (see <ref
 id="orphaning">). Alternatively, you may ask the help of other people
@@ -3282,7 +3322,7 @@ the package meets minimum Debian standards.  That implies that you
 must build and test the package on your own system before uploading.
 	<p>
 You can not simply upload a binary <file>.deb</file> from the sponsoree. In
-theory, you should only ask only for the diff file and the location of the
+theory, you should only ask 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 they haven't
@@ -3296,7 +3336,7 @@ means being a mentor.
 	<p>
 Once the package meets Debian standards, build the package with
 <example>dpkg-buildpackage -us -uc</example> and sign it
-with <example>debsign -m &lt;your-email-addr&gt; &lt;changes-file&gt;</example>
+with <example>debsign -m"<var>FULLNAME</var> <var>email-addr</var>" <var>changes-file</var></example>
 before uploading it to the incoming directory.
 	<p>
 The Maintainer field of the <file>control</file> file and the
@@ -3360,9 +3400,20 @@ they are required for any Debian maintainer.
 	<p>
 <package>Lintian</package> dissects Debian packages and reports bugs
 and policy violations. It contains automated checks for many aspects
-of Debian policy as well as some checks for common errors.  The use of
-<package>lintian</package> has already been discussed in <ref
-id="upload-checking"> and <ref id="lintian-reports">.
+of Debian policy as well as some checks for common errors.
+	<p>
+You should periodically get the newest <package>lintian</package> from
+`unstable' and check over all your packages. Notice that the <tt>-i</tt>
+option provides detailed explanations of what each error or warning means,
+what is its basis in Policy, and commonly how you can fix the problem.
+	<p>
+Refer to <ref id="upload-checking"> for more information on how and when
+to use Lintian.
+	<p>
+You can also see a summary of all problems reported by Lintian on your
+packages at <url id="&url-lintian;">. Those reports contain the latest
+<prgn>lintian</prgn> output on the whole development distribution
+("unstable").
 
 
       <sect id="debconf">
@@ -3420,6 +3471,21 @@ favor of <package>debhelper</package>.  However, it's not a bug to use
 <package>debmake</package>.
 
 
+      <sect id="dh-make">
+	<heading><package>dh-make</package>
+	<p>
+The <package/dh-make/ package contains <prgn/dh_make/, a program that
+creates a skeleton of files necessary to build a Debian package out of
+a source tree. As the name suggests, <prgn/dh_make/ is a rewrite of
+<package/debmake/ and its template files use dh_* programs from
+<package/debhelper/.
+	<p>
+While the rules files generated by <prgn/dh_make/ are in general a
+sufficient basis for a working package, they are still just the groundwork:
+the burden still lies on the maintainer to finely tune the generated files
+and make the package entirely functional and Policy-compliant.
+
+
       <sect id="yada">
 	<heading><package>yada</package>
 	<p>