[Bug 2003759] Re: apt phasing should be documented in apt.conf(5) rather than apt_preferences(5)

[Julian Andres Klode]

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.

-- 
You received this bug notification because you are a member of Ubuntu
Foundations Bugs, which is subscribed to apt in Ubuntu.
https://bugs.launchpad.net/bugs/2003759

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

Status in apt package in Ubuntu:
  Confirmed

Bug description:
  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

To manage notifications about this bug go to:
https://bugs.launchpad.net/ubuntu/+source/apt/+bug/2003759/+subscriptions