4.6.4. Distributions

The directory system described in the previous chapter is itself contained within distribution directories. Each distribution is actually contained in the pool directory in the top level of the Debian archive itself.

To summarize, the Debian archive has a root directory within a mirror site. For instance, at the mirror site ftp.us.debian.org the Debian archive itself is contained in /debian, which is a common location (another is /pub/debian).

A distribution comprises Debian source and binary packages, and the respective Sources and Packages index files, containing the header information from all those packages. The former are kept in the pool/ directory, while the latter are kept in the dists/ directory of the archive (for backwards compatibility).

4.6.4.1. Stable, testing, and unstable

There are always distributions called stable (residing in dists/stable), testing (residing in dists/testing), and unstable (residing in dists/unstable). This reflects the development process of the Debian project.

Active development is done in the unstable distribution (that’s why this distribution is sometimes called the development distribution). Every Debian developer can update their packages in this distribution at any time. Thus, the contents of this distribution change from day to day. Since no special effort is made to make sure everything in this distribution is working properly, it is sometimes literally unstable.

The The testing distribution 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 update to testing is launched twice each day, right after the new packages have been installed. See The testing distribution.

After a period of development, once the release manager deems fit, the testing distribution is frozen, meaning that the policies which control how packages move from unstable to testing are tightened. Packages which are too buggy are removed. No changes are allowed into testing except for bug fixes. After some time has elapsed, depending on progress, the testing distribution is frozen even further. Details of the handling of the testing distribution are published by the Release Team on debian-devel-announce. After the open issues are solved to the satisfaction of the Release Team, the distribution is released. Releasing means that testing is renamed to stable, and a new copy is created for the new testing, and the previous stable is renamed to oldstable and stays there until it is finally archived. On archiving, the contents are moved to archive.debian.org.

This development cycle is based on the assumption that the unstable distribution becomes stable after passing a period of being in testing. Even once a distribution is considered stable, a few bugs inevitably remain — that’s why the stable distribution is updated every now and then. However, these updates are tested very carefully and have to be introduced into the archive individually to reduce the risk of introducing new bugs. You can find proposed additions to stable in the proposed-updates directory. Those packages in proposed-updates that pass muster are periodically moved as a batch into the stable distribution and the revision level of the stable distribution is incremented (e.g., ‘6.0’ becomes ‘6.0.1’, ‘5.0.7’ becomes ‘5.0.8’, and so forth). Please refer to Special case: uploads to the stable and oldstable distributions for details.

Note that development in unstable during the freeze should not be continued as usual, as packages are still build in unstable, before they migrate to testing, thus unstable should only contain packages ment for testing. Thus only upload to unstable during freezes, if you are planning to request an unblock (or if the package is not in testing).

If you want to develop new stuff for after the freeze, upload to experimental instead.

4.6.4.2. More information about the testing distribution

Packages are usually installed into the testing distribution after they have undergone some degree of testing in unstable.

For more details, please see the The testing distribution.

4.6.4.3. Experimental

The experimental distribution is a special distribution. It is not a full distribution in the same sense as stable, testing 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, or software that’s just too unstable even for the unstable distribution (but there is a reason to package it nevertheless). Users who download and install packages from experimental are expected to have been duly warned. In short, all bets are off for the experimental distribution.

These are the sources.list 5 lines for experimental:

deb http://deb.debian.org/debian/ experimental main
deb-src http://deb.debian.org/debian/ experimental main

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 experimental. For instance, an experimental compressed file system should probably go into experimental.

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 experimental. A new, beta, version of some software which uses a completely different configuration can go into experimental, at the maintainer’s discretion. If you are working on an incompatible or complex upgrade situation, you can also use experimental as a staging area, so that testers can get early access.

Some experimental software can still go into unstable, with a few warnings in the description, but that isn’t recommended because packages from unstable are expected to propagate to testing and thus to stable. You should not be afraid to use experimental since it does not cause any pain to the ftpmasters, the experimental packages are periodically removed once you upload the package in unstable with a higher version number.

New software which isn’t likely to damage your system can go directly into unstable.

An alternative to experimental is to use your personal web space on people.debian.org.