No multiple distributions in Distribution, update footnote

Document that the Debian archive software does not allow listing
multiple distributions in the *.changes file.  Update the footnote
listing Distribution field values to list the ones currently used,
remove frozen, remove the discussion of testing, and add a mention
of stable-security and testing-security.

Based on wording proposed by Colin Watson and Adam D. Barratt.

diff --git a/policy.sgml b/policy.sgml
index 36f51aa795d18c3c649727a8349741f745d8ddc4..969b5c72d09c7295ea0677ea2956a20feb0a0365 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -3062,69 +3062,58 @@ Package: libc6
            distribution(s) where this version of the package should
            be installed.  Valid distributions are determined by the
            archive maintainers.<footnote>
-               Current distribution names are:
+             Current distribution names in the Debian archive used in
+             <file>.changes</file> files are:
                <taglist compact="compact">
-                 <tag><em>stable</em></tag>
-                 <item>
-                     This is the current "released" version of Debian
-                     GNU/Linux.  Once the distribution is
-                     <em>stable</em> only security fixes and other
-                     major bug fixes are allowed. When changes are
-                     made to this distribution, the release number is
-                     increased (for example: 2.2r1 becomes 2.2r2 then
-                     2.2r3, etc).
-                 </item>
-
                  <tag><em>unstable</em></tag>
                  <item>
-                     This distribution value refers to the
-                     <em>developmental</em> part of the Debian
-                     distribution tree. New packages, new upstream
-                     versions of packages and bug fixes go into the
-                     <em>unstable</em> directory tree. Download from
-                     this distribution at your own risk.
+                   This distribution value refers to the
+                   <em>developmental</em> part of the Debian distribution
+                   tree.  Most new packages, new upstream versions of
+                   packages and bug fixes go into the <em>unstable</em>
+                   directory tree.
                  </item>
 
-                 <tag><em>testing</em></tag>
+                 <tag><em>experimental</em></tag>
                  <item>
-                     This distribution value refers to the
-                     <em>testing</em> part of the Debian distribution
-                     tree.  It receives its packages from the
-                     unstable distribution after a short time lag to
-                     ensure that there are no major issues with the
-                     unstable packages.  It is less prone to breakage
-                     than unstable, but still risky.  It is not
-                     possible to upload packages directly to
-                     <em>testing</em>.
+                   The packages with this distribution value are deemed
+                   by their maintainers to be high risk.  Oftentimes they
+                   represent early beta or developmental packages from
+                   various sources that the maintainers want people to
+                   try, but are not ready to be a part of the other parts
+                   of the Debian distribution tree.
                  </item>
 
-                 <tag><em>frozen</em></tag>
+                 <tag><em>stable-proposed-updates</em></tag>
                  <item>
-                     From time to time, the <em>testing</em>
-                     distribution enters a state of "code-freeze" in
-                     anticipation of release as a <em>stable</em>
-                     version. During this period of testing only
-                     fixes for existing or newly-discovered bugs will
-                     be allowed.  The exact details of this stage are
-                     determined by the Release Manager.
+                   Once a distribution of Debian GNU/Linux is released,
+                   it is declared <em>stable</em> and only security fixes
+                   and other major bug fixes are allowed.  Proposed
+                   non-security updates for <em>stable</em> are uploaded
+                   using this distribution value after getting approval
+                   from the stable release managers.
                  </item>
 
-                 <tag><em>experimental</em></tag>
+                 <tag><em>testing-proposed-updates</em></tag>
                  <item>
-                     The packages with this distribution value are
-                     deemed by their maintainers to be high
-                     risk. Oftentimes they represent early beta or
-                     developmental packages from various sources that
-                     the maintainers want people to try, but are not
-                     ready to be a part of the other parts of the
-                     Debian distribution tree. Download at your own
-                     risk.
+                   The <em>testing</em> distribution, which cannot be
+                   uploaded to directly, normally receives its packages
+                   from the <em>unstable</em> distribution after a short
+                   time lag.  However sometimes, such as during release
+                   freezes before a new stable release or when a problem
+                   in the <em>testing</em> distribution requires fixing
+                   before the <em>unstable</em> version can migrate,
+                   direct uploads to <em>testing</em> are useful.  This
+                   distribution value is used for those exceptions.
                  </item>
                </taglist>
 
                <p>
-                 You should list <em>all</em> distributions that the
-                 package should be installed into.
+                 Security fixes for the <em>stable</em> or
+                 <em>testing</em> distributions are handled via a
+                 separate upload queue and special
+                 <em>stable-security</em> and <em>testing-security<em>
+                 distribution values.
                </p>
 
                <p>
@@ -3132,6 +3121,9 @@ Package: libc6
                  Reference, section "The Debian archive".
                </p>
            </footnote>
+           The Debian archive software only supports listing a single
+           distribution.  Migration of packages to other distributions is
+           handled outside of the upload process.
          </p>
        </sect1>