From: hertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Wed, 8 May 2002 15:34:10 +0000 (+0000)
Subject: - Indicated that the list of subsections is defined in the policy.
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=commitdiff_plain;h=f2f24c1fcc8ef55128a5933fe73639ecc255ff83

- Indicated that the list of subsections is defined in the policy.
  Closes: #123586
- Removed some cruft in `Announcing package uploads'.
- Document the testing scripts. Closes: #129445


git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1671 313b444b-1b9f-4f58-a734-7bb04f332e8d
---

diff --git a/common.ent b/common.ent
index 0e82133..9bdc400 100644
--- a/common.ent
+++ b/common.ent
@@ -68,6 +68,7 @@
 <!entity url-readme-non-us "ftp://&ftp-debian-org;/debian/README.non-US">
 
 <!entity url-testing-maint "http://ftp-master.debian.org/testing/">
+<!entity url-testing-faq "http://people.debian.org/~jules/testingfaq.html">
 
 <!entity us-upload-dir "/org/ftp.debian.org/incoming/">
 <!entity non-us-upload-dir "/org/non-us.debian.org/incoming/">
diff --git a/debian/changelog b/debian/changelog
index fa2a9fd..85be49f 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -49,7 +49,11 @@ developers-reference (3.0) unstable; urgency=low
     - extended "removing a package"; closes: #135560
     - Added best packaging practices chapter.
     - Added "Writing useful descriptions" as a first entry in that
-      chapter. Closes: #53109, #129848
+      chapter. closes: #53109, #129848
+    - Indicated that the list of subsections is defined in the policy.
+      closes: #123586
+    - Removed some cruft in `Announcing package uploads'.
+    - Document the testing scripts. closes: #129445
 
   * Antoine Hulin:
     - update French translation
diff --git a/developers-reference.sgml b/developers-reference.sgml
index b93f6b3..6609c1b 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.98 $">
+  <!entity cvs-rev "$Revision: 1.99 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -690,11 +690,11 @@ pages">.
 	<p>
 The sections <em>main</em>, <em>contrib</em>, and <em>non-free</em>
 are split into <em>subsections</em> to simplify the installation
-process and the maintenance of the archive.  Subsections are not
-formally defined, except perhaps the `base' subsection.
-Subsections simply exist to simplify the organization and browsing of
-available packages.  Please check the current Debian distribution to
-see which sections are available.
+process and the maintenance of the archive. Subsections simply exist to
+simplify the organization and browsing of available packages. The
+<url id="&url-debian-policy;" name="Debian Policy Manual"> gives
+the authoritative list of subsections.
+
 	<p>
 Note however that with the introduction of package pools (see the top-level
 <em>pool/</em> directory), the subsections in the form of subdirectories
@@ -760,15 +760,11 @@ distribution change from day-to-day. Since no special effort is done
 to make sure everything in this distribution is working properly, it is
 sometimes literally unstable.
 	<p>
-Packages get copied from <em>unstable</em> to <em>testing</em> if they
-satisfy certain criteria. To get into <em>testing</em> distribution, a
-package needs to be in the archive for two weeks and not have any
-release critical bugs. After that period, it will propagate into
-<em>testing</em> as soon as anything it depends on is also added. This
-process is automatic.  You can see some notes on this system as well
-as <tt>update_excuses</tt> (describing which packages are valid
-candidates, which are not, and why not) at <url
-id="&url-testing-maint;">.
+The testing distribution is generated automatically by taking
+packages from unstable if they satisfy certain criteria. Those
+criteria should ensure a good quality for packages within testing.
+The <ref id="testing-scripts"> are launched each day after the
+new packages have been installed.
 	<p>
 After a period of development, once the release manager deems fit, the
 <em>testing</em> distribution is frozen, meaning that the policies
@@ -879,6 +875,54 @@ real distribution directories use the <em>code names</em>, while
 symbolic links for <em>stable</em>, <em>testing</em>, and
 <em>unstable</em> point to the appropriate release directories.
 
+    <sect id="testing-scripts">
+	<heading>The testing scripts</heading>
+	<p>
+The testing scripts 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 conditionned:
+<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
+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;
+    <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>
+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
+to keep someone informed of the progression of his packages in testing.
+	<p>
+The <tt>update_excuses</tt> file does not always give the precise reason
+why the package is refused, one may have to find it by himself 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.
+	<p>
+Sometimes, some packages never enter testing 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.
+
 
    <chapt id="pkgs">Managing Packages
 	<p>
@@ -1307,10 +1351,6 @@ If a package is released with the <tt>Distribution:</tt> set to
 package is released with <tt>Distribution:</tt> set to `unstable',
 or `experimental', the announcement will be
 posted to &email-debian-devel-changes; instead.
-	<p>
-The <prgn>dupload</prgn> program is clever enough to determine
-where the announcement should go, and will automatically mail the
-announcement to the right list.  See <ref id="dupload">.
 
       <sect1 id="upload-notification">
 	<heading>Notification that a new package has been installed</heading>
@@ -2113,10 +2153,10 @@ even better.
 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
-provide all the required information that can help him decide whether
-or not he will install it.
+provide all the required information to let him decide whether
+to install the package.
 	    <p>
-For example, apart from the usual description that you will copy from the
+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
 by the author, you may also want to warn the user that the