Bug#864017: release-notes: Assumes /etc/apt/sources.list is used (and not /etc/apt/sources.list.d/*.list or deb822) [general]
Vincent.Mcintyre@csiro.au wrote:
>> <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.
>> + <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.
> 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...)
--
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..f97d5634 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,60 +424,26 @@ $ 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</filename> and files under
+ <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
- hard disk, then <acronym>CD-ROM</acronym>s, and then remote mirrors).
+ 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, if you have multiple mirror locations, list first the ones
+ on local hard disks, then <acronym>CD-ROM</acronym>s, and then remote mirrors).
</para>
<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>
Reply to: