Phased update configuration flags not documented in apt.conf(5)

[Robie Basak]

Hi,

https://discourse.ubuntu.com/t/phased-updates-in-apt-in-21-04/20345 describes Dir::Etc::machine-id, APT::Get::Always-Include-Phased-Updates and APT::Get::Never-Include-Phased-Updates. I expected these to be documented in apt.conf(5) which I treat as a definitive reference to configuration options, but they aren't there.

[Julian Andres Klode (juliank)]

Just to be clear: apt.conf(5) is not the definitive source, that is (fsvo reference) in /use/share/doc/examples/configure-index. The manual page only documents popular options whereas the index lists them all (apt test suite type checks against it).

Phased updates are documented in apt_preferences, but the documentation has not been updated for the new implementation either.

They are also, and primarily, documented in the discourse post as that was requested as the preferred documentation medium.

[Robie Basak (racb)]

That's not really discoverable as a reference though. I wouldn't expect "examples" to contain a definitive reference, and nor a Discourse post about a feature that as far as I know isn't pointed to from any definitive documentation. Same with apt_preferences - I do expect to find information about scoring and the syntax of preferences.d/ files in there, but if I want a reference to a configuration option, it's not obvious to look there.

[Robie Basak (racb)]

Looking at apt.conf(5), it does read as if it's the definitive reference, too, and the examples file is just an example.

[Julian Andres Klode (juliank)]

Yeah many options are not really for end users though so it's not all encompassing.