<!-- 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.68 $">
<!-- if you are translating this document, please notate the RCS
revision of the developers reference here -->
<sect1>Experimental
-<!-- Note: experimental is currently dead because of the package pools.
- Once that changes, the description below will most probably need
- adjustments. -->
<p>
The <em>experimental</em> distribution is a specialty distribution.
It is not a full distribution in the same sense as `stable' and
`unstable' are. Instead, it is meant to be a temporary staging area
for highly experimental software where there's a good chance that the
-software could break your system. Users who download and install
+software could break your system, or software that's just too unstable
+even for the <em>unstable</em> distribution (but there is a reason to
+package it nevertheless). Users who download and install
packages from <em>experimental</em> are expected to have been duly
warned. In short, all bets are off for the <em>experimental</em>
distribution.
<p>
-Developers should be very selective in the use of the
-<em>experimental</em> distribution. Even if a package is highly
-unstable, it could still go into <em>unstable</em>; just state a
-few warnings in the description. However, if there is a chance that
-the software could do grave damage to a system, it might be better to
-put it into <em>experimental</em>.
- <p>
+If there is a chance that the software could do grave damage to a system,
+it is likely to be better to put it into <em>experimental</em>.
For instance, an experimental compressed file system should probably go
-into <em>experimental</em>. A new, beta, version of some software
-which uses completely different configuration might go into
-<em>experimental</em> at the maintainer's discretion. New software
-which isn't likely to damage your system can go into
-<em>unstable</em>. If you are working on an incompatible or complex
-upgrade situation, you can also use <em>experimental</em> as a staging
-area, so that testers can get early access.
- <p>
-However, using <em>experimental</em> as a personal staging area is not
-always the best idea, especially with transient packages. For
-example, you cannot delete packages which have been uploaded to
-<em>experimental</em> on your own; that must be done by the Debian
-archive maintainers. An alternative is to use your personal web space
-on <tt>klecker.debian.org</tt>, a.k.a. <tt>people.debian.org</tt>.
+into <em>experimental</em>.
+ <p>
+Whenever there is a new upstream version of a package that introduces new
+features but breaks a lot of old ones, it should either not be uploaded, or
+be uploaded to <em>experimental</em>. A new, beta, version of some software
+which uses completely different configuration can go into
+<em>experimental</em>, at the maintainer's discretion. If you are working
+on an incompatible or complex upgrade situation, you can also use
+<em>experimental</em> as a staging area, so that testers can get early
+access.
+ <p>
+Some experimental software can still go into <em>unstable</em>, with a few
+warnings in the description, but that isn't recommended because packages
+from <em>unstable</em> are expected to propagate to <em>testing</em> and
+thus to <em>stable</em>.
+ <p>
+New software which isn't likely to damage your system can go directly into
+<em>unstable</em>.
+ <p>
+An alternative to <em>experimental</em> is to use your personal web space
+on <tt>people.debian.org</tt> (<tt>klecker.debian.org</tt>).
<sect id="codenames">Release code names
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
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>
`experimental', or `frozen' (when present), the announcement will be
posted to &email-debian-devel-changes; instead.
<p>
-On occasion, it is necessary to upload a package to both the
-<em>stable</em> and <em>unstable</em> distributions; this is done by
-putting both distributions in the <tt>Distribution:</tt> line. In
-such a case the upload announcement will go to both of the above
-mailing lists.
- <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">.
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