Merge branch 'upgrade-guide' of github.com:plone/documentation into upgrade-guide

� Conflicts:
�	docs/backend/upgrading/intro.md
�	docs/backend/upgrading/preparations.md

Author: stevepiercy

docs/backend/upgrading/intro.md

@@ -81,6 +81,7 @@ It just fixed a bug.
 A post on the Community forum, [Rules for Plone 6 development during the beta stage](https://community.plone.org/t/rules-for-plone-6-development-during-the-beta-stage/15432), discusses alpha and beta versioning.
 ```
 
+In addition to the general procedure there are {doc}`version-specific migration guides </manage/upgrading/version_specific_migration/index>`.
 
 (introduction-version-specific-upgrade-guides-label)=
 
@@ -90,6 +91,8 @@ In addition to the general upgrade procedure, there are {doc}`version-specific m
 
 These guides contain specific instructions and valuable information that has been collected from real-life migration cases.
 
+This approach is recommended for all upgrades of minor version and can work fine for most mayor upgrades.
+When dealing with mayor changes in Plone or with very large or complex installations a export-import based migration (see below) is often the better solution.
 
 (introduction-upgrade-strategies-label)=
 

docs/backend/upgrading/preparations.md

@@ -20,10 +20,9 @@ This chapter lists things to do before you migrate Plone.
 ## Gather information
 
 -   Read the "What's new in..." for your relevant Plone version, and read the release notes.
-    You will find these in the {file}`CMFPlone` directory of the distribution of the new version of Plone.
+    You will find these in the [online directory of released versions on `dist.plone.org`](https://dist.plone.org/release/).
+    As an example, you can find the file [`RELEASE-NOTES.md` for 6.0.0b2](https://dist.plone.org/release/6.0.0b2/RELEASE-NOTES.md).
 
--   Make sure to check installed add-ons.
-    If you **do not** need certain add-ons anymore, deactivate and uninstall them.
 
 -   Check for dependencies.
 
@@ -44,21 +43,16 @@ This chapter lists things to do before you migrate Plone.
 
     -   If the newer version of Plone depends on a newer version of Zope, you will need to install that before proceeding with the Plone upgrade.
 
-        ```{note}
-        Zope has its own migration guidelines, which you will find in the release notes of the version you are migrating to.
-        
-        If Plone is being upgraded at the same time as a Zope version, Plone will usually handle the Zope upgrade with its own migration script.
-        ```
-
--   Read the following files in the {file}`CMFPlone` directory of the distribution of the new version of Plone to which you want to update.
+```{seealso}
+Zope has its own documentation of migration guidelines.
+Of most interest for migration are the following.
 
-    -   `README.txt`
-    
-    -   `INSTALL.txt`
-    
-    -   `UPGRADE.txt` (although this usually contains only the general procedure outlined above)
+-   [What's new](https://zope.readthedocs.io/en/latest/news.html) at a high level.
+-   [Migrating between Zope versions](https://zope.readthedocs.io/en/latest/migrations/index.html).
+-   [Detailed changelog](https://zope.readthedocs.io/en/latest/changes.html).
 
-    These files may contain important last-minute information, and might be more specific than the relevant sections of this reference manual.
+If Plone is being upgraded at the same time as a Zope version, Plone will usually handle the Zope upgrade with its own migration script.
+```
 
 
 (upgrade-back-up-your-Plone-site-label)=

docs/backend/upgrading/troubleshooting.md

@@ -21,15 +21,15 @@ When a site error occurs, or Zope fails to start, there's probably an informativ
 Locate [these log files](https://plone.org/documentation/faq/plone-logs) and inspect instance.log.
 Ignore irrelevant warnings and search for words such as error, exception and traceback (case-insensitive).
 
-When Zope doesn't start and there's no useful information in the log file, you can start Zope interactively and watch for error messages in the output::
+When Zope doesn't start and there's no useful information in the log file, you can start Zope interactively and watch for error messages in the output:
 
-```
+```bash
 bin/instance fg
 ```
 
 You may be able to find more information on the error messages in:
 
-- the {doc}`Version-specific migration tips </manage/upgrading/version_specific_migration/index>` for your version of Plone
+- the {doc}`Version-specific migration tips </backend/upgrading/version_specific_migration/index>` for your version of Plone
 - the {doc}`Error References </appendices/error-reference>`
 
 ## Test without customizations
@@ -41,11 +41,11 @@ Temporarily remove your customizations, for example by removing your layers from
 If the problem disappears, you'll need to double-check your customizations.
 It's usually best to copy the original files of the new version of Plone to your skin, and re-customize those.
 
-## Test without products
+## Test without add-ons
 
-Bugs or compatibility problems in products that you have installed may cause problems in Plone.
-Go to Site Setup > Add/Remove Products and remove (uninstall) all product that are not distributed with Plone.
-Remove the uninstalled products from the Products directory of your Zope instance.
+Bugs or compatibility problems in add-ons that you have installed may cause problems in Plone.
+Go to Site Setup > Add-ons and deactivate all add-ons that are not distributed with Plone.
+Remove the deactivated add-ons from the packages of your Zope instance.
 
 If the problem disappears, you'll need to doublecheck the offending product:
 
@@ -81,7 +81,7 @@ The more complex your story is, the more likely that it is unique to your situat
 
 Once you have investigated, analyzed, identified and confirmed the cause of your problem and you are convinced it's a bug (rather than an X-file), go to the appropriate bug tracker and report it:
 
-- Products: the README usually tells how to report bugs
+- Add-ons: the README usually tells how to report bugs
 - [Plone Issue Tracker](https://github.com/plone/Products.CMFPlone/issues)
 
 Do not use the bug trackers to ask for help.

docs/backend/upgrading/version-specific-migration/upgrade-to-60.md

@@ -162,7 +162,7 @@ See [PLIP 3061](https://github.com/plone/Products.CMFPlone/issues/3061).
 ## Python
 
 You may need to use a newer Python version.
-Supported Python versions are 3.7, 3.8, and 3.9.
+Supported Python versions are 3.8, 3.9 and 3.10.
 We recommend the most recent version.
 See https://www.python.org/downloads/ for which Python version is still supported by the Python community.