From d7a1ea13683f3ff993377f1caab86a4a149440dd Mon Sep 17 00:00:00 2001 From: aba Date: Sat, 25 Sep 2004 15:32:27 +0000 Subject: [PATCH] updated information about testing git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2599 313b444b-1b9f-4f58-a734-7bb04f332e8d --- debian/changelog | 1 + developers-reference.sgml | 325 +++++++++++++++++++++++++++++--------- 2 files changed, 253 insertions(+), 73 deletions(-) diff --git a/debian/changelog b/debian/changelog index 2b06efe..3b80be6 100644 --- a/debian/changelog +++ b/debian/changelog @@ -22,6 +22,7 @@ developers-reference (3.3.5) unstable; urgency=low - add hint about -v to experimental. Closes: #232930 - update information about yada. Closes: #217956 - urgency is sticky. Closes: #261914 + - updated information about testing distribution. * Matt Zimmerman - Security uploads get urgency=high - Be even more explicit about not uploading security updates diff --git a/developers-reference.sgml b/developers-reference.sgml index 1311438..5351168 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + @@ -953,64 +953,14 @@ Note that development under unstable continues during the freeze period, since the unstable distribution remains in place in parallel with testing. - + More information about the testing distribution +

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

-The scripts that update the testing distribution are run each -day after the installation of the updated packages. They generate the -Packages files for the testing distribution, but -they do so in an intelligent manner trying to avoid any inconsistency -and trying to use only non-buggy packages. -

-The inclusion of a package from unstable is conditional on -the following: - - -The package must have been available in unstable 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; 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; - -It must have less release-critical bugs than the version available -in testing; - -It must be available on all architectures on which it has been -previously built. may be of interest to -check that information; - -It must not break any dependency of a package that is already available -in testing; - -The packages on which it depends must either be available in testing -or they must be accepted into testing at the same time (and they will -if they respect all the necessary criteria); - -

-To find out whether a package is progressing into testing or not, see the -testing script output on the , or use the program grep-excuses -which is in the devscripts package. This utility can -easily be used in a to keep one -informed of the progression of their packages into testing. -

-The update_excuses 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 - gives some more -information about the usual problems which may be causing such troubles. -

-Sometimes, some packages never enter testing 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. -

-In general, please refer to the for more information. It also includes -answers to some of the frequently asked questions. - +For more details, please see the information about the +testing distribution. Experimental

@@ -1761,23 +1711,9 @@ uploading to stable/stable-proposed-updates, so that the uploaded package fits the needs of the next point release. - Special case: uploads to testing-proposed-updates -

-The testing distribution is fed with packages from unstable according to the rules -explained in . 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 testing-proposed-updates to provide fixed packages during the freeze. + Special case: uploads to testing/testing-proposed-updates

-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;. -

-You should not upload to testing-proposed-updates when you can update your -packages through unstable. 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 testing section for details. Uploading a package @@ -3147,6 +3083,249 @@ Collaborative maintenance can often be further eased with the use of tools on Alioth (see ). + + The testing distribution +

+ + Basics +

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

+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. + + Updates from unstable +The scripts that update the testing distribution are run each +day after the installation of the updated packages. They generate the +Packages files for the testing distribution, but +they do so in an intelligent manner trying to avoid any inconsistency +and trying to use only non-buggy packages. +

+The inclusion of a package from unstable is conditional on +the following: + + +The package must have been available in unstable 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; + +It must have less release-critical bugs than the version available +in testing; + +It must be available on all architectures on which it has been +previously built in unstable. may be of interest to +check that information; + +It must not break any dependency of a package that is already available +in testing; + +The packages on which it depends must either be available in testing +or they must be accepted into testing at the same time (and they will +if they respect all the necessary criteria); + +

+To find out whether a package is progressing into testing or not, see the +testing script output on the , or use the program grep-excuses +which is in the devscripts package. This utility can +easily be used in a to keep one +informed of the progression of their packages into testing. +

+The update_excuses 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 + gives some more +information about the usual problems which may be causing such troubles. +

+Sometimes, some packages never enter testing because the set of +inter-relationship is too complicated and cannot be sorted out +by the scripts. See below for details. +

+Some further dependency analysis is shown on + - but be warned, they show also +the build dependencies that are not considered by britney. + + + out-of-date +

+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. +

+Consider this example: +

+ + foo | alpha | arm +---------+-------+---- +testing | 1 | - +unstable | 1 | 2 + +

+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. +

+However, if ftp-master removes a package in unstable (here on arm): +

+ +foo | alpha | arm | hurd-i386 +---------+-------+-----+---------- +testing | 1 | 1 | - +unstable | 2 | - | 1 + +

+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). +

+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.) + + + Removals from testing +

+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. +

+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). + + + circular dependencies +

+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. +

+An example of this is: +

+ + | testing | unstable +--+-----------------+------------ +a | 1; depends: b=1 | 2; depends: b=2 +b | 1; depends: a=1 | 2; depends: a=2 + +

+Package a is not considered for update, and package b also not. +

+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. + + + + influence of package in testing +

+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. +

+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. + + + details +

+If you are interested in details, this is how britney works: +

+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.) +

+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.) +

+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 +

+The hints are available via . + + + + Direct updates to testing +

+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 testing-proposed-updates. +

+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;. +

+You should not upload to testing-proposed-updates when you can update your +packages through unstable. 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. +

+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. + + + + Frequently asked questions +

+ + + What are release-critical bugs, and how do they get counted? +

+All bugs of some higher severities are by default considered release-critical; currently, these are critical, grave and serious bugs. +

+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". +

+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. + + + + How could installing a package into "testing" possibly break other packages? +

+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. +

+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. +

+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. +

+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. +

+If you are having problems with complicated groups of packages like this, contact debian-devel or debian-release for help. + Best Packaging Practices -- 2.30.2