Bug#864017: release-notes: Assumes /etc/apt/sources.list is used (and not /etc/apt/sources.list.d/*.list or deb822) [general]

[Niels Thykier]

Package: release-notes
Severity: minor

Incidentally, the release-notes mention /etc/apt/sources.list plenty
of times but never /etc/apt/sources.list.d/*.list files; and soon
we'll also have the option of deb822-style .sources files - see the
sources.list(5) in stretch. We'll need to come up with a generic term
and use that instead; I'd suggest "APT source-list files".

[Debian Bug Tracking System]

tags -1 patch

Bug #864017 [release-notes] release-notes: Assumes /etc/apt/sources.list is used (and not /etc/apt/sources.list.d/*.list or deb822) [general]
Added tag(s) patch.

[Paul Gevers]

Control: tags -1 patch

Post by Niels Thykier
Package: release-notes
Severity: minor

Incidentally, the release-notes mention /etc/apt/sources.list plenty
of times but never /etc/apt/sources.list.d/*.list files; and soon
we'll also have the option of deb822-style .sources files - see the
sources.list(5) in stretch. We'll need to come up with a generic term
and use that instead; I'd suggest "APT source-list files".

I gave this a first shot. What do you think of the attached patch
(should we do this via Salsa merge requests)?

Paul

[Justin B Rye]

Post by Paul Gevers

Incidentally, the release-notes mention /etc/apt/sources.list plenty
of times but never /etc/apt/sources.list.d/*.list files; and soon
we'll also have the option of deb822-style .sources files - see the
sources.list(5) in stretch. We'll need to come up with a generic term
and use that instead; I'd suggest "APT source-list files".

I gave this a first shot. What do you think of the attached patch
(should we do this via Salsa merge requests)?

(I know nothing of git, and am therefore finding salsa considerably
harder to use than the old alioth setup, but I'm hoping to get it
worked out in time to contribute with the release notes.)

All of the changes in your diff look good to me, though there's a typo

Post by Paul Gevers
<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.
+ Lines in APT source-list files starting with <literal>deb ftp:</literal> or
+ <literal>URIs: ftp:</literal>and pointing to debian.org

^
extra space needed

More importantly, the FTP servers were shut down in April 2017, so
this update was required for Jessie-to-Stretch, wasn't it? At any
rate, I find it hard to imagine very many machines as cobwebby as this
would be using a deb822-format APT config with "URIs: ftp:"!

Also, when we first mention APT configuration we need to set out what
we mean by "APT source-list files", if only by pointing at
sources.list(5).

[Paul Gevers]

Hi Justin,

Post by Justin B Rye

Post by Paul Gevers

Incidentally, the release-notes mention /etc/apt/sources.list plenty
of times but never /etc/apt/sources.list.d/*.list files; and soon
we'll also have the option of deb822-style .sources files - see the
sources.list(5) in stretch. We'll need to come up with a generic term
and use that instead; I'd suggest "APT source-list files".

I gave this a first shot. What do you think of the attached patch
(should we do this via Salsa merge requests)?

(I know nothing of git, and am therefore finding salsa considerably
harder to use than the old alioth setup, but I'm hoping to get it
worked out in time to contribute with the release notes.)

Have you already looked at the web interface for commenting on merge
requests? No knowledge of git required what so ever.

Post by Justin B Rye
All of the changes in your diff look good to me, though there's a typo

Post by Paul Gevers
<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.
+ Lines in APT source-list files starting with <literal>deb ftp:</literal> or
+ <literal>URIs: ftp:</literal>and pointing to debian.org

^
extra space needed

Fixed (updated patch attached for the changes in the previous bug as well).

Post by Justin B Rye
More importantly, the FTP servers were shut down in April 2017, so
this update was required for Jessie-to-Stretch, wasn't it? At any
rate, I find it hard to imagine very many machines as cobwebby as this
would be using a deb822-format APT config with "URIs: ftp:"!

So, should we drop that paragraph altogether? I was wondering about that
as well.

Post by Justin B Rye
Also, when we first mention APT configuration we need to set out what
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.

Paul

[Paul Gevers]

Hi,

Post by Paul Gevers

Post by Justin B Rye
Also, when we first mention APT configuration we need to set out what
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?

Paul

[Justin B Rye]

Post by Paul Gevers

Post by Paul Gevers

Post by Justin B Rye
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.

Post by Paul Gevers
From 710a6ac851e47e6952087aec89a5b7e8397cf9be Mon Sep 17 00:00:00 2001
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

Post by Paul Gevers
<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

Post by Paul Gevers
<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.)

[...]

Post by Paul Gevers
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.

Post by Paul Gevers
<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...

Post by Paul Gevers
<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.

[Justin B Rye]

Post by Justin B Rye
Sorry, I've run out of coffee! I'll have another look at this
tomorrow.

I'm still only running on cheap freeze-dried instant coffee, so the
attached patch will probably still need work, but I think the
reordering of paragraphs makes sense.

Post by Justin B Rye
diff --git a/en/old-stuff.dbk b/en/old-stuff.dbk
index 0a53d737..3d1b70ed 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.html">sources.list(5)</ulink>)
+ 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>

I've let this keep a fuller explanation instead of a crossreference,
partly because I haven't figured out how crossreferences work yet.

[,,,]

Post by Justin B Rye
index a22924f3..d241de1f 100644
--- a/en/upgrading.dbk
+++ b/en/upgrading.dbk
@@ -244,16 +244,26 @@
</section>
<section id="system-status">
- <title>Checking system status</title>
+ <title>Checking APT configuration status</title>

"System" could mean anything; all the following checks deal with the
status of the package management system in particular.

Post by Justin B Rye
<para>
- The upgrade process described in this chapter has been designed for upgrades
- from <quote>pure</quote> &oldreleasename; systems without third-party packages.
- For the greatest reliability of the
- upgrade process, you may wish to remove third-party packages from your system
- before you begin upgrading.
+ The upgrade process described in this chapter has been designed for
+ <quote>pure</quote> Debian stable systems. If your APT configuration mentions
+ additional sources besides &oldreleasename, or if you have installed packages
+ from other releases or from third parties, then to ensure a reliable upgrade
+ process you may wish to begin by removing these complicating factors.
</para>
<para>
- Below there are two methods for finding such packages by using either
+ 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>

Inserting the main "first" introduction of the concept of APT
sources-list files, and adding the point that having a whole
collection of different /etc/apt/sources.list.d/*.list files pointing
at different releases is a bad idea.

Post by Justin B Rye
+ <para>
+ Below there are two methods for finding installed packages that
+ did not come from Debian, using either
<command>aptitude</command> or <command>apt-forktracer</command>. Please
note that neither of them are 100% accurate (e.g. the aptitude example
will list packages that were once provided by Debian but no longer are, such as
old kernel packages).<screen>

Incidentally, why is it bad that aptitude will detect the fact you've
got an obsolete kernel installed? On a stable system, it must be:
* a homebrew kernel-package; or
* an ancient relic from &oldrelease; or at least
* a leftover from an old point release;
and any of these would be things you should consider
removing/replacing before the upgrade, i.e. a "true positive".

[V***@csiro.au]

Post by Justin B Rye

Post by Justin B Rye
Sorry, I've run out of coffee! I'll have another look at this
tomorrow.

I'm still only running on cheap freeze-dried instant coffee, so the
attached patch will probably still need work, but I think the
reordering of paragraphs makes sense.

Post by Justin B Rye
diff --git a/en/old-stuff.dbk b/en/old-stuff.dbk
index 0a53d737..3d1b70ed 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.html">sources.list(5)</ulink>)
+ 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>

I've let this keep a fuller explanation instead of a crossreference,
partly because I haven't figured out how crossreferences work yet.
[,,,]

Post by Justin B Rye
index a22924f3..d241de1f 100644
--- a/en/upgrading.dbk
+++ b/en/upgrading.dbk
@@ -244,16 +244,26 @@
</section>
<section id="system-status">
- <title>Checking system status</title>
+ <title>Checking APT configuration status</title>

"System" could mean anything; all the following checks deal with the
status of the package management system in particular.

Post by Justin B Rye
<para>
- The upgrade process described in this chapter has been designed for upgrades
- from <quote>pure</quote> &oldreleasename; systems without third-party packages.
- For the greatest reliability of the
- upgrade process, you may wish to remove third-party packages from your system
- before you begin upgrading.
+ The upgrade process described in this chapter has been designed for
+ <quote>pure</quote> Debian stable systems. If your APT configuration mentions
+ additional sources besides &oldreleasename, or if you have installed packages
+ from other releases or from third parties, then to ensure a reliable upgrade
+ process you may wish to begin by removing these complicating factors.
</para>
<para>
- Below there are two methods for finding such packages by using either
+ 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>

Inserting the main "first" introduction of the concept of APT
sources-list files, and adding the point that having a whole
collection of different /etc/apt/sources.list.d/*.list files pointing
at different releases is a bad idea.

Post by Justin B Rye
+ <para>
+ Below there are two methods for finding installed packages that
+ did not come from Debian, using either
<command>aptitude</command> or <command>apt-forktracer</command>. Please
note that neither of them are 100% accurate (e.g. the aptitude example
will list packages that were once provided by Debian but no longer are, such as
old kernel packages).<screen>

Incidentally, why is it bad that aptitude will detect the fact you've
* a homebrew kernel-package; or
* an ancient relic from &oldrelease; or at least
* a leftover from an old point release;
and any of these would be things you should consider
removing/replacing before the upgrade, i.e. a "true positive".
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff --git a/en/old-stuff.dbk b/en/old-stuff.dbk
index 0a53d737..3d1b70ed 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.html">sources.list(5)</ulink>)
+ 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>
<para>
If you have also already installed packages from &releasename;, there probably
@@ -43,28 +43,26 @@ 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
-editor (as <literal>root</literal>) 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
-<quote><literal>stable</literal></quote>. If you find any, change
-<literal>stable</literal> to <literal>&oldreleasename;</literal>.
+ 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>,
+ <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
-to check for yourself if the location they refer to contains an
-&oldreleasename; or a &releasename; archive.
+ 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 a
+ &oldreleasename; or &releasename; archive.
</para>
<important>
<para>
- Do not change any lines that begin with <literal>deb cdrom:</literal>.
+ Do not change any lines that begin with <literal>deb cdrom:</literal> or
+ <literal>URIs: cdrom:</literal>.
Doing so would invalidate the line and you would have to
run <command>apt-cdrom</command> again. Do not be alarmed if a
<literal>cdrom:</literal> source line refers to <quote><literal>unstable</literal></quote>.
diff --git a/en/upgrading.dbk b/en/upgrading.dbk
index a22924f3..d241de1f 100644
--- a/en/upgrading.dbk
+++ b/en/upgrading.dbk
@@ -244,16 +244,26 @@
</section>
<section id="system-status">
- <title>Checking system status</title>
+ <title>Checking APT configuration status</title>
<para>
- The upgrade process described in this chapter has been designed for upgrades
- from <quote>pure</quote> &oldreleasename; systems without third-party packages.
- For the greatest reliability of the
- upgrade process, you may wish to remove third-party packages from your system
- before you begin upgrading.
+ The upgrade process described in this chapter has been designed for
+ <quote>pure</quote> Debian stable systems. If your APT configuration mentions
+ additional sources besides &oldreleasename, or if you have installed packages
+ from other releases or from third parties, then to ensure a reliable upgrade
+ process you may wish to begin by removing these complicating factors.
</para>
<para>
- Below there are two methods for finding such packages by using either
+ 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>
+ Below there are two methods for finding installed packages that
+ did not come from Debian, using either
<command>aptitude</command> or <command>apt-forktracer</command>. Please
note that neither of them are 100% accurate (e.g. the aptitude example
will list packages that were once provided by Debian but no longer are, such as
@@ -275,6 +285,39 @@ $ apt-forktracer | sort
instructions in <xref linkend="old-upgrade"/>.
</para>
+ <section id="proposed-updates">
+ <title>The proposed-updates section</title>
+ <para>
+ If you have listed the <literal>proposed-updates</literal> section in
+ your APT source-list files, you should remove it before
+ attempting to upgrade your system. This is a precaution to reduce the
+ likelihood of conflicts.
+ </para>
+ </section>
+
+ <section id="unofficial-sources">
+ <title>Unofficial sources</title>
+ <para>
+ If you have any non-Debian packages on your system, you should be aware
+ that these may be removed during the upgrade because of conflicting
+ dependencies. If these packages were installed by adding an extra
+ package archive in your APT source-list files, you should check if that
+ archive also offers packages compiled for &releasename; and change the
+ source item accordingly at the same time as your source items for Debian
+ packages.
+ </para>
+ <para>
+ Some users may have <emphasis>unofficial</emphasis> backported <quote>newer</quote> versions of packages that
+ <emphasis>are</emphasis> in Debian installed on their &oldreleasename; system. Such
+ packages are most likely to cause problems during an upgrade as they may result
+ in file conflicts<footnote><para> Debian's package management system normally
+ does not allow a package to remove or replace a file owned by another package
+ unless it has been defined to replace that package. </para> </footnote>.
+ <xref linkend="trouble"/> has some information on how to deal with file
+ conflicts if they should occur.
+ </para>
+ </section>
+
<section id="review-actions">
<title>Review actions pending in aptitude if you use that package manager</title>
<programlisting condition="fixme">
@@ -290,12 +333,12 @@ $ 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 still point to <emphasis>&oldreleasename;</emphasis>
+ and not to <emphasis>stable</emphasis> or <emphasis>&releasename;</emphasis>; see
+ <xref linkend="old-sources"/>.
</para>
<para>
To perform this review, launch <command>aptitude</command> in full-terminal mode and
@@ -381,59 +424,25 @@ $ apt-forktracer | sort
</para>
<para>
If there is anything you need to fix, it is best to make sure your
- <filename>sources.list</filename> still refers to &oldreleasename; as explained in <xref
+ APT source-list files still refer to &oldreleasename; as explained in <xref
linkend="old-sources"/>.
</para>
</section>
- <section id="proposed-updates">
- <title>The proposed-updates section</title>
- <para>
- If you have listed the <literal>proposed-updates</literal> section
- in your <filename>/etc/apt/sources.list</filename> file, you
- should remove it from that file before attempting to upgrade your
- system. This is a precaution to reduce the likelihood of
- conflicts.
- </para>
- </section>
-
- <section id="unofficial-sources">
- <title>Unofficial sources</title>
- <para>
- If you have any non-Debian packages on your system, you should be aware that
- these may be removed during the upgrade because of conflicting dependencies.
- If these packages were installed by adding an extra package archive in your
- <filename>/etc/apt/sources.list</filename>, you should check if that archive
- also offers packages compiled for &releasename; and change the source line accordingly
- at the same time as your source lines for Debian packages.
- </para>
- <para>
- Some users may have <emphasis>unofficial</emphasis> backported <quote>newer</quote> versions of packages that
- <emphasis>are</emphasis> in Debian installed on their &oldreleasename; system. Such
- packages are most likely to cause problems during an upgrade as they may result
- in file conflicts<footnote><para> Debian's package management system normally
- does not allow a package to remove or replace a file owned by another package
- unless it has been defined to replace that package. </para> </footnote>.
- <xref linkend="trouble"/> has some information on how to deal with file
- conflicts if they should occur.
- </para>
-
- </section>
-
</section>
<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>.
+ Before starting the upgrade you must reconfigure APT's source-list
+ files (<filename>/etc/apt/sources.list.d/</filename> and files under

I think you want <filename>/etc/apt/sources.list</filename> here.

Post by Justin B Rye
+ <filename>/etc/apt/sources.list.d/</filename>).
</para>
<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
+ APT will consider all packages that can
+ 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).

Possibly avoid the long parenthetical comment here?

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.

or going slightly further

files. Thus, where you have multiple mirror locations, list local
hard disks first, then <acronym>CD-ROM</acronym>s, and then remote mirrors.

Kind regards
Vince

Post by Justin B Rye
</para>
@@ -528,16 +537,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 remote 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>
<para>
For example, your package mirror may be under
@@ -558,7 +567,7 @@ $ apt-forktracer | sort
</para>
<para>
After adding your new sources, disable the previously existing
- <quote><literal>deb</literal></quote> lines in <filename>sources.list</filename> by placing a
+ archive entries in the APT source-list files by placing a
hash sign (<literal>#</literal>) in front of them.
</para>
</section>
@@ -566,10 +575,9 @@ $ apt-forktracer | sort
<section id="cdroms">
<title>Adding APT sources from optical media</title>
<para>
- If you want to use <emphasis>only</emphasis> CDs (or DVDs or Blu-ray Discs),
- comment out the existing
- <quote><literal>deb</literal></quote> lines in <filename>/etc/apt/sources.list</filename> by
- placing a hash sign (<literal>#</literal>) in front of them.
+ If you want to use <emphasis>only</emphasis> CDs (or DVDs or Blu-ray
+ Discs), comment out the existing entries in all the APT source-list files
+ by placing a hash sign (<literal>#</literal>) in front of them.
</para>
<para>
Make sure there is a line in <filename>/etc/fstab</filename> that enables
@@ -629,9 +637,11 @@ $ apt-forktracer | sort
</screen>
<para>
Next you should double-check that the APT source entries (in
- <filename>/etc/apt/sources.list</filename>) refer either to
- <quote><literal>&releasename;</literal></quote> or to <quote><literal>stable</literal></quote>. There should not be
- any sources entries pointing to &oldreleasename;.
+ <filename>/etc/apt/sources.list</filename> and files under
+ <filename>/etc/apt/sources.list.d/<filename>) refer either to
+ <quote><literal>&releasename;</literal></quote> or to
+ <quote><literal>stable</literal></quote>. There should not be any sources
+ entries pointing to &oldreleasename;.
<note>
<para>
Source lines for a CD-ROM might sometimes refer to
@@ -900,8 +910,8 @@ E: You don't have enough free space in /var/cache/apt/archives/.
<para>
- Note that in order to safely remove packages, it is advisable to switch your
- <filename>sources.list</filename> back to &oldreleasename; as described in <xref
+ Note that in order to safely remove packages, it is advisable to switch
+ your APT source-list files back to &oldreleasename; as described in <xref
linkend="old-sources"/>.
</para>
</section>
@@ -998,8 +1008,8 @@ E: Could not perform immediate configuration on '<replaceable>package</replaceab
</para>
<para>
Another possible workaround for this problem is to temporarily add both
- &oldreleasename; and &releasename; sources to your
- <filename>sources.list</filename> and run <command>apt update</command>.
+ &oldreleasename; and &releasename; sources to your APT source-list files
+ and run <command>apt update</command>.
</para>
</section>

--

[Justin B Rye]

Post by V***@csiro.au

Post by Paul Gevers
<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>.
+ Before starting the upgrade you must reconfigure APT's source-list
+ files (<filename>/etc/apt/sources.list.d/</filename> and files under

I think you want <filename>/etc/apt/sources.list</filename> here.

Thanks.

Post by V***@csiro.au

Post by Paul Gevers
+ <filename>/etc/apt/sources.list.d/</filename>).
</para>
<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
+ APT will consider all packages that can
+ 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).

Possibly avoid the long parenthetical comment here?

Oh yes, definitely.

Post by V***@csiro.au
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.
or going slightly further
files. Thus, where you have multiple mirror locations, list local
hard disks first, then <acronym>CD-ROM</acronym>s, and then remote mirrors.

Being really picky, you aren't listing hard disks; the things you're
listing are repositories that happen to be *on* local writable storage
media.

files. Thus, if you have multiple mirror locations, list first the ones
on local hard disks, then <acronym>CD-ROM</acronym>s, and then remote mirrors.

Okay, revised patch using that last version.

(I'm using git more or less just as a way of getting colourful diffs...)

[Paul Gevers]

Hi Justin,

Looks good to me, minus one missing ";".

Post by Justin B Rye
+ The upgrade process described in this chapter has been designed for
+ <quote>pure</quote> Debian stable systems. If your APT

configuration mentions

Post by Justin B Rye
+ additional sources besides &oldreleasename, or if you have installed packages

^ there.

If nobody has further comments, I'll commit this version.

Paul

[Debian Bug Tracking System]

Your message dated Sun, 31 Mar 2019 14:38:45 +0200
with message-id <24dce916-2b34-efd7-9ded-***@debian.org>
and subject line Re: Bug#864017: release-notes: Assumes /etc/apt/sources.list is used (and not /etc/apt/sources.list.d/*.list or deb822) [general]
has caused the Debian Bug report #864017,
regarding release-notes: Assumes /etc/apt/sources.list is used (and not /etc/apt/sources.list.d/*.list or deb822) [general]
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact ***@bugs.debian.org
immediately.)