Merge branch 'qtpies-patch-2'

user/managing-os/debian/debian-upgrade.md

@@ -1,6 +1,6 @@
 ---
 layout: doc
-title: Upgrading Debian TemplateVMs
+title: In-place upgrade of Debian TemplateVMs
 permalink: /doc/template/debian/upgrade/
 redirect_from:
 - /doc/template/debian/upgrade-8-to-9/
@@ -13,7 +13,7 @@ redirect_from:
 # Upgrading Debian TemplateVMs
 
 This page provides instructions for performing an in-place upgrade of an installed [Debian TemplateVM].
-If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM] page instead.
+If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM] page instead. ([Learn more about the two options.][Debian TemplateVM Upgrade])
 
 In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system][upgrade].
 
@@ -152,6 +152,7 @@ We strongly recommend against using any Debian release that has reached [end-of-
 
 
 [Debian TemplateVM]: /doc/templates/debian/
+[Debian TemplateVM Upgrade]: /doc/templates/debian/#upgrading
 [upgrade]: https://wiki.debian.org/DebianUpgrade
 [switch]: /doc/templates/#switching
 [jessie]: https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html

user/managing-os/debian/debian.md

@@ -41,16 +41,16 @@ After installing a fresh Debian TemplateVM, we recommend performing the followin
 
 ## Updating
 
-Routine daily updates within a given release.
-
-Please see [Updating software in TemplateVMs].
+For routine daily TemplateVM updates within a given Debian release, see [Updating software in TemplateVMs].
 
 
 ## Upgrading
 
-Upgrading from your current release to a newer release.
+There are two ways to upgrade your TemplateVM to a new Debian release:
 
-Please see [Upgrading Debian TemplateVMs].
+ - [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template][switch]. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.
+
+ - [Perform an in-place upgrade of an existing Debian template.][Upgrading Debian TemplateVMs] This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
 
 
 ## Release-specific notes

user/managing-os/fedora/fedora-upgrade.md

@@ -1,6 +1,6 @@
 ---
 layout: doc
-title: Upgrading Fedora TemplateVMs
+title: In-place upgrade of Fedora TemplateVMs
 permalink: /doc/template/fedora/upgrade/
 redirect_from:
 - /doc/template/fedora/upgrade-26-to-27/
@@ -24,7 +24,7 @@ redirect_from:
 # Upgrading Fedora TemplateVMs
 
 This page provides instructions for performing an in-place upgrade of an installed [Fedora TemplateVM].
-If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM] page instead.
+If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM] page instead. ([Learn more about the two options.][Fedora TemplateVM Upgrade])
 
 
 ## Summary instructions for standard Fedora TemplateVMs
@@ -194,14 +194,11 @@ In this case, you have several options:
     However, you may end up having to increase the disk image size anyway (see previous option).
  3. Do the upgrade in parts, e.g., by using package groups.
     (First upgrade `@core` packages, then the rest.)
- 4. Do not perform an in-place upgrade.
-    Instead, simply download and install a new template package, then redo all desired template modifications.
-    Here are some useful messages from the mailing list that also apply to TemplateVM management and migration in general from
-    [Marek](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/dS1jbLRP9n8J) and
-    [Jason M](https://groups.google.com/d/msg/qubes-users/mCXkxlACILQ/5PxDfI-RKAsJ).
+ 4. Do not perform an in-place upgrade, see [Upgrading Fedora TemplateVMs].
 
 
 [Fedora TemplateVM]: /doc/templates/fedora/
+[Fedora TemplateVM Upgrade]: /doc/templates/fedora/#upgrading
 [resize-disk-image]: /doc/resize-disk-image/
 [Additional Information]: #additional-information
 [switch]: /doc/templates/#switching

user/managing-os/fedora/fedora.md

@@ -33,17 +33,16 @@ After installing a fresh Fedora TemplateVM, we recommend performing the followin
 
 ## Updating
 
-Routine daily updates within a given release.
-
-Please see [Updating software in TemplateVMs].
+For routine daily updates within a given release, see [Updating software in TemplateVMs].
 
 
 ## Upgrading
 
-Upgrading from your current release to a newer release.
+There are two ways to upgrade your TemplateVM to a new Fedora release:
 
-Please see [Upgrading Fedora TemplateVMs].
+ - [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template][switch]. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the `dnf history` command.
 
+ - [Perform an in-place upgrade of an existing Fedora template.][Upgrading Fedora TemplateVMs] This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
 
 
 [TemplateVM]: /doc/templates/