update for next release

[developers-reference.git] / developers-reference.sgml

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 2749638dff44270226d622ae07432a2f9f846749..a1f44f9627b8c52c12b77f32636ff9c5e15d51c0 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->

-  <!entity cvs-rev "$Revision: 1.200 $">
+  <!entity cvs-rev "$Revision: 1.207 $">

   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--


@@ -851,7 +851,7 @@ with checksums (<prgn>md5sums</prgn>) and some additional info about
 the package (maintainer, version, etc.).
 
 
 the package (maintainer, version, etc.).
 
 

-      <sect1>Distribution directories
+      <sect1>Distributions

        <p>
 The directory system described in the previous chapter is itself
 contained within <em>distribution directories</em>.  Each
        <p>
 The directory system described in the previous chapter is itself
 contained within <em>distribution directories</em>.  Each


@@ -927,6 +927,62 @@ Note that development under <em>unstable</em> continues during the
 freeze period, since the <em>unstable</em> distribution remains in
 place in parallel with <em>testing</em>.
 
 freeze period, since the <em>unstable</em> distribution remains in
 place in parallel with <em>testing</em>.
 

+    <sect2 id="testing">
+       <heading>More information about the testing distribution</heading>
+       <p>
+The scripts that update the <em>testing</em> distribution are run each
+day after the installation of the updated packages. They generate the
+<file>Packages</file> files for 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 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 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>
+It must have less release-critical bugs than the version available
+in <em>testing</em>;
+    <item>
+It must be available on all architectures on which it has been
+previously built. <ref id="madison"> may be of interest to
+check that information;
+    <item>
+It must not break any dependency of a package that is already available
+in <em>testing</em>;
+    <item>
+The packages on which it depends must either be available in <em>testing</em>
+or they must be accepted into <em>testing</em> at the same time (and they will
+if they respect themselves all the criteria);
+</list>
+       <p>
+To find out whether a package is progressing into testing or not, see the
+testing script output on the <url name="web page of the testing distribution"
+id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn>
+which is in the <package>devscripts</package> package. This utility can
+easily be used in a <manref name="crontab" section="5"> to keep one
+informed of the progression of their packages into <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-maint;" name="testing web page"> 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
+inter-relationship is too complicated and can not be sorted out
+by the scripts. In that case, the release manager must be
+contacted, and he will force the inclusion of the packages.
+       <p>
+In general, please refer to the <url name="testing web page"
+id="&url-testing-maint;"> for more information. It also includes
+answers to some of the frequently asked questions.
+
+

        <sect2 id="experimental">Experimental
          <p>
 The <em>experimental</em> distribution is a special distribution.
        <sect2 id="experimental">Experimental
          <p>
 The <em>experimental</em> distribution is a special distribution.


@@ -1123,60 +1179,6 @@ easily upload a package in one of the delayed directories:
 <example>DELAY=5 dupload --to delayed &lt;changes-file&gt;</example>
 
 
 <example>DELAY=5 dupload --to delayed &lt;changes-file&gt;</example>
 
 

-    <sect id="testing">
-       <heading>The "testing" distribution</heading>
-       <p>
-The scripts that update the <em>testing</em> distribution are run each day
-after the installation of the
-updated packages. They generate the <file>Packages</file> files for
-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 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 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>
-It must have less release-critical bugs than the version available
-in <em>testing</em>;
-    <item>
-It must be available on all architectures on which it has been
-previously built. <ref id="madison"> may be of interest to
-check that information;
-    <item>
-It must not break any dependency of a package that is already available
-in <em>testing</em>;
-    <item>
-The packages on which it depends must either be available in <em>testing</em>
-or they must be accepted into <em>testing</em> at the same time (and they will
-if they respect themselves all the criteria);
-</list>
-       <p>
-To find out whether a package is progressing into testing or not, see the
-testing script output on the <url name="web page of the testing distribution"
-id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn>
-which is in the <package>devscripts</package> package. This utility can
-easily be used in a <manref name="crontab" section="5"> to keep one
-informed of the progression of their packages into <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-maint;" name="testing web page"> 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
-inter-relationship is too complicated and can not be sorted out
-by the scripts. In that case, the release manager must be
-contacted, and he will force the inclusion of the packages.
-       <p>
-In general, please refer to the <url name="testing web page"
-id="&url-testing-maint;"> for more information. It also includes
-answers to some of the frequently asked questions.
-

 
     <sect id="pkg-info">Package information
        <p>
 
     <sect id="pkg-info">Package information
        <p>


@@ -1662,7 +1664,8 @@ because the dependencies of the package may vary with the distribution.
 In particular, it never makes sense to combine the <em>experimental</em>
 distribution with anything else (see <ref id="experimental">).
 
 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
          <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


@@ -1701,7 +1704,8 @@ verbose, if necessary) in your changelog entries for uploads to
 <em>stable</em>, because otherwise the package won't be considered for
 inclusion.
 
 <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
          <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


@@ -1731,6 +1735,10 @@ to transfer the files, place them into &us-upload-dir;;
 if you use anonymous FTP to upload, place them into
 &upload-queue;.
          <p>
 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 supported 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
 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


@@ -1970,7 +1978,8 @@ maintainer address.
 
       <sect1 id="bug-answering">Responding to bugs
        <p>
 
       <sect1 id="bug-answering">Responding to bugs
        <p>

-Make sure that any discussion you have about bugs are sent both to
+When responding to bugs, 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
 mail and you don't remember the submitter email address, you can
 the original submitter of the bug, and 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


@@ -1979,6 +1988,9 @@ 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>
 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
 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


@@ -2623,7 +2635,7 @@ Make sure your debian/rules contains separate ``binary-arch'' and
 ``binary-indep'' targets, as the Debian Policy Manual requires.
 Make sure that both targets work independently, that is, that you can
 call the target without having called the other before. To test this,
 ``binary-indep'' targets, as the Debian Policy Manual requires.
 Make sure that both targets work independently, that is, that you can
 call the target without having called the other before. To test this,

-try to run <tt>dpkg-buildpackage -b</tt>.
+try to run <tt>dpkg-buildpackage -B</tt>.

          </enumlist>
 
 
          </enumlist>
 
 


@@ -3579,7 +3591,7 @@ interaction. This will enable non-interactive installations in the
 future.
        <p>
 Debconf is a great tool but it is often poorly used.   Many common mistakes
 future.
        <p>
 Debconf is a great tool but it is often poorly used.   Many common mistakes

-are listed in the <manref name="debconf-devel" section="8"> man page. 
+are listed in the <manref name="debconf-devel" section="7"> man page. 

 It is something that you must read if you decide to use debconf.
       </sect>
 
 It is something that you must read if you decide to use debconf.
       </sect>
 


@@ -4042,9 +4054,8 @@ that need to be made.  It often takes several rounds of back-and-forth
 email before the package is in acceptable shape.  Being a sponsor
 means being a mentor.
        <p>
 email before the package is in acceptable shape.  Being a sponsor
 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"<var>FULLNAME</var> <var>email-addr</var>" <var>changes-file</var></example>
+Once the package meets Debian standards, build and sign it with                           
+<example>dpkg-buildpackage -k<var>KEY-ID</var></example>                                  

 before uploading it to the incoming directory.
        <p>
 The Maintainer field of the <file>control</file> file and the
 before uploading it to the incoming directory.
        <p>
 The Maintainer field of the <file>control</file> file and the