On Sun, 5 Jan 2020 16:34:04 +0000
Justin B Rye <justin.byam....@gmail.com> wrote:
> I finally got round to reviewing this:
>
> > + <section id="cleanup-revised-configuration-files">
> > + <title>Cleanup revised configuration files</title>
>
> "Cleanup" is the noun; you want the verb, "Clean up". And I'm not
> sure you want "revised"; I would recommend "leftover", or you could
> just omit it.
Done. (Used "leftover".)
Patch sections_v4.patch attached. This patch should
apply directly to HEAD and incorporates the old
cleanup.patch series.
In the FYI catagory, there are errors building
HEAD on master:
Writing ch-whats-new.en.html for chapter(ch-whats-new)
ERROR: xref linking to secure-boot has no generated link text.
Error: no ID for constraint linkend: "secure-boot".
Writing ch-installing.en.html for chapter(ch-installing)
ERROR: xref linking to before-first-reboot has no generated link text.
Error: no ID for constraint linkend: "before-first-reboot".
ERROR: xref linking to noteworthy-obsolete-packages has no generated link text.
Error: no ID for constraint linkend: "noteworthy-obsolete-packages".
Writing ch-upgrading.en.html for chapter(ch-upgrading)
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 b04a58e2..e00db2c3 100644
--- a/en/upgrading.dbk
+++ b/en/upgrading.dbk
@@ -244,64 +244,106 @@
</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.
- </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.
+ If your system is using multiple source-list files then you will
+ need to ensure they stay consistent.
</para>
+ <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="clean-up-leftover-configuration-files">
+ <title>Clean up leftover 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>
<para>
@@ -350,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
