apt phasing should be documented in apt.conf(5) rather than apt_preferences(5)

[Seth Arnold]

Hello, the apt documentation on controlling apt phasing is in apt_preferences(5). However, putting the records into a file in /etc/apt/preferences.d leads to an error:

$ rg -l APT::Machine-ID -g '*.xml'
apt_2.2.2ubuntu1/doc/apt_preferences.5.xml
apt_2.3.10/doc/apt_preferences.5.xml
apt_2.3.7/doc/apt_preferences.5.xml
apt_2.1.17/doc/apt_preferences.5.xml
apt_2.3.3/doc/apt_preferences.5.xml
apt_2.3.9/doc/apt_preferences.5.xml
apt_2.4.8/doc/apt_preferences.5.xml
apt_2.2.3/doc/apt_preferences.5.xml
apt_2.5.0/doc/apt_preferences.5.xml
apt_2.4.5/doc/apt_preferences.5.xml
apt_2.3.13/doc/apt_preferences.5.xml
apt_2.2.1/doc/apt_preferences.5.xml
apt_2.3.11/doc/apt_preferences.5.xml
apt_2.3.6/doc/apt_preferences.5.xml
apt_2.1.16/doc/apt_preferences.5.xml
apt_2.3.9ubuntu0.1/doc/apt_preferences.5.xml
apt_2.5.3/doc/apt_preferences.5.xml
apt_2.4.0/doc/apt_preferences.5.xml
apt_2.3.5/doc/apt_preferences.5.xml
apt_2.2.2/doc/apt_preferences.5.xml
apt_2.3.15build1/doc/apt_preferences.5.xml
apt_2.3.15/doc/apt_preferences.5.xml
apt_2.3.8/doc/apt_preferences.5.xml
apt_2.2.4ubuntu0.1/doc/apt_preferences.5.xml
apt_2.4.3/doc/apt_preferences.5.xml
apt_2.1.18/doc/apt_preferences.5.xml

⏚ [sarnold:/etc/apt] $ sudo vim /etc/apt/preferences.d/phased-updates
[sudo] password for sarnold:
⏚ [sarnold:/etc/apt] 11s $ apt list
E: Invalid record in the preferences file /etc/apt/preferences.d/phased-updates, no Package header
⏚ [sarnold:/etc/apt] $ cat /etc/apt/preferences.d/phased-updates
// To have all your machines phase the same, set the same string in this field
// If commented out, apt will use /etc/machine-id to seed the random number generator
APT::Machine-ID "aaaabbbbccccddddeeeeffff";

// Always include phased updates
APT::Get::Always-Include-Phased-Updates "1";

// Never include phased updates
# APT::Get::Never-Include-Phased-Updates "1";

Considering how difficult it is to tell which of preferences vs conf should be used for which settings, mentioning phasing in both manpages would be very kind. However, both manpages should be clear about which one is actually correct.

Thanks

[Launchpad Janitor (janitor)]

Status changed to 'Confirmed' because the bug affects multiple users.

[Julian Andres Klode (juliank)]

I think it's better to ship slightly wrong documentation in the wrong place than to ship the right documentation in a language users don't understand, so that's why they don#t get updated in stable releases.

I do not think the apt.conf manual page is a good idea in the first place. These options belong to upgrade commands now, so they should be documented in apt-upgrade once that is written (which houses apt upgrade, apt-get upgrade, apt dist-upgrade, apt full-upgrade, apt-get dist-upgrade docs).

Because the problem is that apt.conf(5) doesn't really have a clear place. Any commandline option can be specified in the config files too, but they're only relevant to their individual commands, so they should be documented alongside their commands. So like apt.conf serves to describe the file format and common options not exposed via command-line flags.

So like if we add a -4 argument corresponding to Acquire::ForceIPv4, it should not be listed in apt.conf anymore as it's in all manual pages that involve downloading, if that makes sense.

And phasing is in apt_preferences because it was implemented using preferences. It no longer is, it's now part of the upgrade code. It certainly does not belong in apt.conf, that's a last resort for stuff we just can't seem to fit in anywhere else.

The whole documentation is horrible.