Debian Unstable to Testing Migration with Dak

This article explains how the Debian Archive Kit (dak) coordinates the automated transition of software packages from Debian's unstable repository (Sid) into the testing distribution. It explores the interplay between dak and the migration engine Britney, details the specific health and stability criteria a package must meet before being promoted, and outlines how coordinated multi-package transitions are safely executed to keep the testing suite stable and installable.

The Roles of Dak and Britney

In the Debian infrastructure, archive operations on ftp-master are driven by dak (Debian Archive Kit). While dak handles core repository maintenance—such as package ingestion, metadata generation, and database updates—it delegates the mathematical and logical validation of testing migrations to a dedicated sub-program called Britney (specifically Britney2).

During the migration pipeline, dak exports the state of both the unstable and testing suites into structured files. Britney reads these inputs, evaluates candidates against release criteria, computes dependency graphs, and generates a list of approved package transitions. Once Britney finishes its run, dak executes the results by updating the database references and moving the approved binaries and source packages into the testing archive.

Core Migration Criteria

For dak and Britney to allow a package to enter testing, the package must meet strict quality checks:

  1. Quarantine (Age Requirement): The package must sit in unstable for a designated number of days without being superseded by a newer upload. The duration depends on the package upload urgency:
    • High urgency: 2 days
    • Medium urgency: 5 days
    • Low urgency: 10 days
  2. Build Availability (Arch Parity): The new version must be successfully compiled and built across all release architectures supported by Debian. If a package builds on amd64 but fails on arm64, the entire migration is halted.
  3. No New Release-Critical (RC) Bugs: The package must not introduce new RC bugs (bugs with severities of serious, grave, or critical in the Debian Bug Tracking System). It is permissible for a package to migrate if it has an existing RC bug that is also present in testing, provided no new RC bugs were introduced.
  4. Co-Installability: Migrating the package must not render existing packages in testing uninstallable. Britney verifies that all runtime dependencies (Depends, Pre-Depends) can be satisfied by packages already present in testing or migrating simultaneously.

Coordinated Group Migrations and Transitions

When libraries undergo ABI/API changes (soname transitions), updating a single package would immediately break reverse dependencies. Britney handles these events through smooth updates and composite migration items:

  • Group Migrations: If package A depends on a new version of library B, neither can migrate alone. Britney analyzes the dependency graph to find a minimal set of packages that can migrate together safely.
  • Smooth Updates: For shared libraries, the older binary packages can occasionally remain in testing temporarily while the new source package and its associated binaries migrate. This allows reverse dependencies to be rebuilt against the new library without breaking currently installed applications.

Manual Overrides and Release Team Hints

When automatic dependency resolution cannot solve circular conflicts or massive library transitions, the Debian Release Team intervenes using manual hints. These hints instruct Britney how to process tricky packages:

  • unblock / block: Explicitly allows or prevents a package from migrating, often used during the pre-release freeze.
  • easy: Informs Britney to try migrating an explicit group of packages simultaneously.
  • remove: Drops an outdated, unmaintained, or buggy package from testing to allow the rest of the dependency graph to migrate smoothly.

Archive Finalization

Once Britney concludes its evaluation and outputs the valid transaction list, dak runs its suite synchronization steps. The database pointers for the testing distribution are updated to reference the new package versions, older versions are cleared out from testing (unless kept for a smooth transition), and the suite's metadata files (Packages, Sources, and InRelease) are regenerated and cryptographically signed. The testing repository is then ready for public mirroring.