The usual workflow - quick guide
This section covers the most common ABI/API transitions.
- Change of ABI (SONAME bump) without change in API
Change of ABI and API, when the -dev package does not change name.
The work flow
- Upload your new version to experimental (and have it clear NEW)
- Ensure it builds on all architectures in testing, where it built previously.
Check the auto-generated "auto-<source>" ben tracker. If not useful (or if it does not appear) generate an applicable one and include it in your request for a transition slot (see below).
- Test rebuild reverse dependencies
- Request a transition slot from the release team (reportbug release.debian.org)
- Wait for ACK
- Upload to unstable after ACK
- NMU reverse dependencies as needed.
Please request a transition slot from the Release Team by filing a transition bug report against release.debian.org (reportbug has a template). In some cases (major transitions), it might be prudent to also send an email to debian-devel-announce, but please see the section below on that subject.
In the transition bug report, please include the list of affected source packages and what needs to be done with each of them. In some cases, a lot of binNMUs will be enough (e.g. a clean library ABI bump) though in other cases sourceful uploads are required (e.g. API change).
Please do not upload the package to unstable without approval from the release team.
If you are sending an email to d-d-a about the transition, here are some recommendations.
Reference the transition bug report. People tend to ask if you do not.
- Avoid using specific upload dates, unless they have been approved by the Release Team.
- We do not like NACK'ing a d-d-a mail on d-d-a. It just is not pretty, but it is far better than entangled transitions.
Speeding up transitions
Here are some hints to getting your transitions started and finished sooner.
- Upload to experimental.
- This will ensure your new package has cleared the NEW queue and we can promptly start the transition.
For the general case, it will also create an "auto-<source>" ben tracker.
Include a sample "ben" file in your transition mail.
See documentation about the query language here
- Mostly useful if the auto-generated one is insufficient OR does not appear.
The ben config behind the transition tracker is maintained in Git.
- Check your reverse dependencies:
- Find RC-buggy reverse dependencies.
Not in testing => not a blocker (but list them anyway, so we know).
In testing => may need NMU or RM.
- Build tests to catch FTBFS.
- Use severity important (and bump to serious when the transition starts)
- Find RC-buggy reverse dependencies.
- Find the relevant migration guides or/and patches for your reverse dependencies (if any).
- Avoid changing the name of -dev packages. It means sourceful uploads and that tends to be painfully slow.
- Provides sometimes works, but not for versioned build depends.
NB: Britney does not support versioned provides!
- Be prepared to NMU some of your reverse dependencies.
- Avoid Breaks and Replaces on the old library packages unless they are strictly necessary, because they prevent smooth updates.
- A file path conflict between the old and the new library package always necessitates adding Breaks and Replaces. Any such file path conflict violates policy §8.2 and needs to be fixed, though. Filing for a formal transition does not invoke magic that could solve this case.
How transitions work in general
For the interested, this is the extended general work flow for most transitions. It includes actions from all involved parties.
In the following, the following legend is used:
- [MTL]: Maintainer of Transitioning Library
- [MRD]: Maintainer(s) of reverse dependency (or dependencies)
- [RT]: The Release Team
- [FTP]: The FTP masters
- [AUTO]: An automated system
The general work flow is something like this.
- [MTL]: Uploads to experimental, which will generally end up in NEW
- [FTP]: Approves upload to experimental.
[AUTO]: The "auto-transitioner" usually detects the planned transition and generates a tracker at https://release.debian.org/transitions/ (under "Some planned transitions")
- [MTL]/[MRD]: Test build the reverse dependencies against the new ABI/API.
- [MTL]: Files a bug against release.debian.org requesting a transition slot with the affected reverse dependencies and the test results.
- [RT]: Reviews the request and decides an appropriate time for the transition. Usually defined as "now" or "after the current transition(s) X(, Y and Z)".
[RT]: Acks the transition, usually with a human readable confirmation.1
- [MTL]: Uploads library to unstable.
- MILESTONE: The transition is started and can become entangled.
- [MTL]: Bumps all blocking bugs to RC.
- Interleaved (repeated until all reverse dependencies are updated on all architectures in testing):
- [RT]: Schedules binNMUs for reverse dependencies that just need a rebuild
- [MRD]/[MTL]: Uploads reverse dependencies that needs to be updated for the new library version
- [AUTO]: The automatic removal from testing may remove some of the unfixed packages from testing.
- [FTP]/[AUTO]: The FTP masters or DAK's auto-decrufter will remove the old ABI/API package in unstable.
- This is automated if all reverse dependencies are successfully updated (or removed)
- This is manual if there are problems on some architectures outside testing
- [AUTO]: Britney will migrate the new library package. With smooth updates, the old library ABI may be retained in testing.
- MILESTONE: At this point, the transition will generally no longer become entangled with others.
- Without smooth updates, Britney will have to migrate all of the reverse dependencies at the same time.
- [AUTO]: Britney will migrate all reverse dependencies as they become ready.
- [AUTO]: Britney will remove the old library if it is still present in testing.
- MILESTONE: The transition is now complete.
- [RT]: Closes the release.debian.org bug.
The release team tracks the ACK for a transition using the 'confirmed' tag in the BTS. (1)