<debiandoc>
<!--
- Topics to be included someday:
+ Topics to be included:
+ - add an intro/scope section
- bugs in upstream versions should be reported upstream!
- pointer for useful tools for maintainers
+
-->
<book>
As you can see, the top-level directory of the distribution contains
three directories, namely <em>main</>, <em>contrib</>, and
<em>non-free</>. These directories are called <em>sections</>.
-<!-- NO THEY ARE NOT!!!!
-dark: so from the current devel-ref, s/sub-section/section and s/section/SOMETHING ELSE/
-
-*dark* You call main, contrib, and non-free "sections", and you call admin, base, etc "subsections".
-*dark* The latter are called "sections" everywhere else. The former don't have a real name, but Christian used
- | "sub-sections" in the policy manual.
-dark: so dists/stable/main/binary-all/admin, for instance, is a "section" of the debian distribution.... and the naming for dists/stable/contrib itself is unclear
-<dark> aph: Yep.
-AFAIK, dists/stable/main is itself the actual distribution
-<dark> aph: That's how the packaging manual describes it. And there's the "Section:" header.
-<dark> aph: Unfortunately, Guy kind of polluted that by using contrib/section and non-free/section as sections.
-
-<dark> aph: Hmm Culus may have invented a name for the something else, in his archive-description file format.
-
--->
<p>
In each section, there is a directory with the source packages
(source), a directory for each supported architecture (binary-i386,
(disks-i386, disks-m68k, etc.).
<p>
The <em/binary/ and <em/source/ directories are divided further into
-<em/sub-sections/.
+<em/subsections/.
<sect>Sections
<p>
-The <em>main section</> is what makes up the <em>Debian GNU/Linux
+The <em>main</em> section is what makes up the <em>Debian GNU/Linux
distribution</>. This is because the packages in the other two
-sections do not fully comply with all our guidelines.
+sections do not fully comply with all our guidelines. As such, they
+are not officially part of Debian.
<p>
For example, every package in the main distribution must fully comply
with the <em>Debian Free Software Guidelines</> (DFSG) and with all
non-free software packages.
<p>
Packages in the <em>contrib</> section have to apply to the DFSG, but
-fail other requirements.
+fail other requirements. For instance, they might depend on non-free
+packages.
<p>
(The Debian Policy Manual contains a more exact definition of the
three sections. This is just meant to be an introduction.)
The separation of the three sections at the top-level of the archive
is important for all people who want to distribute Debian, either via
FTP servers on the Internet or on CD-ROMs: by distributing only the
-<em/main/ and <em/contrib/ sections, one can avoid any legal risks,
-since some packages in the <em/non-free/ section do not allow
-commercial distribution, for example.
+<em/main/ and <em/contrib/ sections, one can avoid any legal risks.
+Some packages in the <em/non-free/ section do not allow commercial
+distribution, for example.
<p>
On the other hand, a CD-ROM vendor could easily check the individual
package licenses of the packages in <em/non-free/ and include as many
<p>
Debian GNU/Linux 1.3 is only available for Intel platforms. Debian
2.0 supports Intel and m68k architectures. The next version of Debian
-is likely to also support Sparc, PPC, and Alpha, if not more.
+is likely to also support Alpha, PPC, and Sparc architectures, if not
+more.
- <sect>Sub sections
+ <sect>Subsections
<p>
The sections <em/main/, <em/contrib/, and <em/non-free/ are split into
-<em/sub sections/, to simplify the installation process and the
-maintainance of the archive.
+<em/subsections/, to simplify the installation process and the
+maintainance of the archive. Subsections are not formally defined,
+excepting perhaps for the "base" subsection. Subsections exist simply
+to simpilfy the organization and browsing of available packages.
+Please check the current Debian distribution to see which sections are
+available.
+
<sect>Packages
changes from day to day and since no special effort is done to test
this distribution it's sometimes ``unstable.''
<p>
-After about two months of development, the <em/unstable/ distribution
-is copied in a new distribution directory, called <em/frozen/. After
+After about a period of development, the <em/unstable/ distribution is
+copied in a new distribution directory, called <em/frozen/. After
that, no changes are allowed to the frozen distribution, except bug
-fixes. (That's why it's called ``frozen.'')
- <p>
-After another month or a little longer, the <em/frozen/ distribution
-is renamed to <em/stable/, overriding the old <em/stable/
-distribution, which is removed at that time.
- <p>
-This development cycle is based on the assumption, that the once
-`unstable' distribution finally becomes `stable' after passing one
-month of testing. Unfortunately, a few bugs still remain--that's why
-the stable distribution is updated every now and then. However, these
-updates are tested very carefully and have to be acknowledged
-individually to reduce the risk of introducing new bugs. You can find
-proposed additions to `stable' in the <tt/proposed-updates/ directory.
+fixes. (That's why it's called ``frozen.'') After another month or a
+little longer, the <em/frozen/ distribution is renamed to <em/stable/,
+overriding the old <em/stable/ distribution, which is removed at that
+time.
+ <p>
+This development cycle is based on the assumption that the `unstable'
+distribution becomes `stable' after passing a period of testing as
+`frozen'. Unfortunately, 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 acknowledged individually to
+reduce the risk of introducing new bugs. You can find proposed
+additions to `stable' in the <tt/proposed-updates/ directory.
<p>
Note, that development is continued during the ``freeze'' period,
-since a new ``unstable'' distribution will be created at that time.
+since a new `unstable' distribution is be created when the older
+`unstable' is moved to `frozen'.
<p>
In summary, there is always a <em/stable/ and an <em/unstable/
-distribution available and the <em/frozen/ distribution shows up for a
-month from time to time.
+distribution available, and the <em/frozen/ distribution shows up for
+a month or so from time to time.
<sect>Release code names
<p>
should first check the <url
id="http://www.debian.org/doc/prospective-packages.html"
name="Work-Needing and Prospective Packages (WNPP)"> page. Checking
-the WNPP ensures that effort is not duplicated or wasted; namely, that
-no-one is already working on packaging that software. Assuming no-one
-else is currently working on your prospective package, you have to
-send a short email to <email/debian-devel@lists.debian.org/ describing
-your plan create a new package. You should set the subject of the
-email to "intent to package <var/foobar/", substituting the name of
-the new package for <var/foobar/.
+the WNPP ensures that no-one is already working on packaging that
+software, and that effort is not duplicated. Assuming no-one else is
+already working on your prospective package, you must then send a
+short email to <email/debian-devel@lists.debian.org/ describing your
+plan to create a new package. You should set the subject of the email
+to "intent to package <var/foobar/", substituting the name of the new
+package for <var/foobar/.
<p>
There are a number of reasons why we ask maintainers to follow these
steps.
All of them are mandatory for a Debian upload. See the list of
control fields in the <em/Debian Packaging Manual/ for the contents of
these fields.
+ <p>
+Notably, the <tt/Distribution/ field, which originates from the
+<tt>debian/changelog</tt> file, should indicate which distribution the
+package is intended for. There are three possible values for this
+field: `stable', `unstable', or `frozen'; these values can also be
+combined. For instance, if you have a crucial security fix release of
+a package, and the package has not diverged between the `stable' and
+`unstable' distributions, then you might put `stable unstable' in the
+<tt>debian/changelog</tt>'s distribution field. Or, if Debian has
+been frozen, and you want to get a bug-fix release into `frozen', you
+would set the distribution to `frozen unstable'. Note that setting
+the distribution to `stable' means that the pacakge will be placed
+into the <tt>proposed-updates</tt> directory of the Debian archive for
+further testing, before it is actually included in `stable'.
+
<p>
The first time a version is uploaded which corresponds to a particular
upstream version the original source tar file should be uploaded and
that bug reports will go to you.
+ <chapt>Moving, removing, renaming, and orphaning packages
+ <p>
+Some archive manipulation operation are not automated in the Debian
+upload process. This chapter gives guidelines in what to do in these
+cases.
+
+ <sect>Moving packages
+ <p>
+Sometimes a package will change either it's section or it's
+subsection. For instance, a package from the `non-free' section might
+be GPL'd in a later version; in this case you should consider moving
+it to `main' or `contrib' (see the <em/Policy Manual/ for guidelines).
+ <p>
+In this case, it is sufficient to edit the package control information
+normally and re-upload the package (see the <em/Packaging Manual/ for
+details). Carefully examine the installation log sent to you when the
+package is installed into the archive. If for some reason the old
+location of the package remains, file a bug against
+<prgn/ftp.debian.org/ asking that the old location be removed. Give
+details on what you did, since it might be a <prgn/dinstall/ bug.
+
+ <sect>Removing packages
+ <p>
+If for some reason you want to completely remove a package (say, if it
+is an old compatability library which is not longer required), you
+need to file a bug against <prgn/ftp.debian.org/ asking that the
+package be removed. Make sure you indicate which distribution the
+package should be removed from.
+ <p>
+If in doubt concerning whether a package is disposable, email
+<email/debian-devel@lists.debian.org/ asking for opinions.
+
+ <sect>Replacing or renaming packages
+ <p>
+Sometimes you made a mistake naming the package and you need to rename
+it. In this case, you need to follow a two-step process. First, set
+your <tt>debian/control</tt> file to replace and conflict with the
+obsolete name of the package (see the <em/Packaging Manual/ for
+details). Once you've uploaded that package, and the package has
+moved into the archive, file a bug against <prgn/ftp.debian.org/
+asking to remove the package with the obsolete name.
+
+ <sect>Orphaning a package
+ <p>
+If you can no longer maintain a package, then you should set the
+package maintainer to <tt>Debian QA
+<debian-qa@lists.debian.org></tt> and email
+<email/wnpp@debian.org/ indicating that the package is now orphaned.
+If the package is especially crucial to Debian, you should instead
+email <email/debian-devel@lists.debian.org/ asking for a new
+maintainer.
+
+
<chapt>Handling bug reports
- <sect>Bugs in your packages
+ <sect>Monitoring bugs
<p>
If you want to be a good maintainer, you should periodically check the
<url id="http://www.debian.org/Bugs/" name="Debian bug tracking system
(BTS)"> for your packages. The BTS contains all the open bugs against
your packages.
<p>
+Maintainers interact with the BTS via email addresses at
+<tt/bugs.debian.org/. Documentation on available commands can be
+found at <url id="http://www.debian.org/Bugs/">, or, if you have
+installed the <prgn/debian-doc/ package, you can look at the local
+files <tt>/usr/doc/debian/bug-*</tt>.
+ <p>
+Often as a package maintainer, you find bugs in other packages or else
+have bugs reported to your packages which need to be reassigned. The
+BTS instructions can tell you how to do this. Make sure the bug is
+not already filed against a package. Try to do a good job reporting a
+bug and redirecting it to the proper location. For extra credit, you
+can go through other packages, merging bugs which are reported more
+than once, or setting bug severities to "fixed" when they have already
+been fixed. Note that when you are neither the bug submitter nor the
+package maintainer, you are not empowered to actually close the bug
+(unless you secure permission from the maintainer).
+
+ <sect>When bugs are closed by new uploads
+ <p>
If you fix a bug in your packages, it is your responsibility as the
package maintainer to close the bug when it has been fixed. However,
you should not close the bug until the package which fixes the bug has
notification that your updated package has been installed into the
archive, you can and should close the bug in the BTS.
<p>
-Maintainers interact with the BTS via email addresses at
-<tt/bugs.debian.org/. Documentation on available commands can be
-found in <tt>/usr/doc/debian/bug-*</tt> from the <prgn/debian-doc/
-package.
+Again, see the BTS documentation for details on how to do this.
+Often, it's sufficient to mail the <tt/.changes file to
+<email/<var/XXX/-done@bugs.debian.org/, where <var/XXX/ is your bug
+number.
<sect>Lintian reports
<p>
You should periodically get the new <prgn/lintian/ from `unstable' and
check over all your packages. Alternatively you can check for you're
-maintainer email address at <url
-id="http://www.debian.org/lintian/">. That page, which is
-updated automatically, contains lintian reports against the latest
-version of the package (usually from 'unstable') using the latest
-<prgn/lintian/.
+maintainer email address at <url id="http://www.debian.org/lintian/">.
+That page, which is updated automatically, contains <prgn/lintian/
+reports against the latest version of the package (usually from
+'unstable') using the latest <prgn/lintian/.
<sect>Reporting lots of bugs at once
~ianmdlvl / developers-reference.git / commitdiff