From 5af284566736c2d39a1d3b75e030413b0cf57bba Mon Sep 17 00:00:00 2001 From: Maurits van Rees Date: Wed, 10 Dec 2025 17:42:58 +0100 Subject: [PATCH 1/2] Create upgrade guide for Plone 6.2 backend. --- .../version-specific-migration/index.md | 1 + .../upgrade-to-62.md | 83 +++++++++++++++++++ docs/upgrade/index.md | 1 + styles/config/vocabularies/Plone/accept.txt | 2 + 4 files changed, 87 insertions(+) create mode 100644 docs/backend/upgrading/version-specific-migration/upgrade-to-62.md diff --git a/docs/backend/upgrading/version-specific-migration/index.md b/docs/backend/upgrading/version-specific-migration/index.md index c8cb485cdb..c4279e294e 100644 --- a/docs/backend/upgrading/version-specific-migration/index.md +++ b/docs/backend/upgrading/version-specific-migration/index.md @@ -27,5 +27,6 @@ upgrade-to-python3 upgrade-zodb-to-python3 upgrade-to-60 upgrade-to-61 +upgrade-to-62 migrate-to-volto ``` diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md new file mode 100644 index 0000000000..7fdebd923d --- /dev/null +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md @@ -0,0 +1,83 @@ +--- +myst: + html_meta: + "description": "How to upgrade to Plone 6.2" + "property=og:description": "How to upgrade to Plone 6.2" + "property=og:title": "How to upgrade to Plone 6.2" + "keywords": "Upgrade, Plone 6" +--- + +(backend-upgrade-plone-v62-label)= + +# Upgrade Plone 6.1 to 6.2 + +Plone 6.2 has seen the following major changes. +Some may require changes in your setup. + + +## Move to native namespaces + +Plone 6.2 has migrated all core Python packages from `pkg_resources`-style namespaces to native namespaces. + +The Plone Python backend consists of over 200 packages. +Most of these are namespace packages. +Examples are `plone.batching` and `plone.api`, which share the `plone` namespace. + +There are three styles or techniques of namespaces. +For Plone only two are important: `pkg_resources` and native (sometimes referred to as implicit). +The third style is `pkgutil`, but Plone has never used it. + +Native namespaces exist since Python 3.3. +Because Plone started in the days of Python 2, it has always used `pkg_resources`. +`pkg_resources` is part of the `setuptools` package. +This part is deprecated: it's scheduled to be removed around the end of 2025, in `setuptools` 81. +This means Plone needs to move to native namespaces. + +In general, this move shouldn't cause problems for integrators. +To install Plone 6.2 you can keep using the same version of `pip` (or `uv`), or `zc.buildout` as you do for Plone 6.1. +This assumes that all packages within one namespace use the same namespace style or technique. + +You may encounter problems when this assumption isn't true. +As an example, say your Plone project uses a package `collective.example`, and this still uses `pkg_resources`-style namespaces. +Plone itself depends on a package `collective.monkeypatcher` which is now using native namespaces. +This may cause problems at startup, especially `ModuleNotFoundError`. +In a normal install: + +* `pip` works fine. +* `zc.buildout` 4 won't work. +* `zc.buildout` 5 works fine. + +If for one or both of these packages you don't use a final release from https://pypi.org, but an editable install, it may not work. +You can solve this by installing an extra package with `pip`: `horse-with-no-namespace`. + +```{note} +If you let `zc.buildout` install `horse-with-no-namespace`, it won't work. +It really must be installed by `pip` into the same virtual environment where you have installed `zc.buildout`. +``` + +The recommendation is to migrate all namespace packages to native namespaces. +This includes the `collective` namespace that a lot of Plone add-ons use. +This {doc}`guide ` describes the needed steps. + +## Start separating Classic UI code from the core + +In Plone 6, the Python backend includes the Classic UI frontend. +You can't get one without the other. +If you use the Volto frontend, this means that you get lots of code that you never use. + +Plone 6.2 starts separating Classic UI code from the core of Plone. +This is ongoing work, described in {term}`PLIP` [3953](https://github.com/plone/Products.CMFPlone/issues/3953). +You won't yet get less code: this is preparation for a more complete separation in Plone 7. + +The focus currently is on moving page templates into the `plone.app.layout` package. +Templates from the following packages are now in a new location: + +* `plone.locking` +* `plone.protect` + +```{note} +If you use the `z3c.jbot` add-on to override a template that has been moved, your override will still work. +This is because we keep a mapping from the old to the new location. +For example, `plone.locking` registers that `plone.locking.browser.info.pt` has a new location: `plone.app.layout.viewlets.locking.pt`. +You should rename your override to the new location if you no longer need compatibility with Plone 6.1 or earlier. +``` diff --git a/docs/upgrade/index.md b/docs/upgrade/index.md index 9e6905db07..926155fd3b 100644 --- a/docs/upgrade/index.md +++ b/docs/upgrade/index.md @@ -19,6 +19,7 @@ Plone has several components, each of which have their own upgrade guides: For Plone 6 the most relevant guides are: +- {doc}`../backend/upgrading/version-specific-migration/upgrade-to-62` - {doc}`../backend/upgrading/version-specific-migration/upgrade-to-61` - {doc}`../backend/upgrading/version-specific-migration/upgrade-to-60` - {doc}`../backend/upgrading/version-specific-migration/migrate-to-volto` diff --git a/styles/config/vocabularies/Plone/accept.txt b/styles/config/vocabularies/Plone/accept.txt index b2c97f978f..d1f3d57c75 100644 --- a/styles/config/vocabularies/Plone/accept.txt +++ b/styles/config/vocabularies/Plone/accept.txt @@ -28,6 +28,8 @@ jQuery libxslt middleware Mockup +namespace +namespaces npm nvm Pastanaga From b6b66bf7f2f8d55ba437449bb84eebbc5a5119f1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 15 Dec 2025 02:59:20 -0800 Subject: [PATCH 2/2] Apply suggestions from code review --- .../version-specific-migration/upgrade-to-62.md | 10 ++++++---- styles/config/vocabularies/Plone/accept.txt | 3 +-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md index 7fdebd923d..e239c8ded9 100644 --- a/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-62.md @@ -30,7 +30,8 @@ The third style is `pkgutil`, but Plone has never used it. Native namespaces exist since Python 3.3. Because Plone started in the days of Python 2, it has always used `pkg_resources`. `pkg_resources` is part of the `setuptools` package. -This part is deprecated: it's scheduled to be removed around the end of 2025, in `setuptools` 81. +This part is deprecated. +It's scheduled to be removed around the end of 2025, in `setuptools` 81. This means Plone needs to move to native namespaces. In general, this move shouldn't cause problems for integrators. @@ -48,7 +49,7 @@ In a normal install: * `zc.buildout` 5 works fine. If for one or both of these packages you don't use a final release from https://pypi.org, but an editable install, it may not work. -You can solve this by installing an extra package with `pip`: `horse-with-no-namespace`. +You can solve this by installing an extra package with `pip`, `horse-with-no-namespace`. ```{note} If you let `zc.buildout` install `horse-with-no-namespace`, it won't work. @@ -67,7 +68,8 @@ If you use the Volto frontend, this means that you get lots of code that you nev Plone 6.2 starts separating Classic UI code from the core of Plone. This is ongoing work, described in {term}`PLIP` [3953](https://github.com/plone/Products.CMFPlone/issues/3953). -You won't yet get less code: this is preparation for a more complete separation in Plone 7. +You won't yet get less code yet. +This PLIP is preparation for a more complete separation in Plone 7. The focus currently is on moving page templates into the `plone.app.layout` package. Templates from the following packages are now in a new location: @@ -78,6 +80,6 @@ Templates from the following packages are now in a new location: ```{note} If you use the `z3c.jbot` add-on to override a template that has been moved, your override will still work. This is because we keep a mapping from the old to the new location. -For example, `plone.locking` registers that `plone.locking.browser.info.pt` has a new location: `plone.app.layout.viewlets.locking.pt`. +For example, `plone.locking` registers that `plone.locking.browser.info.pt` has a new location, `plone.app.layout.viewlets.locking.pt`. You should rename your override to the new location if you no longer need compatibility with Plone 6.1 or earlier. ``` diff --git a/styles/config/vocabularies/Plone/accept.txt b/styles/config/vocabularies/Plone/accept.txt index d1f3d57c75..60bbe49f33 100644 --- a/styles/config/vocabularies/Plone/accept.txt +++ b/styles/config/vocabularies/Plone/accept.txt @@ -28,8 +28,7 @@ jQuery libxslt middleware Mockup -namespace -namespaces +namespaces? npm nvm Pastanaga