Bug#864017: release-notes: Assumes /etc/apt/sources.list is used (and not /etc/apt/sources.list.d/*.list or deb822) [general]
Paul Gevers wrote:
>>> we mean by "APT source-list files", if only by pointing at
>>> sources.list(5).
>>
>> I wanted to link to that man page as well, so let's find a place. I'm
>> nearly of to bed now, so if you find a good spot before I do tomorrow,
>> don't hesitate to mail.
>
> I have added a link to the manpages (3 places), but I am not totally
> happy with how it reads.
>
> What do you think?
I don't know whether we're "allowed" to link to manpages.d.o here; the
only other place I see a man page pointer is in whats-new.dbk, which
just says
See the <systemitem role="package">cryptsetup</systemitem> manpage
On the other hand if we *are* going to point at manpages.d.o there are
probably lots of other places where it might help.
Reading through the patch:
> From 710a6ac851e47e6952087aec89a5b7e8397cf9be Mon Sep 17 00:00:00 2001
> From: Paul Gevers <elbrus@debian.org>
> Date: Sun, 24 Mar 2019 20:31:48 +0100
> Subject: [PATCH] Generalize use of APT source-list files
>
> Closes: #864017
> ---
> en/old-stuff.dbk | 36 ++++++++++----------
> en/upgrading.dbk | 85 +++++++++++++++++++++++++-----------------------
> 2 files changed, 63 insertions(+), 58 deletions(-)
>
> diff --git a/en/old-stuff.dbk b/en/old-stuff.dbk
> index 0a53d737..ec26ca91 100644
> --- a/en/old-stuff.dbk
> +++ b/en/old-stuff.dbk
> @@ -27,14 +27,14 @@ upgraded to the latest &oldreleasename; point release.
> </section>
>
> <section id="old-sources">
> -<title>Checking your sources list</title>
> +<title>Checking your APT source-list files</title>
> <para>
> -If any of the lines in your <filename>/etc/apt/sources.list</filename>
> -refer to <quote><literal>stable</literal></quote>, it effectively
> -points to &releasename; already. This might not be what you want if
> -you are not ready yet for the upgrade. If you have already run
> -<command>apt update</command>, you can still get back without
> -problems by following the procedure below.
> + If any of the lines in your APT source-list files (see <ulink
> + url="https://manpages.debian.org/&releasename;/apt/sources.list.5.en.html";>sources.list(5)</ulink>)
> + refer to <quote><literal>stable</literal></quote>, it effectively points to
> + &releasename; already. This might not be what you want if you are not ready
> + yet for the upgrade. If you have already run <command>apt update</command>,
> + you can still get back without problems by following the procedure below.
> </para>
Instead of trying to cram this into parentheses we should explain it
more fully the first time we mention it:
<para>
The main configuration file that APT uses to decide what sources it should
download packages from is <filename>/etc/apt/sources.list</filename>, but
it can also use files in the <filename>/etc/apt/sources.list.d/</filename>
directory - for details see <ulink
url="https://manpages.debian.org/&releasename;/apt/sources.list.5.html";>sources.list(5)</ulink>.
If your system is using multiple source-list files then you will need to ensure
they stay consistent.
</para>
<para>
If any of your APT source-list files contain references to
<quote><literal>stable</literal></quote>, this is effectively pointing to
&releasename; already. This might not be what you want if you are not yet
ready for the upgrade. If you have already run <command>apt update</command>,
you can still get back without problems by following the procedure below.
</para>
Note that I've subtracted the ".en" component from the manpage URL;
but it's possible that the URL should be defined in release-notes.ent
instead.
Oh, wait, I hadn't realised that old-stuff.dbk is only alphabetically
the first section; it gets turned into an appendix. So instead the
paragraph giving the full explanation should go in upgrading.dbk, and
then this paragraph in old-stuff.dbk should just refer back to that:
If any of your APT source-list files (see <xref linkend=???"/>) contain
references to <quote><literal>stable</literal></quote>, this is effectively pointing to
> <para>
> If you have also already installed packages from &releasename;, there probably
> @@ -43,28 +43,28 @@ that case you will have to decide for yourself whether you want to continue or
> not. It is possible to downgrade packages, but that is not covered here.
> </para>
> <para>
> -Open the file <filename>/etc/apt/sources.list</filename> with your favorite
> + Open the relevant APT source-list file, e.g.
> + <filename>/etc/apt/sources.list</filename>, with your favorite
> editor (as <literal>root</literal>) and check all lines beginning with
It might be a good idea to rearrange this sentence:
As root, open the relevant APT source-list file (such as
<filename>/etc/apt/sources.list</filename>) with your favorite
editor, and check all lines beginning with
> <literal>deb http:</literal>, <literal>deb https:</literal>,
> -<literal>deb tor+http:</literal>, <literal>deb tor+https:</literal> or
> -<literal>deb ftp:</literal> for a reference to
> +<literal>deb tor+http:</literal>, <literal>deb tor+https:</literal>,
> +<literal>URIs: http:</literal>,
> +<literal>URIs: https:</literal>,
> +<literal>URIs: tor+http:</literal> or <literal>URIs: tor+https:</literal>
> +for a reference to
> <quote><literal>stable</literal></quote>. If you find any, change
> <literal>stable</literal> to <literal>&oldreleasename;</literal>.
> </para>
> -<note>
> - <para>
> - Lines in sources.list starting with <quote>deb ftp:</quote> and pointing to debian.org
> - addresses should be changed into <quote>deb http:</quote> lines.
> - </para>
> -</note>
> <para>
> -If you have any lines starting with <literal>deb file:</literal>, you will have
> + If you have any lines starting with <literal>deb file:</literal> or
> + <literal>URIs: file:</literal>, you will have
> to check for yourself if the location they refer to contains an
> &oldreleasename; or a &releasename; archive.
> </para>
I've just noticed: "contains AN &oldreleasename;"? There has only
been one releasename beginning with a vowel, and that was Debian 4.0
"Etch"!
(The fact that this is an issue is one of the reasons I'm not keen on
these entities.)
[...]
> diff --git a/en/upgrading.dbk b/en/upgrading.dbk
> index a22924f3..54a6eb9f 100644
> --- a/en/upgrading.dbk
> +++ b/en/upgrading.dbk
> @@ -290,12 +290,14 @@ $ apt-forktracer | sort
> </para>
> <para>
> Because of this you should review if there are any pending actions in the
> - package manager <command>aptitude</command>. If a package is scheduled for
> - removal or update in the package manager, it might negatively impact the
> - upgrade procedure. Note that correcting this is only possible if your
> - <filename>sources.list</filename> still points to <emphasis>&oldreleasename;</emphasis>
> - and not to <emphasis>stable</emphasis> or <emphasis>&releasename;</emphasis>; see <xref
> - linkend="old-sources"/>.
> + package manager <command>aptitude</command>. If a package is scheduled
> + for removal or update in the package manager, it might negatively impact
> + the upgrade procedure. Note that correcting this is only possible if
> + your APT source-list files, i.e. the files described in the <ulink
> + url="https://manpages.debian.org/&releasename;/apt/sources.list.5.en.html";>sources.list(5)</ulink>
> + manpage, still point to <emphasis>&oldreleasename;</emphasis> and not to
> + <emphasis>stable</emphasis> or <emphasis>&releasename;</emphasis>; see
> + <xref linkend="old-sources"/>.
> </para>
Okay, *this* chapter is the first one to mention APT source-list
files, and therefore the most natural chapter to put an explanation
in. Unfortunately, this paragraph would be a really awkward place to
have to do it. One possible solution would be to reverse the order of
two subsections: move one or more of the later paragraphs to be before
this one, and make sure the definition is given there instead.
So this becomes just:
<para>
Because of this you should review if there are any pending actions in the
package manager <command>aptitude</command>. If a package is scheduled
for removal or update in the package manager, it might negatively impact
the upgrade procedure. Note that correcting this is only possible if
your APT source-list files (see above) still point to
<emphasis>&oldreleasename;</emphasis> and not to <emphasis>stable</emphasis> or
<emphasis>&releasename;</emphasis>; see <xref linkend="old-sources"/>.
</para>
Then we move... probably *both* "proposed-updates" and
"unofficial-sources" to be before "review-actions", and insert the
longwinded definition of "APT source-list files" there.
Or maybe they should both be subsections of one section, with an extra
introductory paragraph in common...
...sorry, the more I look at it the more I think we should rip it all
out and start again. *Everything* in section 4.2 is about getting the
package manager straightened out; so the stuff at the start of 4.3 is
in the wrong place.
> <section id="upgrade-process">
> - <title>Preparing sources for APT</title>
> + <title>Preparing APT source-list files</title>
> <para>
> Before starting the upgrade you must set up <systemitem
> - role="package">apt</systemitem>'s configuration file for package lists,
> - <filename>/etc/apt/sources.list</filename>.
> + role="package">apt</systemitem>'s configuration file(s) for package lists,
> + <filename>/etc/apt/sources.list</filename> and files under
> + <filename>/etc/apt/sources.list.d/</filename> (see <ulink
> + url="https://manpages.debian.org/&releasename;/apt/sources.list.5.en.html";>sources.list(5)</ulink>).
> </para>
This would make a plausible place to put the expansion if it hasn't
already been done, but I'm sorry, I'm losing track...
> <para>
> <systemitem role="package">apt</systemitem> will consider all packages that can
> - be found via any <quote><literal>deb</literal></quote> line, and install the package with the
> - highest version number, giving priority to the first line in the
> - file (thus where you have multiple mirror locations, you'd typically first name a local
> + be found via any configured archive, and install the package with the
> + highest version number, giving priority to the first entry in the
> + files (thus where you have multiple mirror locations, you'd typically first name a local
> hard disk, then <acronym>CD-ROM</acronym>s, and then remote mirrors).
> </para>
>
> @@ -528,16 +532,16 @@ $ apt-forktracer | sort
> </para>
> <para>
> Again, after adding your new sources, disable the previously existing
> - <quote><literal>deb</literal></quote> lines.
> + archive entries.
> </para>
> </section>
>
> <section id="localmirror">
> <title>Adding APT sources for a local mirror</title>
> <para>
> - Instead of using HTTP package mirrors, you may wish to modify
> - <filename>/etc/apt/sources.list</filename> to use a mirror on a local disk
> - (possibly mounted over <acronym>NFS</acronym>).
> + Instead of using HTTP package mirrors, you may wish to modify the APT
> + source-list files to use a mirror on a local disk (possibly mounted over
> + <acronym>NFS</acronym>).
> </para>
Or for improved futureproofing, "Instead of remote package mirrors".
Sorry, I've run out of coffee! I'll have another look at this
tomorrow.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: