<!ENTITY % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!ENTITY cvs-rev "$Revision: 1.232 $">
+ <!ENTITY cvs-rev "$Revision: 1.238 $">
<!-- if you are translating this document, please notate the CVS
revision of the original developer's reference in cvs-en-rev -->
<title>Debian Developer's Reference
<author>Developer's Reference Team &email-devel-ref;
- <author>Adam Di Carlo, editor
+ <author>Andreas Barth
+ <author>Adam Di Carlo
<author>Raphaël Hertzog
<author>Christian Schwarz
<author>Ian Jackson
<copyright>
<copyrightsummary>
+copyright © 2004 Andreas Barth</copyrightsummary>
+ <copyrightsummary>
copyright © 1998—2003 Adam Di Carlo</copyrightsummary>
<copyrightsummary>
copyright © 2002—2003 Raphaël Hertzog</copyrightsummary>
freeze period, since the <em>unstable</em> distribution remains in
place in parallel with <em>testing</em>.
- <sect2 id="testing">
+ <sect2>
<heading>More information about the testing distribution</heading>
+ <p>
+Packages are usually installed into the `testing' distribution after they
+have undergone some degree of testing in unstable.
<p>
-The scripts that update the <em>testing</em> distribution are run each
-day after the installation of the updated packages. They generate the
-<file>Packages</file> files for the <em>testing</em> distribution, but
-they do so in an intelligent manner trying to avoid any inconsistency
-and trying to use only non-buggy packages.
- <p>
-The inclusion of a package from <em>unstable</em> is conditional on
-the following:
-<list>
- <item>
-The package must have been available in <em>unstable</em> for several days;
-the precise number depends on the upload's urgency field. It
-is 10 days for low urgency, 5 days for medium urgency and 2 days for high
-urgency. Those delays may be doubled during a freeze;
- <item>
-It must have less release-critical bugs than the version available
-in <em>testing</em>;
- <item>
-It must be available on all architectures on which it has been
-previously built. <ref id="madison"> may be of interest to
-check that information;
- <item>
-It must not break any dependency of a package that is already available
-in <em>testing</em>;
- <item>
-The packages on which it depends must either be available in <em>testing</em>
-or they must be accepted into <em>testing</em> at the same time (and they will
-if they respect all the necessary criteria);
-</list>
- <p>
-To find out whether a package is progressing into testing or not, see the
-testing script output on the <url name="web page of the testing distribution"
-id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn>
-which is in the <package>devscripts</package> package. This utility can
-easily be used in a <manref name="crontab" section="5"> to keep one
-informed of the progression of their packages into <em>testing</em>.
- <p>
-The <file>update_excuses</file> file does not always give the precise reason
-why the package is refused, one may have to find it on their own by looking
-for what would break with the inclusion of the package. The
-<url id="&url-testing-maint;" name="testing web page"> gives some more
-information about the usual problems which may be causing such troubles.
- <p>
-Sometimes, some packages never enter <em>testing</em> because the set of
-inter-relationship is too complicated and cannot be sorted out
-by the scripts. In that case, the release manager must be
-contacted, and he will force the inclusion of the packages.
- <p>
-In general, please refer to the <url name="testing web page"
-id="&url-testing-maint;"> for more information. It also includes
-answers to some of the frequently asked questions.
-
+For more details, please see the <qref id="testing">information about the
+testing distribution</qref>.
<sect2 id="experimental">Experimental
<p>
An alternative to <em>experimental</em> is to use your personal web space
on <tt>people.debian.org</tt>.
<p>
-Please consider to use the option <bb>-v</bb> to <bb>dpkg-buildpackage</bb>
+Please consider to use the option <tt>-v</tt> to <prgn>dpkg-buildpackage</prgn>
if uploading a package to unstable to get the bugs finally closed that were
first fixed in experimental.
uploaded package fits the needs of the next point release.
<sect1 id="upload-t-p-u">
- <heading>Special case: uploads to <em>testing-proposed-updates</em></heading>
- <p>
-The testing distribution is fed with packages from unstable according to the rules
-explained in <ref id="testing">. However, the release manager may stop the testing
-scripts when he wants to freeze the distribution. In that case, you may want to
-upload to <em>testing-proposed-updates</em> to provide fixed packages during the freeze.
+ <heading>Special case: uploads to <em>testing/testing-proposed-updates</em></heading>
<p>
-Keep in mind that packages uploaded there are not automatically processed, they
-have to go through the hands of the release manager. So you'd better have a good
-reason to upload there. In order to know what a good reason is in the
-release manager's eyes, you should read the instructions that he regularly
-gives on &email-debian-devel-announce;.
- <p>
-You should not upload to <em>testing-proposed-updates</em> when you can update your
-packages through <em>unstable</em>. If you can't (for example because you have a
-newer development version in unstable), you may use it but it is recommended to ask
-the authorization of the release manager before.
+Please see the information in the <qref id="t-p-u">testing section</qref> for details.
<sect id="upload">Uploading a package
tools on Alioth (see <ref id="alioth">).
</sect>
+ <sect id="testing">
+ <heading>The testing distribution</heading>
+ <p>
+ <sect1 id="testing-basics">
+ <heading>Basics</heading>
+ <p>
+Packages are usually installed into the `testing' distribution after they
+have undergone some degree of testing in unstable.
+ <p>
+They must be in sync on all architectures and
+mustn't have dependencies that make them uninstallable; they also have to
+have generally no known release-critical bugs at the time they're
+installed into testing.
+This way, `testing' should always be close to being a release candidate.
+Please see below for details.
+ <sect1 id="testing-unstable">
+ <heading>Updates from unstable</heading>
+ <p>
+The scripts that update the <em>testing</em> distribution are run each
+day after the installation of the updated packages. They generate the
+<file>Packages</file> files for the <em>testing</em> distribution, but
+they do so in an intelligent manner trying to avoid any inconsistency
+and trying to use only non-buggy packages.
+ <p>
+The inclusion of a package from <em>unstable</em> is conditional on
+the following:
+<list>
+ <item>
+The package must have been available in <em>unstable</em> for 2, 5 or 10
+days, depending on the urgency (high, medium or low).
+Please note that the urgency is sticky, means that the highest
+urgency uploaded since the last testing transition is taken into account.
+Those delays may be doubled during a freeze, or testing transition may be
+switched off at all;
+ <item>
+It must have less release-critical bugs than the version available
+in <em>testing</em>;
+ <item>
+It must be available on all architectures on which it has been
+previously built in unstable. <ref id="madison"> may be of interest to
+check that information;
+ <item>
+It must not break any dependency of a package that is already available
+in <em>testing</em>;
+ <item>
+The packages on which it depends must either be available in <em>testing</em>
+or they must be accepted into <em>testing</em> at the same time (and they will
+if they respect all the necessary criteria);
+</list>
+ <p>
+To find out whether a package is progressing into testing or not, see the
+testing script output on the <url name="web page of the testing distribution"
+id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn>
+which is in the <package>devscripts</package> package. This utility can
+easily be used in a <manref name="crontab" section="5"> to keep one
+informed of the progression of their packages into <em>testing</em>.
+ <p>
+The <file>update_excuses</file> file does not always give the precise reason
+why the package is refused, one may have to find it on their own by looking
+for what would break with the inclusion of the package. The
+<url id="&url-testing-maint;" name="testing web page"> gives some more
+information about the usual problems which may be causing such troubles.
+ <p>
+Sometimes, some packages never enter <em>testing</em> because the set of
+inter-relationship is too complicated and cannot be sorted out
+by the scripts. See below for details.
+ <p>
+Some further dependency analysis is shown on
+<url id="http://bjorn.haxx.se/debian/"> - but be warned, they show also
+the build dependencies that are not considered by britney.
+
+ <sect2 id="outdated">
+ <heading>out-of-date</heading>
+ <p>
+For the testing migration script, "outdated" means: There are different
+versions in unstable for the release architectures (except for the
+architectures in fuckedarches; fuckedarches is an list of architectures
+that don't keep up (in update_out.py), but currently, it's empty).
+"outdated" has nothing whatsoever to do with the architectures this package
+has in testing.
+ <p>
+Consider this example:
+ <p>
+ <tt>
+ foo | alpha | arm
+---------+-------+----
+testing | 1 | -
+unstable | 1 | 2
+</tt>
+ <p>
+The package is out of date on alpha in unstable, and will not go to
+testing. And removing foo from testing would not help at all, the package
+is still out of date on alpha, and will not propagate to testing.
+ <p>
+However, if ftp-master removes a package in unstable (here on arm):
+ <p>
+ <tt>
+foo | alpha | arm | hurd-i386
+---------+-------+-----+----------
+testing | 1 | 1 | -
+unstable | 2 | - | 1
+ </tt>
+ <p>
+In this case, the package is up to date on all release architectures in
+unstable (and the extra hurd-i386 doesn't matter, as it's not a release
+architecture).
+ <p>
+Sometimes, the question is raised if it is possible to allow packages in
+that are not yet built on all architectures: No. Just plainly no. (Except
+if you maintain glibc or so.)
+
+ <sect2 id="removals">
+ <heading>Removals from testing</heading>
+ <p>
+Sometimes, a package is removed to allow another package in: This happens
+only to allow _another_ package to go in, that's ready in every other
+sense. Consider e.g. that a conflicts with the new version of b; than a may
+be removed to allow b in.
+ <p>
+Of course, there is another reason to remove a package from testing: It's
+just too buggy (and having a single RC-bug is enough to be in this state).
+
+ <sect2 id="circular">
+ <heading>circular dependencies</heading>
+ <p>
+A situation that is not handled very well by britney is if package a
+depends on the new version of package b, and vice versa.
+ <p>
+An example of this is:
+ <p>
+ <tt>
+ | testing | unstable
+--+-----------------+------------
+a | 1; depends: b=1 | 2; depends: b=2
+b | 1; depends: a=1 | 2; depends: a=2
+ </tt>
+ <p>
+Package a is not considered for update, and package b also not.
+ <p>
+Currently, this requires some manual hinting from the release masters.
+Please, send mail to debian-release@lists.debian.org if that happens to
+one of your packages.
+
+
+ <sect2>
+ <heading>influence of package in testing</heading>
+ <p>
+Generally, there is nothing that the status of a package in testing means
+for transition of the next version from unstable to testing, with two
+exceptions: If the RC-bugginess of the package goes down, it may go in
+even if it is still RC-buggy. The second exception is if the version
+of the package in testing is out of sync on the different arches: Then
+any arch might just upgrade to the version of the source package;
+however, this can happen only if the package was previously forced
+through, or the arch is in fuckedarches.
+ <p>
+In summary this means: The only influence that a package being in testing
+has on a new version of the same package is that the new version might
+go in easier.
+
+ <sect2 id="details">
+ <heading>details</heading>
+ <p>
+If you are interested in details, this is how britney works:
+ <p>
+The packages are looked at to determine whether they are valid
+candidates. This gives the "update excuses". The most common reasons
+why a package is not considered are too young, RC-bugginess and out of
+date on some arches. For this part, the release managers have hammers
+of any size to force britney to consider a package. (Also, the base
+freeze is coded in that part of britney.) (There is a similar thing
+for binary-only updates, but this is not described here. If you're
+interessted in that, please use the code.)
+ <p>
+Now, the more complex part happens: Britney tries to update testing with
+the valid candidates; first, each package alone, and then larger and even
+larger sets of packages together. Each try is accepted if sarge is not
+more uninstallable after the update as before. (Before and after this part,
+some hints are processed; but as only release masters can hint, this is
+probably not so important for you.)
+ <p>
+If you want to see more details, you can look it up on
+merkel:/org/ftp.debian.org/testing/update_out/ (or there in
+~aba/testing/update_out to see a setup with a smaller packages file). Via
+web, it's at <url
+id="http://ftp-master.debian.org/testing/update_out_code/">
+ <p>
+The hints are available via <url
+id="http://ftp-master.debian.org/testing/hints/">.
+
+
+ <sect1 id="t-p-u">
+ <heading>Direct updates to testing</heading>
+ <p>
+The testing distribution is fed with packages from unstable according to the rules
+explained above. However, in some cases, it is necessary to upload
+packages built only for testing. For that, you may want to
+upload to <em>testing-proposed-updates</em>.
+ <p>
+Keep in mind that packages uploaded there are not automatically processed, they
+have to go through the hands of the release manager. So you'd better have a good
+reason to upload there. In order to know what a good reason is in the
+release manager's eyes, you should read the instructions that he regularly
+gives on &email-debian-devel-announce;.
+ <p>
+You should not upload to <em>testing-proposed-updates</em> when you can update your
+packages through <em>unstable</em>. If you can't (for example because you have a
+newer development version in unstable), you may use it but it is recommended to ask
+the authorization of the release manager before. Even if a package is
+frozen, updates through unstable are possible, if the upload via unstable
+does not pulls an new dependency in.
+ <p>
+Version numbers are usually selected by adding the codename of the testing
+distribution and a incrementing number, like 1.2sarge1 for the first upload
+through testing-proposed-updates of the package version 1.2.
+
+
+ <sect1 id="faq">
+ <heading>Frequently asked questions</heading>
+ <p>
+
+ <sect2 id="rc">
+ <heading>What are release-critical bugs, and how do they get counted?</heading>
+ <p>
+All bugs of some higher severities are by default considered release-critical; currently, these are critical, grave and serious bugs.
+ <p>
+Such bugs are presumed to have an impact on the chances that the package will be released with the stable release of Debian: in general, if a package has open release-critical bugs filed on it, it won't get into "testing", and consequently won't be released in "stable".
+ <p>
+The "testing" bug count for a package is considered to be roughly the bug count at the last point when the "testing" version equalled the "unstable" version. The bugs tagged woody or sarge will not be counted. Bugs with the sid tag will be counted, though.
+
+
+ <sect2>
+ <heading>How could installing a package into "testing" possibly break other packages?</heading>
+ <p>
+The structure of the distribution archives is such that they can only contain one version of a package; a package is defined by its name. So, when the source package acmefoo is installed into "testing", along with its binary packages acme-foo-bin, acme-bar-bin, libacme-foo1 and libacme-foo-dev, the old version is removed.
+ <p>
+However, the old version may have provided a binary package with an old soname of a library, such as libacme-foo0. Removing the old acmefoo will remove libacme-foo0, which will break any packages which depend on it.
+ <p>
+Evidently, this mainly affects packages which provide changing sets of binary packages in different versions (in turn, mainly libraries). However, it will also affect packages upon which versioned dependencies have been declared of the ==, <= or << varieties.
+ <p>
+When the set of binary packages provided by a source package change in this way, all the packages that depended on the old binaries will have to be updated to depend on the new binaries instead. Because installing such a source package into "testing" breaks all the packages that depended on it in "testing", some care now has to be taken: all the depending packages must be updated and ready to be installed themselves so that they won't be broken, and, once everything is ready, manual intervention by the release manager or an assistant is normally required.
+ <p>
+If you are having problems with complicated groups of packages like this, contact debian-devel or debian-release for help.
+ </sect>
<chapt id="best-pkging-practices">
<heading>Best Packaging Practices</heading>
<heading>Make transition packages deborphan compliant</heading>
<p>
Deborphan is a program helping users to detect which packages can be safely
-removed from the system, ie the ones that have no packages depending on
+removed from the system, i.e. the ones that have no packages depending on
them. The default operation is to search only within the libs and oldlibs
sections, to hunt down unused libraries. But when passed the right argument,
it tries to catch other useless packages.
<p>
-For example, with --guess-dummy, tries to search all transitionnal packages
+For example, with --guess-dummy, tries to search all transitional packages
which were needed for upgrade but which can now safely be removed. For that,
it looks for the string "dummy" or "transitional" in their short
description.
<p>
-So, when you are creating ssuch a package, please make sure to add this text
+So, when you are creating such a package, please make sure to add this text
to your short description. If you are looking for example, just run:
<example>apt-cache search .|grep dummy</example> or
<example>apt-cache search .|grep transitional</example>.
<package>yada</package> is another packaging helper tool. It uses a
<file>debian/packages</file> file to auto-generate
<file>debian/rules</file> and other necessary files in the
-<file>debian/</file> subdirectory.
- <p>
-Note that <package>yada</package> is called "essentially unmaintained"
-by it's own maintainer, Charles Briscoe-Smith. As such, it can be
-considered deprecated.
+<file>debian/</file> subdirectory. The <file>debian/packages</file> file
+contains instruction to build packages and there is no need to create any
+<file>Makefile</file> files. There is possibility to
+use macro engine similar to the one used in SPECS files from RPM
+source packages.</p>
+ <p>
+For more informations see
+<tt><url id="http://yada.alioth.debian.org/" name="YADA site"></tt>.</p>
</sect1>
<sect1 id="equivs">
~ianmdlvl / developers-reference.git / blobdiff