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> > --
