On Thu, 2 Jan 2020 16:56:10 -0600
"Karl O. Pinc" <k...@karlpinc.com> wrote:
> On Thu, 2 Jan 2020 13:27:19 -0600
> "Karl O. Pinc" <k...@karlpinc.com> wrote:
>
> > Attached are 2 patches:
> >
> > cleanup_v2.patch
> > This should incorporate all changes discussed so far.
> >
> > section_v1.patch
> > This applies on top of the cleanup patch. It re-titles
> > the 4.2 section and adds sub-sections. If you want this
> > in a separate bug report, discussed elsewhere, etc.,
> > please let me know. (I had it in my brain and wanted
> > to get it out.)
>
> Attached is section_v2.patch, to be applied on top of
> cleanup_v2.patch. (Replaces section_v1.patch.)
Attached is a cleanup_v3.patch.
Regards,
Karl <k...@karlpinc.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
diff --git a/en/upgrading.dbk b/en/upgrading.dbk
index 9cc9f7a4..eb32edc8 100644
--- a/en/upgrading.dbk
+++ b/en/upgrading.dbk
@@ -244,73 +244,105 @@
</section>
<section id="system-status">
- <title>Checking APT configuration status</title>
+ <title>Start from "pure" Debian</title>
<para>
- 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.
+ The upgrade process described in this chapter has been designed
+ for <quote>pure</quote> Debian stable systems. APT controls what
+ is installed on your system. 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>
- 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>
+ 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="&url-man;/&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.
+ 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
- old kernel packages).<screen>
-$ aptitude search '~i(!~ODebian)'
-$ apt-forktracer | sort
- </screen>
- </para>
- <para>
- Direct upgrades from Debian releases older than &oldrelease; (&oldreleasename;)
- are not supported.
- Please follow the instructions in the <ulink
- url="https://www.debian.org/releases/&oldreleasename;/releasenotes";>Release
- Notes for &debian; &oldrelease;</ulink> to upgrade to &debian; &oldrelease; first.
- </para>
- <para>
- This procedure also assumes your system has been updated to the latest point
- release of &oldreleasename;. If you have not done this or are unsure, follow the
- instructions in <xref linkend="old-upgrade"/>.
- </para>
- <para>
- You should also make sure the package database is ready before proceeding
- with the upgrade. If you are a user of another package manager like
- <systemitem role="package">aptitude</systemitem> or <systemitem
- role="package">synaptic</systemitem>, review any pending actions. A
- package scheduled for installation or removal
- might interfere with 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>
- It is a good idea to <link linkend="obsolete">remove obsolete
- packages</link> from your system before upgrading.
- </para>
- <para>
- A previous upgrade may have left unused copies of configuration
- files; <link linkend="configuration-changes">old versions</link>
- of configuration files, versions supplied by the package
- maintainers, etc. Removing leftover files from previous upgrades
- can avoid confusion. Find such leftover files with:
- </para>
- <screen>
-# find /etc -name '*.dpkg-*' '*.ucf-*' '*.merge-error'
- </screen>
+
+ <section id="upgrade-to-debian-oldrelease">
+ <title>Upgrade to Debian &oldrelease; (&oldreleasename;)</title>
+ <para>
+ Direct upgrades from Debian releases older than &oldrelease;
+ (&oldreleasename;) are not supported. Display your Debian version
+ with:
+ <screen>
+$ cat /etc/debian_version
+ </screen>
+ Please follow
+ the instructions in the <ulink
+ url="https://www.debian.org/releases/&oldreleasename;/releasenotes";>Release
+ Notes for &debian; &oldrelease;</ulink> to upgrade to &debian;
+ &oldrelease; first.
+ </para>
+ </section>
+
+ <section id="removing-non-debian-packages">
+ <title>Remove non-Debian packages</title>
+ <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>
+ $ aptitude search '~i(!~ODebian)'
+ $ apt-forktracer | sort
+ </screen>
+ </para>
+ </section>
+
+ <section id="upgrade-to-latest-point-release">
+ <title>Upgrade to latest point release</title>
+ <para>
+ This procedure assumes your system has been updated to the latest point
+ release of &oldreleasename;. If you have not done this or are unsure, follow the
+ instructions in <xref linkend="old-upgrade"/>.
+ </para>
+ </section>
+
+ <section id="prepare-package-database">
+ <title>Prepare the package database</title>
+ <para>
+ You should make sure the package database is ready before proceeding
+ with the upgrade. If you are a user of another package manager like
+ <systemitem role="package">aptitude</systemitem> or <systemitem
+ role="package">synaptic</systemitem>, review any pending actions. A
+ package scheduled for installation or removal
+ might interfere with 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>
+ </section>
+
+ <section id="remove-obsolete-packages">
+ <title>Remove obsolete packages</title>
+ <para>
+ It is a good idea to <link linkend="obsolete">remove obsolete
+ packages</link> from your system before upgrading.
+ </para>
+ </section>
+
+ <section id="cleanup-revised-configuration-files">
+ <title>Cleanup revised configuration files</title>
+ <para>
+ A previous upgrade may have left unused copies of configuration
+ files; <link linkend="configuration-changes">old versions</link>
+ of configuration files, versions supplied by the package
+ maintainers, etc. Removing leftover files from previous upgrades
+ can avoid confusion. Find such leftover files with:
+ </para>
+ <screen>
+ # find /etc -name '*.dpkg-*' '*.ucf-*' '*.merge-error'
+ </screen>
+ </section>
<section id="proposed-updates">
<title>The proposed-updates section</title>
@@ -360,7 +392,7 @@ $ apt-forktracer | sort
</section>
<section id="package-status">
- <title>Checking packages status</title>
+ <title>Check package status</title>
<para>
Regardless of the method used for upgrading, it is recommended that you check
the status of all packages first, and verify that all packages are in an
