created a new subsection about uploading to stable, and elaborated about that subject...

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

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 7f10814dc018c29e02f7b3068e72bbb1982e789e..f45f7f67be44dd045559eecd800145dea077b56a 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -5,7 +5,7 @@
   <!-- common, language independant entities -->
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.65 $">
+  <!entity cvs-rev "$Revision: 1.66 $">
 
   <!-- if you are translating this document, please notate the RCS
        revision of the developers reference here -->
@@ -954,14 +954,8 @@ anything else.
 You should avoid combining `stable' with others because of potential
 problems with library dependencies (for your package and for the package
 built by the build daemons for other architecture).
-Also note that setting the distribution to `stable' means
-that the package will be placed into the <tt>proposed-updates</tt>
-directory of the Debian archive for further testing before it is actually
-included in <em>stable</em>. The Release Team (which can be reached at
-&email-debian-release;) will decide if your package can be included in
-stable, therefore if your changelog entry is not clear enough, you may
-want to explain them why you uploaded your package to stable by sending 
-them a short explication.
+See <ref id="upload-stable"> for more information on when and how to
+upload to <em>stable</em>.
          <p>
 The first time a version is uploaded which corresponds to a particular
 upstream version, the original source tar file should be uploaded and
@@ -1025,6 +1019,43 @@ original bug fixed and the severity of the bug newly introduced by the
 fix.
 
 
+         <sect2 id="upload-stable">Uploading to <em>stable</em>
+           <p>
+Uploading to <em>stable</em> means that the package will be placed into the
+<tt>proposed-updates</tt> directory of the Debian archive for further
+testing before it is actually included in <em>stable</em>.
+           <p>
+Extra care should be taken when uploading to <em>stable</em>. Basically, a
+package should only be uploaded to stable if one of the following happens:
+<list>
+       <item>a security problem (e.g. a Debian security advisory)
+       <item>a truely critical functionality problem
+       <item>the package becomes uninstallable
+       <item>a released architecture lacks the package
+</list>
+           <p>
+It is discouraged to change anything else in the package that isn't
+important, because even trivial fixes can cause bugs later on. Uploading
+new upstream versions to fix security problems is deprecated; applying the
+specific patch from the new upstream version to the old one ("backporting"
+the patch) is the right thing to do in most cases.
+           <p>
+Packages uploaded to <em>stable</em> need to be compiled on systems running
+<em>stable</em>, so that their dependencies are limited to the libraries
+(and other packages) available in <em>stable</em>; for example, a package
+uploaded to <em>stable</em> that depends on a library package that only
+exists in unstable will be rejected. Making changes to dependencies of other
+packages (by messing with <tt>Provides</tt> or shlibs files), possibly making
+those other packages uninstallable, is strongly discouraged.
+           <p>
+The Release Team (which can be reached at &email-debian-release;) will
+regularly evaluate the uploads in <em>proposed-updates</em> and decide if
+your package can be included in <em>stable</em>. Please be clear (and
+verbose, if necessary) in your changelog entries for uploads to
+<em>stable</em>, because otherwise the package won't be considered for
+inclusion.
+
+
 
        <sect1 id="upload-checking">Checking the package prior to upload
          <p>
@@ -1341,13 +1372,12 @@ distribution, i.e., stable, unstable, or frozen.  Porters have
 slightly different rules than non-porters, due to their unique
 circumstances (see <ref id="source-nmu-when-porter">).
        <p>
-Only critical changes or security bug fixes make it into stable.  When
-a security bug is detected, a fixed package should be uploaded as soon
-as possible. In this case, the Debian Security Managers should get in
+When a security bug is detected, a fixed package should be uploaded
+as soon as possible. In this case, the Debian security officers get in
 contact with the package maintainer to make sure a fixed package is
 uploaded within a reasonable time (less than 48 hours). If the package
 maintainer cannot provide a fixed package fast enough or if he/she
-cannot be reached in time, the Security Manager may upload a fixed
+cannot be reached in time, a security officer may upload a fixed
 package (i.e., do a source NMU).
        <p>
 During the release freeze (see <ref id="upload-frozen">), NMUs which