Bug#864017: release-notes: Assumes /etc/apt/sources.list is used (and not /etc/apt/sources.list.d/*.list or deb822) [general]
On Wed, Mar 27, 2019 at 06:44:29PM +0000, Justin B Rye wrote:
> Justin B Rye wrote:
> > 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.
>
> In particular:
> > 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.
>
> [,,,]
> > 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.
>
> > <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.
>
> > + <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".
> --
> 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.
> + <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
> </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: