Add old upgrade guide and integrate with new chapters

Author: pbauer

docs/backend/upgrading/index.md

@@ -7,15 +7,24 @@ myst:
     "keywords": ""
 ---
 
-(backend-upgrading-index-label)=
+(plone-upgrade-guide-label)=
+
+# Plone Upgrade Guide
+
+Instructions and tips for upgrading to a newer Plone version.
+
+This guide particularly focuses on
+[Unix-like](https://en.wikipedia.org/wiki/Unix-like) environments,
+though the stack discussion may be useful to everyone.
 
-# Upgrading the Backend
 
 ```{toctree}
-:caption: Upgrading the Backend
+:caption: Upgrade Guide
 :maxdepth: 2
-:hidden:
 
-v60
-migrate-to-volto
+intro
+preparations
+addon_upgrade
+troubleshooting
+version_specific_migration/index
 ```

docs/backend/upgrading/intro.md

@@ -0,0 +1,61 @@
+---
+myst:
+  html_meta:
+    "description": ""
+    "property=og:description": ""
+    "property=og:title": ""
+    "keywords": ""
+---
+
+(upgrading-plone-label)=
+
+# Upgrading Plone
+
+This document covers the procedures and issues involved in upgrading an existing Plone installation.
+
+This involves both the upgrading of the program set, and migration of the site itself.
+
+Generally, you will often see the word *migration* used as the word we use to describe the process of getting your Plone site
+from one version of a given component to a newer version.
+
+For most people, this means upgrading Plone to a newer release, for example from 5.2.x to 6.0.x.
+
+Migration is necessary because the internals of Plone sometimes change to support new functionality.
+When that's the case, the content which is stored in your Plone instance may not match what the new version of the software expects.
+
+Plone has a builtin tool that migrates existing content to the new structure.
+
+This guide describes migration in Plone, specifically how you upgrade between different versions.
+
+Before migrating you should read this entire document to understand the potential impact migrating will have on your Plone site.
+
+It is also wise to have read the {doc}`troubleshooting <troubleshooting>` section, in case you may need to employ one of the techniques there.
+
+The guide applies to all contemporary versions of Plone.
+
+For unsupported versions from the year 2009 and before, see older versions of this documentation.
+
+## Version Numbering And Terminology
+
+Plone has a policy that increases the version number to a .0 on every major release.
+
+This means that when we say a *major release*, we are referring to a x.0 release, whereas a minor release has the version numbering 4.3.14 or 5.1.0
+
+In addition to the general procedure there are {doc}`version-specific migration guides </manage/upgrading/version_specific_migration/index>`.
+
+These guides contain more specific instructions and valuable information that has been collected from real-life migration cases.
+
+## No Large Leaps
+
+```{note}
+- It is advisable to not make large leaps in version numbers.
+- A single upgrade should not try to bridge multiple major version numbers.
+```
+
+Going from Plone 4.0 to Plone 5.1 is fine.
+
+If you are at Plone 2.5 and want to upgrade to the latest Plone 5, you should approach this in several steps:
+
+- First upgrade from Plone 2.5 to the latest Plone 3 version (3.3.6).
+- Then upgrade from Plone 3 to the latest Plone 4 version.
+- Then upgrade from Plone 4 to the latest Plone 5 version.

docs/backend/upgrading/preparations.md

@@ -0,0 +1,76 @@
+---
+myst:
+  html_meta:
+    "description": ""
+    "property=og:description": ""
+    "property=og:title": ""
+    "keywords": ""
+---
+
+# Preparations
+
+```{admonition} Description
+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'll find these in the CMFPlone directory of the distribution of the new version of Plone.
+
+- Make sure to check installed add-ons, if you **do not** need certain add-ons anymore, please deactivate and deinstall.
+
+- Check for dependencies
+
+  - Read the release notes for the Plone release you are upgrading to, in particular:
+
+  - What version of Python is required?
+
+  - What version of Zope is required?
+
+  - Do you need any new Python libraries?
+
+  - Make sure all the add-on products you are using have updated to support the version of Plone you are upgrading to.
+
+  - Start with the third-party products that are in use on your site.
+
+    - Verify that they have been updated or verified to work on the new version, and get them upgraded in your existing instance before you start the Plone/Zope/Python upgrade if possible.
+
+  - If Zope depends on a newer version of Python, install the new version of Python first.
+
+  - 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 CMFPlone directory of the distribution of the new version of Plone you want to update to:
+
+  - README.txt
+
+  - INSTALL.txt
+
+  - UPGRADE.txt (although this usually contains only the general procedure outlined above)
+
+    - These files are important because they may contain important last minute information and might be more specific than the relevant sections of this reference manual.
+
+## Back Up Your Plone Site
+
+```{note}
+It's important to back up your Plone site.
+```
+
+You will find a {doc}`how-to on backing up your Plone site here </manage/deploying/backup>`.
+
+## Setup A Test Environment To Rehearse The Upgrade
+
+```{note}
+Never work directly on your live site until you know that the upgrade was successful.
+```
+
+Instead, create a test environment to rehearse the upgrade.
+Copy your instance into a new environment and upgrade the copy.
+This is a good way of working out your third party products and dependencies in preparation for the final upgrade of the live site!

docs/backend/upgrading/troubleshooting.md

@@ -0,0 +1,88 @@
+---
+myst:
+  html_meta:
+    "description": ""
+    "property=og:description": ""
+    "property=og:title": ""
+    "keywords": ""
+---
+
+# Troubleshooting
+
+```{admonition} Description
+What to do when a problem occurs during a Plone upgrade.
+```
+
+When a problem occurs during the migration we recommend that you take the following steps.
+
+## Check the log files
+
+When a site error occurs, or Zope fails to start, there's probably an informative error message in Zope's log files.
+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::
+
+```
+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}`Error References </appendices/error-reference>`
+
+## Test without customizations
+
+When you have customized page templates or Python scripts, your changes may interfere with changes in the new version of Plone.
+It's important to rule out this possibility, since your customizations are unique to your site and no one on the planet will be able to help you solve it.
+
+Temporarily remove your customizations, for example by removing your layers from portal_skins, or by removing files from these layers on the file system.
+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
+
+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.
+
+If the problem disappears, you'll need to doublecheck the offending product:
+
+- Does it support the new version of Plone, Zope and Python?
+  Check the product's README.txt or other informational files or pages.
+- Does the product require any additional migration procedures?
+  Check the product's INSTALL.txt, UPGRADE.txt or other informational files or pages.
+- Does the product install properly? Re-install it and check the install log.
+
+## Test with a fresh Plone instance
+
+Create a new Plone site with your new version of Plone.
+You don't need a new Zope instance, since you can add another Plone site in the root of Zope.
+If the problem does not occur in a fresh site, the cause of your problem is most likely a customization, an installed product or content that was not migrated properly.
+
+## Make the problem reproducible
+
+Before you go out and {doc}`ask for help </askforhelp>`, you should be able to describe your problem in such a way that others can reproduce it in their environment.
+
+Reduce the problem to the smallest possible domain.
+Eliminate products and customizations that are not part of the problem.
+This makes it easier for others to reproduce the problem and it increases your chances of meeting others with the same problem or even a solution.
+The more complex your story is, the more likely that it is unique to your situation and in-penetrable to others.
+
+## Ask for help
+
+{doc}`Ask for help </askforhelp>` in the [Plone support channels](https://plone.org/support). Be sure to:
+
+- Provide relevant source code for your customizations that are part of the problem.
+- Describe the exact configuration, software versions, migration history, error messages and so on.
+
+## Report a bug
+
+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
+- [Plone Issue Tracker](https://github.com/plone/Products.CMFPlone/issues)
+
+Do not use the bug trackers to ask for help.
+First analyze your problem and assert that it's a bug before you report it.

docs/backend/upgrading/version_specific_migration/images/portal_actions_control_panel.png

@@ -0,0 +1,19 @@
+# Version-specific migration procedures and tips
+
+```{admonition} Description
+In addition to the general procedure described in the previous sections, this section provides version-specific procedures and tips.
+If your migration does not involve a version pair specified here, then you may follow the general procedures alone.
+```
+
+```{toctree}
+:maxdepth: 2
+
+p4x_to_p5x_upgrade
+plone5_minor_upgrade
+upgrade_to_51
+upgrade_to_52
+upgrade_to_python3
+upgrade_zodb_to_python3
+upgrade_to_60
+migrate-to-volto
+```

docs/backend/upgrading/version_specific_migration/images/sharing_group_link.png

@@ -9,7 +9,7 @@ myst:
 
 (backend-migrate-to-volto-label)=
 
-# Migrate to Volto
+# Migrating from Plone Classic to Volto
 
 Plone 6 comes with a new default frontend called {term}`Volto`.
 Volto is written in React and uses {py:mod}`plone.restapi` to communicate with the backend.