<!-- retain these comments for translator revision tracking -->
<!-- Original version: $Revision: 1.49 $ -->
<chapt id="ftparchives">The Debian FTP archives

<sect id="dists">How many Debian distributions are there?

<p>There are three major distributions: the "stable" distribution, the
"testing" distribution, and the "unstable" distribution. The "testing"
distribution is sometimes `frozen' (see <ref id="frozen">).  Next to these,
there is the "oldstable" distribution (that's just the one from before
"stable"), and the "experimental" distribution. 

<p>Experimental is used for packages which are still being developed, and with
a high risk of breaking your system.  It's used by developers who'd like to
study and test bleeding edge software.  Users shouldn't be using packages from
here, because they can be dangerous and harmful even for the most experienced
people.

<p>See <ref id="choosing"> for help when choosing a Debian distribution.

<sect id="codenames">What are all those names like etch, lenny, etc.?

<p>They are just "codenames". When a Debian distribution is in the
development stage, it has no version number but a codename. The purpose
of these codenames is to make easier the mirroring of the Debian
distributions (if a real directory like <tt>unstable</tt> suddenly changed
its name to <tt>stable</tt>, a lot of stuff would have to be needlessly
downloaded again).

<p>Currently, <tt>stable</tt> is a symbolic link to <tt>&releasename;</tt>
(i.e. &debian; &release;) and <tt>testing</tt> is a symbolic link to
<tt>&testingreleasename;</tt>.
This means that <tt>&releasename;</tt> is the current stable
distribution and <tt>&testingreleasename;</tt> is the current testing distribution.

<p><tt>unstable</tt> is a permanent symbolic link to <tt>sid</tt>, as
<tt>sid</tt> is always the unstable distribution (see <ref id="sid">).

<sect1 id="oldcodenames">Which other codenames have been used in the past?

<p>Other codenames that have been already used are: <tt>buzz</tt> for
release 1.1, <tt>rex</tt> for release 1.2, <tt>bo</tt> for releases 1.3.x,
<tt>hamm</tt> for release 2.0, <tt>slink</tt> for release 2.1,
<tt>potato</tt> for release 2.2, <tt>woody</tt> for release 3.0,
<tt>sarge</tt> for release 3.1, <tt>etch</tt> for release 4.0, and
<tt>lenny</tt> for release 5.0, and
<tt>squeeze</tt> for release 6.0,
<tt>wheezy</tt> for release 7.0.

<sect1 id="sourceforcodenames">Where do these codenames come from?

<p>So far they have been characters taken from the "Toy Story" movies by Pixar.
<list>
  <item><em>buzz</em> (Buzz Lightyear) was the spaceman,
  <item><em>rex</em> was the tyrannosaurus,
  <item><em>bo</em> (Bo Peep) was the girl who took care of the sheep,
  <item><em>hamm</em> was the piggy bank,
  <item><em>slink</em> (Slinky Dog) was the toy dog,
  <item><em>potato</em> was, of course, Mr. Potato,
  <item><em>woody</em> was the cowboy,
  <item><em>sarge</em> was the sergeant of the Green Plastic Army Men,
  <item><em>etch</em> was the toy blackboard (Etch-a-Sketch),
  <item><em>lenny</em> was the toy binoculars,
  <item><em>squeeze</em> was the name for the three-eyed aliens,
  <item><em>wheezy</em> was the name of the rubber toy penguin with 
  a red bow tie,
  <item><em>jessie</em> was the name of the yodelling cowgirl.

<!-- SID should be the last line always -->
  <item><em>sid</em> was the boy next door who destroyed toys.
</list>

<!-- TODO
  Q: Should we add the trademark info here? Maybe as a footnote
  Mr. Potato is a Registered Trademark of Playskool, Inc.,
    Pawtucket, R.I., a division of Hasbro Inc.
  Slinky Dog is a trademark of Poof Products of Plymouth, Mich.,
  Etch-a-Sketch is a trademark of The Ohio Art Company,
  other characters might also be registered trademarks...
  (jfs)
-->
<!--
  more info in http://www.pixar.com/featurefilms/ts/
  and  http://www.pixar.com/featurefilms/ts2/
  or
  http://en.wikipedia.org/wiki/List_of_Toy_Story_characters
  or better yet http://us.imdb.com/M/title-exact?Toy%20Story%20(1995)
  or actually:
    http://us.imdb.com/Title?0114709 for TS1
    http://us.imdb.com/Title?0120363 for TS2
  we shouldn't put the links in, Pixar needs no additional propaganda
-->
<!--
  characters not used from Toy Story (yet):
    - Andy (the kid)
    - Snake
    - Robot
    - Scud (Sid's dog)
    - Three Eyed Alien
    - Rocky (the wrestling figure)
    - Roller Bob (the remote control car)
    - Legs (one of sid's mutant toys)
    - Hand-in-the-box (one of sid's mutant toys)
    - Duckie (one of sid's mutant toys)
  and additional characters from Toy Story 2, also not yet used:
    - Al (the propietor of Al's Toy Farm)
    - Bullseye (Woody's toy horse)
    - Zurg (the Evil Emperor)
    - Hannah (owner of Jessie)
    - Stinky Pete the Prospector (the old fat guy)
    - Mrs. Davis (Andy's Mom)
    - Barbie (the Tour Guide, probably under (c))
    - Mrs. Potato Head
    - Heimlich the Caterpillar
-->
<!-- (jfs) Just in case somebody misses the "What do we do when we finish
with Toy Story characters" thread see:
http://lists.debian.org/debian-devel/2002/debian-devel-200207/msg01133.html

I suggested we followed with either "Monster's Inc" or "A Bug's life" :)
-->

<sect id="sid">What about "sid"?

<p><em>sid</em> or <em>unstable</em> is the place where most of the packages
are initially uploaded. It will never be released directly, because packages
which are to be released will first have to be included in <em>testing</em>,
in order to be released in <em>stable</em> later on. sid contains packages
for both released and unreleased architectures.

<p>The name "sid" also comes from the "Toy Story" animated motion picture:
Sid was the boy next door who destroyed toys :-)

<p><footnote>
<p>When the present-day sid did not exist, the FTP site organization had one
major flaw: there was an assumption that when an architecture is created in
the current unstable, it will be released when that distribution becomes the
new stable. For many architectures that isn't the case, with the result that
those directories had to be moved at release time. This was impractical
because the move would chew up lots of bandwidth.

<p>The archive administrators worked around this problem for several years
by placing binaries for unreleased architectures in a special directory
called "sid". For those architectures not yet released, the first time they
were released there was a link from the current stable to sid, and from
then on they were created inside the unstable tree as normal. This layout
was somewhat confusing to users.

<p>With the advent of package pools (see <ref id="pools">), binary packages
began to be stored in a canonical location in the pool, regardless of the
distribution, so releasing a distribution no longer causes large bandwidth
consumption on the mirrors (there is, however, a lot of gradual bandwidth
consumption throughout the development process).
</footnote>

<sect id="stable">What does the stable directory contain?

<p><list>
  <item>stable/main/:
  This directory contains the packages which formally constitute the most
  recent release of the &debian; system.

  <p>These packages all comply with the <url name="Debian Free Software
  Guidelines" id="http://www.debian.org/social_contract#guidelines">,
  and are all freely usable and distributable.

  <item>stable/non-free/:  This directory contains packages distribution of
  which is restricted in a way that requires that distributors take careful
  account of the specified copyright requirements.

  <p>For example, some packages have licenses which prohibit commercial
  distribution.  Others can be redistributed but are in fact shareware
  and not free software.  The licenses of each of these packages must be
  studied, and possibly negotiated, before the packages are included in
  any redistribution (e.g., in a CD-ROM).

  <item>stable/contrib/: This directory contains packages which are
  DFSG-free and <em>freely distributable</em> themselves, but somehow depend
  on a package that is <em/not/ freely distributable and thus available only
  in the non-free section.
</list>

<sect id="testing">What does the testing distribution contain?

<p>Packages are installed into the `testing' directory after they have
undergone some degree of testing in <qref id="unstable">unstable</qref>.

<p>They must be in sync on all architectures where they have been built and
mustn't have dependencies that make them uninstallable; they also have to
have fewer release-critical bugs than the versions currently in testing.
This way, we hope that `testing' is always close to being a release
candidate.

<p>More information about the status of "testing" in general and the
individual packages is available at
<url id="http://www.debian.org/devel/testing">.

<sect1 id="frozen">What about "testing"? How is it `frozen'?

<p>When the "testing" distribution is mature enough, the release manager
starts `freezing' it. The normal propagation delays are increased to ensure
that as little as possible new bugs from "unstable" enter "testing".

<p>After a while, the "testing" distribution becomes truly `frozen'. This
means that all new packages that are to propagate to the "testing" are held
back, unless they include release-critical bug fixes. The "testing"
distribution can also remain in such a deep freeze during the so-called
`test cycles', when the release is imminent.

<p>When a "testing" release becomes `frozen', "unstable" tends to partially
freeze as well.  This is because developers are reluctant to upload radically
new software to unstable, in case the frozen software in testing needs minor
updates and to fix release critical bugs which keep testing from becoming
"stable".

<p>We keep a record of bugs in the "testing" distribution that can hold off a
package from being released, or bugs that can hold back the whole release.
For details, please see <url name="current testing release information"
id="http://www.debian.org/releases/testing/">.

<p>Once that bug count lowers to maximum acceptable values, the frozen
"testing" distribution is declared "stable" and released with a version
number.

<p>The most important bug count is the "Release Critical" bug count, which can
be followed in the <url name="Release-critical bug status page"
id="http://bugs.debian.org/release-critical/">. A common release goal 
is <url name="NoRCBugs" id="http://wiki.debian.org/ReleaseGoals/NoRCBugs">
which means that the distribution should not have any bugs of severity
critical, grave or serious. The full list of issues considered critical can be
found in the <url name="RC policy document"
id="http://release.debian.org/testing/rc_policy.txt">.

<p>With each new release, the previous "stable" distribution becomes
obsolete and moves to the archive. For more information please see
<url name="Debian archive" id="http://www.debian.org/distrib/archive">.

<sect id="unstable">What does the unstable distribution contain?

<p>The `unstable' directory contains a snapshot of the current development
system. Users are welcome to use and test these packages, but are warned
about their state of readiness. The advantage of using the unstable
distribution is that you are always up-to-date with the latest in GNU/Linux
software industry, but if it breaks: you get to keep both parts :-)

<p>There are also main, contrib and non-free subdirectories in `unstable',
separated on the same criteria as in `stable'.

<sect id="dirtree">What are all those directories at the Debian FTP archives?

<p>The software that has been packaged for &debian; is available in one
of several directory trees on each Debian mirror site.

<p>The <tt>dists</tt> directory is short for "distributions", and it is
the canonical way to access the currently available Debian releases
(and pre-releases).

<p>The <tt>pool</tt> directory contains the actual packages, see
<ref id="pools">.

<p>There are the following supplementary directories:
<taglist>
  <tag><em>/tools/</em>:
    <item>DOS utilities for creating boot disks, partitioning
    your disk drive, compressing/decompressing files, and booting Linux.
  <tag><em>/doc/</em>:
    <item>The basic Debian documentation, such as this FAQ, the bug reporting
          system instructions, etc.
  <tag><em>/indices/</em>:
    <item>various indices of the site (the Maintainers file and the override
          files).
  <tag><em>/project/</em>:
    <item>mostly developer-only materials and some miscellaneous files.
</taglist>

<sect id="archsections">What are all those directories inside
  <tt>dists/stable/main</tt>?

<p>Within each of the major directory trees<footnote>
  <tt>dists/stable/main</tt>, <tt>dists/stable/contrib</tt>,
  <tt>dists/stable/non-free</tt>, and <tt>dists/unstable/main/</tt>, etc.
</footnote>, there are three sets of subdirectories containing index files.

<p>There's one set of <tt>binary-<var>something</var></tt> subdirectories
which contain index files for binary packages of each available computer
architecture, for example <tt/binary-i386/ for packages which execute on
Intel x86 PC machines or <tt/binary-sparc/ for packages which execute on
Sun SPARCStations.

<p>The complete list of available architectures for each release is available
at <url name="the release's web page" id="http://www.debian.org/releases/">.
For the current release, please see <ref id="arches">.

<p>The index files in binary-* are called Packages(.gz, .bz2) and they include
a summary of each binary package that is included in that distribution.
The actual binary packages
reside in the top level <qref id="pools"><tt/pool/ directory</qref>.

<p>Furthermore, there's a subdirectory called source/ which
contains index files for source packages included in the distribution.
The index file is called Sources(.gz, .bz2).

<p>Last but not least, there's a set of subdirectories meant for the
installation system index files, they are at
<tt>debian-installer/binary-<var>architecture</var></tt>.

<sect id="source">Where is the source code?

<p>Source code is included for everything in the Debian system. Moreover,
the license terms of most programs in the system <em>require</em> that
source code be distributed along with the programs, or that an offer to
provide the source code accompany the programs.

<p>The source code is distributed in the <tt>pool</tt> directory
(see <ref id="pools">) together with all the architecture-specific
binary directories.
To retrieve the source code without having to be familiar with the
structure of the FTP archive, try a command like
<tt>apt-get source mypackagename</tt>.

<p>Some packages are only distributed as source code due to the restrictions
in their licenses. Notably, one such package is <tt>pine</tt>, see
<ref id="pine"> for more information.

<p>Source code may or may not be available for packages in the "contrib"
and "non-free" directories, which are not formally part of the Debian system.

<sect id="pools">What's in the <tt>pool</tt> directory?

<p>Packages are kept in a large `pool', structured according to the name
of the source package. To make this manageable, the pool is subdivided by
section (`main', `contrib' and `non-free') and by the first letter of the
source package name. These directories contain several files: the binary
packages for each architecture, and the source packages from which the binary
packages were generated.

<p>You can find out where each package is placed by executing a command like
<tt>apt-cache showsrc mypackagename</tt> and looking at the `Directory:'
line. For example, the <tt>apache</tt> packages are stored in
<tt>pool/main/a/apache/</tt>.

<p>Additionally, since there are so many <tt>lib*</tt>
packages, these are treated specially: for instance, libpaper packages are
stored in <tt>pool/main/libp/libpaper/</tt>.

<!-- joeyh doesn't want to maintain it so it's dead; need to integrate it
     If you want more information, see the
     <url id="http://people.debian.org/~joeyh/poolfaq"
     name="Debian Package Pools FAQ">.
-->

<p><footnote>
<p>Historically, packages were kept in the subdirectory of <tt>dists</tt>
corresponding to which distribution contained them. This turned out to cause
various problems, such as large bandwidth consumption on mirrors when major
changes were made. This was fixed with the introduction of the package pool.

<p>The <tt>dists</tt> directories are still used for the index files
used by programs like <tt>apt</tt>.
</footnote>

<sect id="incoming">What is "incoming"?

<p>After a developer uploads a package, it stays for a short while in the
"incoming" directory before it is checked that it's genuine and allowed into
the archive.

<p>Usually nobody should install things from this place. However, in some
rare cases of emergency, the incoming directory is available at
<url id="http://incoming.debian.org/">. You can manually fetch packages,
check the GPG signature and MD5sums in the .changes and .dsc files,
and then install them.

<sect id="ownrepository">How do I set up my own apt-able repository?

<p>If you have built some private Debian packages which you'd like to install
using the standard Debian package management tools, you can set up your own
apt-able package archive.  This is also useful if you'd like to share your
Debian packages while these are not distributed by the Debian project.
Instructions on how to do this are given in the <url name="Debian Repository
HOWTO"
id="http://www.debian.org/doc/manuals/repository-howto/repository-howto">.

