APT CLI versioning mechanism

apt-cli-version.md

APT 3.1.x introduces a new behavior versioning mechanism, providing primarily stable command-line interfaces for scripting.

Version specification

The CLI version can be specified using --cli-version A[.B][.C].

If the B component is missing, the highest even B currently supported is selected. For example, --cli-version 3 will select 3.2 but not 3.3 in APT 3.3.x, as odd versions are development series.

If the C component is missing, all possible values are allowed.

Users may specify a development series ahead of the current release, for example, they may specify 3.3 in the 3.2 release.

Alternatively, one may use one of the next, stable, lts, donkult, classic tracks defined in the next section. This is generally not very useful, except perhaps for APT maintainers.

Library uses

A function bool APT::Configurastion::RequestVersion(std::string_view ver) is provided with the same semantics as the --cli-version.

Versioning tracks

CLI versioning corresponds to the APT version in use. APT versions have a single-digit B component, so 4.0 follows 3.9, but the 4.0 version also introduces a matching 3.10 API level, and so on for older version.

For a given APT release A.B, the following version levels are supported:

• next: A.(odd X > B) # 3.1, 3.3, 3.5, 3.7, 3.9
• latest: A.B # 3.0, 3.1, ..., 3.9
• stable: A.(even X < B) v # 3.0, 3.2, ..., 3.8
• lts: (A-1).(B+10) # 2.10, 2.11, ..., 2.19

For example, the 3.1.4 series has:

• next: 3.3
• latest: 3.1
• stable: 3.0
• lts: 2.11

Whereas 3.2.0 has:

• next: 3.3
• latest: 3.2
• stable: 3.0
• lts: 2.12

Track update policy

• The next track may continously receive breaking changes.
• The latest track may receive breaking changes if odd. Changes should move to the next track halfway into the release cycle.
• The stable and lts tracks should receive minimal changes.

Special tracks

As of APT 3.2, the following tracks are also supported:

• classic: 0.(A*10+B) - the interface used by apt-get(8) and other apt-* utilities,
• interactive-classic: (unversioned) - more similar to classic on the user interface, but features mostly matching latest

The classic track is deprecated and may be removed in the 4.0 release.

Default tracks

The default tracks are:

• for the apt(8) utility: latest.
• for the libapt-pkg library: stable
• for the other utilities: classic

The other utilities may move to the lts or stable track in 4.0.

Track release managers

The interactive-classic track is managed by DonKult, other tracks are managed by juliank.

Scope of versioning

All aspects of APT are generally in scope for versioning. Versioning is provided on a reasonable effort basis, not a best effort basis, and always subject to case-by-case consideration.

Versioning is usually not applied to:

• Output format changes that add new fields to deb822 outputs

• Output format changes that only change whitespace

• Signature verification policy. Deprecation and disabling of algorithms and key sizes and so on is managed using cut-off dates instead.

• Critical security vulnerabilities.

Feature flags

Each version maps to a set of feature flags upon which code is conditionalized. Once a CLI version is set, the set of active features is compiled. Some features may also be toggled individually by a configuration option, however, going forward, individual options are discouraged and the use of feature flags is preferred.

This will greatly reduce the number of potential combinations of feature flags from 2^n for n features to the number of tracks (for 6 features in 6 tracks, 2^6=64 vs 6), and even fewer in stable releases.