Skip to content

Commit d3d25f2

Browse files
stevepiercystevepiercy
committed
Clean up upgrade introduction
1 parent 850afcd commit d3d25f2

File tree

1 file changed

+121
-50
lines changed

1 file changed

+121
-50
lines changed

‎docs/backend/upgrading/intro.md‎

Lines changed: 121 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,178 @@
11
---
22
myst:
33
html_meta:
4-
"description": ""
5-
"property=og:description": ""
6-
"property=og:title": ""
7-
"keywords": ""
4+
"description": "Introduction to upgrading Plone"
5+
"property=og:description": "Introduction to upgrading Plone"
6+
"property=og:title": "Introduction to upgrading Plone"
7+
"keywords": "Introduction, Upgrading, Plone, migration, version"
88
---
99

10-
(upgrading-plone-label)=
10+
(introduction-label)=
1111

12-
# Upgrading Plone
12+
# Introduction
1313

14-
This document covers the procedures and issues involved in upgrading an existing Plone installation.
14+
This part of the documentation describes how to upgrade an existing Plone installation.
15+
For most people, this means upgrading Plone to a newer release, for example, from 5.2.9 to 6.0.0.
16+
This guide applies to all modern versions of Plone.
17+
For unsupported versions from the year 2009 and before, see older versions of this documentation.
1518

16-
This involves both the upgrading of the program set, and migration of the site itself.
19+
Upgrading Plone includes the Plone application and its add-ons, as well as migration of its content.
1720

18-
Generally, you will often see the word *migration* used as the word we use to describe the process of getting your Plone site
19-
from one version of a given component to a newer version.
21+
A *migration* is the process of taking a component in your Plone site, and moving it from its current version to a newer one.
22+
Migration is necessary because the internals of Plone sometimes change to support new functionality.
23+
When that's the case, the content that is stored in your Plone instance may not align with the requirements of the new version.
24+
To handle this situation, Plone has a built-in tool that migrates existing content to the new structure.
2025

21-
For most people, this means upgrading Plone to a newer release, for example from 5.2.x to 6.0.x.
26+
Before migrating you should read this entire document, as well as {ref}`introduction-version-specific-upgrade-guides-label`, to understand the potential impact migrating will have on your Plone site.
27+
It is also wise to read the {doc}`troubleshooting` chapter, in case you run into any issues.
2228

23-
Migration is necessary because the internals of Plone sometimes change to support new functionality.
24-
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.
2529

26-
Plone has a builtin tool that migrates existing content to the new structure.
30+
(introduction-versioning-policy-and-numbering-label)=
2731

28-
This guide describes migration in Plone, specifically how you upgrade between different versions.
32+
## Versioning policy and numbering
2933

30-
Before migrating you should read this entire document to understand the potential impact migrating will have on your Plone site.
34+
Plone follows [semantic versioning](https://semver.org/) to communicate what users and developers can expect from a release regarding breaking changes, new features, and bug fixes.
35+
We use a three-digit version scheme (e.g., `6.0.0`), following the `major.minor.patch` scheme.
3136

32-
It is also wise to have read the {doc}`troubleshooting <troubleshooting>` section, in case you may need to employ one of the techniques there.
37+
(introduction-versioning-policy-breaking-or-major-release-label)=
3338

34-
The guide applies to all contemporary versions of Plone.
39+
### Breaking (major) release
3540

36-
For unsupported versions from the year 2009 and before, see older versions of this documentation.
41+
A _breaking_ release indicates a change that might break an application or third-party add-on that relies on Plone.
42+
The version numbering would increase as in the following example.
43+
44+
````
45+
5.2.3 -> 6.0.0
46+
````
47+
48+
For every breaking release, details of what breaks and how to mitigate it must be documented in the change and release notes.
49+
50+
51+
(introduction-versioning-policy-feature-minor-release-label)=
52+
53+
### Feature (minor) release
54+
55+
A _feature_ release indicates that a new feature has been added to Plone in a non-breaking fashion.
56+
The version numbering would increase as in the following example.
57+
58+
````
59+
5.1.7 -> 5.2.0
60+
````
61+
62+
You do not have to expect any breaking changes from such a release.
63+
It is possible that the user interface changes, due to a new feature that has been added.
64+
65+
66+
(introduction-versioning-policy-bugfix-patch-release-label)=
67+
68+
### Bugfix (patch) release
69+
70+
A _bugfix_ release indicates one or more bugs in Plone have been fixed.
71+
The version numbering would increase as in the following example.
3772

38-
## Version Numbering And Terminology
73+
````
74+
5.2.8 -> 5.2.9
75+
````
3976

40-
Plone has a policy that increases the version number to a .0 on every major release.
77+
There should be no breaking or UX/UI changes from such a release.
78+
It just fixed a bug.
4179

42-
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
80+
```{seealso}
81+
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.
82+
```
4383

44-
In addition to the general procedure there are {doc}`version-specific migration guides </manage/upgrading/version_specific_migration/index>`.
4584

46-
These guides contain more specific instructions and valuable information that has been collected from real-life migration cases.
85+
(introduction-version-specific-upgrade-guides-label)=
4786

48-
## Upgrade Strategies
87+
## Version-specific upgrade guides
4988

50-
### Inplace Migrations
89+
In addition to the general upgrade procedure, there are {doc}`version-specific migration guides <version-specific-migration/index>`.
5190

52-
A inplace migration means the content and settings of a Plone installation are being updated while Plone is running.
53-
These upgrades use a builtin tool and basically run upgrade-steps that are collected in [plone.app.upgrade](https://github.com/plone/plone.app.upgrade/).
91+
These guides contain specific instructions and valuable information that has been collected from real-life migration cases.
5492

55-
This approach is recommended for all upgrades of minor version and can work fine for most mayor upgrades.
56-
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.
5793

58-
During in-place migrations it is advisable to **not make large leaps** in version numbers.
59-
A single upgrade should not try to bridge multiple major version numbers.
94+
(introduction-upgrade-strategies-label)=
6095

61-
Going from Plone 4.0 to Plone 5.1 is fine.
96+
## Upgrade strategies
6297

63-
If you are at Plone 2.5 and want to upgrade to the latest Plone 5, you should approach this in several steps:
6498

65-
- First upgrade from Plone 2.5 to the latest Plone 3 version (3.3.6).
66-
- Then upgrade from Plone 3 to the latest Plone 4 version.
67-
- Then upgrade from Plone 4 to the latest Plone 5 version.
99+
(introduction-upgrade-strategies-in-place-migrations-label)=
68100

101+
### In-place migrations
69102

70-
### Export-import Migrations
103+
An in-place migration means the content and settings of a Plone installation are being updated while Plone is running.
104+
These upgrades use a built-in tool
105+
They run upgrade steps that are collected in [plone.app.upgrade](https://github.com/plone/plone.app.upgrade/).
71106

72-
Export all content and settings that you want to keep from an old site and import it to a fresh site.
107+
This approach is recommended for all upgrades of feature (minor) versions.
108+
This usually works fine for most breaking (major) upgrades as well.
73109

74-
This approach allows you to migrate from Plone 4 to 6, from Python 2 to 3 and from Archetypes to Dexterity in one migration-step and is recommended for large and complex migrations.
110+
When dealing with major changes in Plone, or with very large or complex installations, an {ref}`export-import <introduction-upgrade-strategies-export-import-migrations-label>` based migration is often the better solution.
75111

76-
The recommended tool for this is https://github.com/collective/collective.exportimport. An alternative is transmogrifier (see the training {ref}`training:transmogrifier-label`)
112+
During in-place migrations, it is advisable **not to skip over** breaking (major) version numbers.
77113

78-
## Mayor Changes
114+
Going from Plone 5.2 to Plone 6.0 is fine.
79115

80-
The following mayor changes in the history of Plone require special attention when migrating:
116+
If you are at Plone 2.5 and want to upgrade to the latest Plone 6, you should approach this in several steps:
117+
118+
- First upgrade from Plone 2.5 to the latest Plone 3 version (3.3.6).
119+
- Then upgrade from Plone 3 to the latest Plone 4 version (4.3.20).
120+
- Then upgrade from Plone 4 to the latest Plone 5 version.
121+
- Then upgrade from Plone 5 to the latest Plone 6 version.
122+
123+
124+
(introduction-upgrade-strategies-export-import-migrations-label)=
125+
126+
### Export-import migrations
127+
128+
Export all content and settings that you want to keep from an old site and import it into a fresh site.
129+
130+
This approach allows you to migrate from Plone 4 to 6, from Python 2 to 3, and from Archetypes to Dexterity, in one migration step.
131+
It is recommended for large and complex migrations.
132+
133+
The recommended tool for this is [`collective.exportimport`](https://github.com/collective/collective.exportimport).
134+
An alternative is `transmogrifier` (see the training {ref}`training:transmogrifier-label`).
135+
136+
137+
(introduction-major-changes-label)=
138+
139+
## Major Changes
140+
141+
The following major changes in the history of Plone require special attention when migrating.
142+
143+
144+
(introduction-plone-5.0-dexterity-replaces-archetypes-label)=
81145

82146
### Plone 5.0: Dexterity replaces Archetypes
83147

84-
With Plone 5.0 the default framework for content-types switched from Archetypes to Dexterity.
148+
With Plone 5.0 the default framework for content types switched from Archetypes to Dexterity.
85149

86-
Until Plone 5.2.x (in Python 2 only!) there is a builtin migration from Archetypes to Dexterity.
87-
See https://pypi.org/project/plone.app.contenttypes/2.2.3/#migration for details on the migration of custom and default content-types to Dexterity.
150+
Until Plone 5.2.x there is a built-in migration from Archetypes to Dexterity, but it only supports Python 2.
151+
See [Migration](https://pypi.org/project/plone.app.contenttypes/2.2.3/#migration) in the latest stable release of `plone.app.contenttypes` for details on the migration of custom and default content types to Dexterity.
88152

89153
Using [collective.exportimport](https://pypi.org/project/collective.exportimport/) you can export Archetypes content and import it as Dexterity content.
90154

91155

156+
(introduction-plone-5.2-support-for-python-3-label)=
157+
92158
### Plone 5.2: Support for Python 3
93159

94160
Plone 5.2 added support for Python 3 while Plone 6.0 dropped support for Python 2.
95161
This means that you can use Plone 5.2 to upgrade to Python 3.
96162

97-
This requires that you run Plone in Python 3 and only use code that supports Python 3. It also requires that you migrate the database in a separate step from Python 2 to 3 while Plone is not running.
163+
This requires that you run Plone in Python 3 and only use code that supports Python 3.
164+
It also requires that you migrate the database in a separate step from Python 2 to 3 while Plone is not running.
98165

99-
See the chapters {ref}`migrating-52-to-python3-label` and {ref}`migrate-zodb-to-python3-label` for detailed info on these steps.
166+
See the chapters {ref}`migrating-52-to-python3-label` and {ref}`migrate-zodb-to-python3-label` for detailed information on these steps.
100167

101168
Using [collective.exportimport](https://pypi.org/project/collective.exportimport/) you can export content in Python 2 and import it in Python 3.
102169

170+
171+
(introduction-plone-6.0-volto-as-new-frontend-label)=
172+
103173
### Plone 6.0: Volto as new frontend
104174

105-
Plone 6.0 comes with a new default frontend called {term}`Volto` which is written in React and expects some subtle but important changes.
175+
Plone 6.0 comes with a new default frontend called {term}`Volto`.
176+
It is written in React, and expects some subtle but important changes.
106177

107-
See {ref}`backend-migrate-to-volto-label` for these specialized migration-steps.
178+
See {ref}`backend-migrate-to-volto-label` for the specific migration steps.

0 commit comments

Comments
 (0)