From b937dfef1cef25f20584b45c54aadb225fd2fe6b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 00:18:32 -0700 Subject: [PATCH 01/17] More uv managed revisions - The instructions for installation from PyPI have only two options, Cookieplone and Buildout, not the three options from the include. The attempt to avoid DRY with an include won't work here. --- docs/admin-guide/add-ons.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index 95f46d798..0f4242ac9 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -98,7 +98,32 @@ You can control which version of an add-on to install through "version pinning." ### Install the add-on -```{include} /_inc/_build-and-restart.md +If the backend is running, stop it with {kbd}`ctrl-c`. + +To actually download and install the new add-on, run the following command. + +`````{tab-set} +````{tab-item} Cookieplone +:sync: cookieplone + +```shell +make backend-build +``` +```` + +````{tab-item} Buildout +:sync: buildout + +```shell +bin/buildout -N +``` +```` +````` + +Next, restart the backend. + +```{seealso} +{doc}`run-plone` ``` In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form. From 27138bc76456150277379291c3fabe3a1f409354 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 00:30:27 -0700 Subject: [PATCH 02/17] - DRY for complete the add-on installation --- docs/_inc/_add-on-complete-install.md | 7 +++++++ docs/admin-guide/add-ons.md | 18 ++++-------------- 2 files changed, 11 insertions(+), 14 deletions(-) create mode 100644 docs/_inc/_add-on-complete-install.md diff --git a/docs/_inc/_add-on-complete-install.md b/docs/_inc/_add-on-complete-install.md new file mode 100644 index 000000000..e9255c5c1 --- /dev/null +++ b/docs/_inc/_add-on-complete-install.md @@ -0,0 +1,7 @@ +In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form. + +Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on. + +Some add-ons have configuration options. +To configure such add-ons, return to the {guilabel}`Site Setup` control panel. +At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed. diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index 0f4242ac9..3e7f85ebb 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -126,13 +126,8 @@ Next, restart the backend. {doc}`run-plone` ``` -In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form. - -Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on. - -Some add-ons have configuration options. -To configure such add-ons, return to the {guilabel}`Site Setup` control panel. -At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed. +```{include} /_inc/_add-on-complete-install.md +``` ## Install an add-on from source @@ -268,10 +263,5 @@ This way you always get the version that's currently available in the source con ```{include} /_inc/_build-and-restart.md ``` -In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form. - -Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on. - -Some add-ons have configuration options. -To configure such add-ons, return to the {guilabel}`Site Setup` control panel. -At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed. +```{include} /_inc/_add-on-complete-install.md +``` From 9f2abe4d6adc5c46ef69fddd15ee2a068546b085 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:14:32 -0700 Subject: [PATCH 03/17] "mxdev" isn't an inline literal --- docs/admin-guide/add-ons.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index 3e7f85ebb..1f22a843b 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -210,7 +210,7 @@ extras=test ```{seealso} The {file}`mx.ini` file configures a tool called {term}`mxdev`. -For an explanation of why Plone uses `mxdev`, see {ref}`manage-packages-mxdev-label`. +For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`. ``` ```` From 96fd19b276d9e84eecea8e949668631c083ed96c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:26:35 -0700 Subject: [PATCH 04/17] "mxdev" isn't an inline literal --- docs/admin-guide/override-core.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md index 0ee292d26..859f2a6b4 100644 --- a/docs/admin-guide/override-core.md +++ b/docs/admin-guide/override-core.md @@ -67,7 +67,7 @@ version-overrides = ```{seealso} The {file}`mx.ini` file configures a tool called {term}`mxdev`. -For an explanation of why Plone uses `mxdev`, see {ref}`manage-packages-mxdev-label`. +For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`. ``` ```` @@ -164,7 +164,7 @@ extras = test ```{seealso} The {file}`mx.ini` file configures a tool called {term}`mxdev`. -For an explanation of why Plone uses `mxdev`, see {ref}`manage-packages-mxdev-label`. +For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`. ``` ```` From 92cf1054566b7941dc0cf51ae8f54a3f6078d6c9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:27:07 -0700 Subject: [PATCH 05/17] tighten up spacing --- docs/admin-guide/override-core.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md index 859f2a6b4..529e16189 100644 --- a/docs/admin-guide/override-core.md +++ b/docs/admin-guide/override-core.md @@ -37,7 +37,6 @@ For projects created with Cookieplone, select the tab labeled: ``` `````{tab-set} - ````{tab-item} uv :sync: uv @@ -50,7 +49,6 @@ constraint-dependencies = [ "plone.api==2.0.0a3", ] ``` - ```` ````{tab-item} pip @@ -69,7 +67,6 @@ version-overrides = The {file}`mx.ini` file configures a tool called {term}`mxdev`. For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`. ``` - ```` ````{tab-item} Buildout @@ -100,9 +97,7 @@ plone.api = 2.0.0a3 ```{note} The version pins specified in the `[versions]` section will take precedence over the pins inherited from `https://dist.plone.org/release/6-latest/versions.cfg`. ``` - ```` - ````` ### Install the package @@ -128,7 +123,6 @@ For projects created with Cookieplone, select the tab labeled: ``` `````{tab-set} - ````{tab-item} uv :sync: uv @@ -146,7 +140,6 @@ Add the local directory to your uv project as an editable package. cd backend uv add --editable ../plone.restapi ``` - ```` ````{tab-item} pip @@ -166,7 +159,6 @@ extras = test The {file}`mx.ini` file configures a tool called {term}`mxdev`. For an explanation of why Plone uses mxdev, see {ref}`manage-packages-mxdev-label`. ``` - ```` ````{tab-item} Buildout @@ -207,9 +199,7 @@ Setting an empty version ensures that the copy of `plone.restapi` from source co ```{seealso} This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. ``` - ```` - ````` ### Install the package From 15f47ff4da980f9c284b58832af95870da98db22 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:27:34 -0700 Subject: [PATCH 06/17] grammar --- docs/admin-guide/override-core.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md index 529e16189..4e5677333 100644 --- a/docs/admin-guide/override-core.md +++ b/docs/admin-guide/override-core.md @@ -16,11 +16,11 @@ Sometimes you will need to override one or more package versions to fix a bug. ## Override the version of a core Plone package -The Python packages which are dependencies of Plone are pinned to specific versions at the time a Plone release is created. +The Python packages on which Plone depends are pinned to specific versions at the time a Plone release is created. This section describes how to override the version of one of these packages, in case you need a newer one. ```{caution} -By doing this, you are intentionally using a combination of package versions that has not been tested by the Plone development team. +When you override package versions, the combination of packages isn't tested by the Plone development team. Use at your own risk! ``` From 6d7253c5cb8ecc0b63fb329742bdf122eb971c60 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:28:00 -0700 Subject: [PATCH 07/17] Increasing specificity --- docs/admin-guide/override-core.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md index 4e5677333..8925b3e6c 100644 --- a/docs/admin-guide/override-core.md +++ b/docs/admin-guide/override-core.md @@ -40,7 +40,7 @@ For projects created with Cookieplone, select the tab labeled: ````{tab-item} uv :sync: uv -Edit `constraint-dependencies` in the file {file}`pyproject.toml`. +In the file {file}`pyproject.toml`, under the table `[tool.uv]`, edit `constraint-dependencies`. This example uses `plone.api`. ``` @@ -54,7 +54,7 @@ constraint-dependencies = [ ````{tab-item} pip :sync: pip -Add a version override to the file {file}`backend/mx.ini`. +In the file {file}`backend/mx.ini`, under the `[settings]` section, add `version-overrides` setting. This example uses `plone.api`. ``` From 1aa8a9375f919a2cf6cbf9fd04da33cf3df2219e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:28:19 -0700 Subject: [PATCH 08/17] Make URL clickable --- docs/admin-guide/override-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md index 8925b3e6c..8ca79527e 100644 --- a/docs/admin-guide/override-core.md +++ b/docs/admin-guide/override-core.md @@ -95,7 +95,7 @@ plone.api = 2.0.0a3 ``` ```{note} -The version pins specified in the `[versions]` section will take precedence over the pins inherited from `https://dist.plone.org/release/6-latest/versions.cfg`. +The version pins specified in the `[versions]` section will take precedence over the pins inherited from https://dist.plone.org/release/6-latest/versions.cfg. ``` ```` ````` From 85ec4e83040034b900087dc8f2956cab524dfc10 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:37:59 -0700 Subject: [PATCH 09/17] Add an introductory paragraph to the empty subheading --- docs/conceptual-guides/package-management.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conceptual-guides/package-management.md b/docs/conceptual-guides/package-management.md index 05970a81b..f0b04becd 100644 --- a/docs/conceptual-guides/package-management.md +++ b/docs/conceptual-guides/package-management.md @@ -26,6 +26,10 @@ Python itself has a complex and convoluted history with package management, as [ ## Manage backend Python packages +pip with mxdev and uv are supported tools to manage the Python packages in the Plone backend. +The following sections explain each of these tools in more detail. + + ### pip By convention in the Python community, {term}`pip` is commonly used to install Python packages. From a084a8b8c4b15f7091b6b5c15e3358b3b815f8a2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:43:41 -0700 Subject: [PATCH 10/17] - Link to sections in add-ons documentation - spelling of mxdev and pip - Oxford comma --- docs/admin-guide/add-ons.md | 2 ++ docs/conceptual-guides/package-management.md | 12 ++++++------ 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index 1f22a843b..eb6f0a7fb 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -130,6 +130,8 @@ Next, restart the backend. ``` +(install-an-add-on-from-source-label)= + ## Install an add-on from source This section describes how to install an unreleased add-on from a source control system, such as GitHub. diff --git a/docs/conceptual-guides/package-management.md b/docs/conceptual-guides/package-management.md index f0b04becd..2bc67e9ca 100644 --- a/docs/conceptual-guides/package-management.md +++ b/docs/conceptual-guides/package-management.md @@ -11,7 +11,7 @@ myst: Plone 6 consists of a collection of Python and Node.js packages. Over the decades of its existence, Plone has used several package management tools, sometimes multiple tools at one time. -Each one has its strengths and weaknesses for performing specific tasks, such as installation, conflict resolution, updates and upgrades, and working with virtual environments and across platforms. +Each one has its strengths and weaknesses for performing specific tasks, such as installation, conflict resolution, updates, upgrades, and working with virtual environments and across platforms. With Volto as the default frontend in Plone 6, first npm, then pnpm, was brought into the mix as a package manager for its Node.js packages. @@ -53,20 +53,20 @@ As a best practice, pip should always be used inside a specific Python {term}`vi During development, it is sometimes necessary to override the Plone version constraints. This makes it possible to: -- install a newer version of a core Plone package that was released with a bugfix -- install an unreleased core Plone package from a source control system +- {ref}`install a newer version of a core Plone package that was released to PyPI ` with a bugfix +- {ref}`install an unreleased core Plone package from a source control system ` -Unfortunately pip does not allow overriding constraints this way. +pip does not allow overriding constraints this way. {term}`mxdev` solves this issue. -`mxdev` resolves Plone constraints according to your needs for pinning versions or source checkouts. +mxdev resolves Plone constraints according to your needs for pinning versions or source checkouts. It reads its configuration file {file}`mx.ini`, and your {file}`requirements.txt` and {file}`constraints.txt` files. Then it fetches the requirements and constraints of Plone. Finally, it writes new combined requirements in {file}`requirements-mxdev.txt` and new constraints in {file}`constraints-mxdev.txt`. Together these two files contain the combined requirements and constraints, but modified according to the configuration in {file}`mx.ini`. The generated files indicate from where the constraints were fetched, and comments are added when a modification was necessary. -`mxdev` does not run `pip` or install packages. +mxdev does not run pip or install packages. You or your development tools, such as GNU Make, must perform that step. ```{seealso} From 3bdf73b65135f499c1079be5436f01071f34c75b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:50:21 -0700 Subject: [PATCH 11/17] Fix Vale errors --- styles/config/vocabularies/Plone/accept.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/styles/config/vocabularies/Plone/accept.txt b/styles/config/vocabularies/Plone/accept.txt index b3666e096..9d106272a 100644 --- a/styles/config/vocabularies/Plone/accept.txt +++ b/styles/config/vocabularies/Plone/accept.txt @@ -10,7 +10,7 @@ backport(ed|ing) Barceloneta [Bb]oolean bugfix -buildout +[Bb]uildout cacheable Classic UI CMSUI @@ -28,6 +28,7 @@ jQuery libxslt middleware Mockup +mxdev namespaces? npm nvm @@ -39,6 +40,7 @@ PLIP(s) Plone plonecli pluggab(le|ility) +pnpm [Pp]ortlets? prerendered programatically @@ -67,4 +69,5 @@ Volto Vue webpack wireframe +xkcd Zope From ba68fccb428e820ab5c42f7cc06329582c925dae Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:52:29 -0700 Subject: [PATCH 12/17] Fix Vale errors --- styles/config/vocabularies/Plone/accept.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/styles/config/vocabularies/Plone/accept.txt b/styles/config/vocabularies/Plone/accept.txt index 9d106272a..c0b583ac1 100644 --- a/styles/config/vocabularies/Plone/accept.txt +++ b/styles/config/vocabularies/Plone/accept.txt @@ -13,15 +13,18 @@ bugfix [Bb]uildout cacheable Classic UI +CMSs CMSUI CommonJS Cookieplone doctest ETags? +extranets [Ff]avicon folderish fieldset getter +interoperate JavaScript [Jj]enkins jQuery From 90ad9b7d91e3da8d5a938a5f0764a1e3ef7470c0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:55:27 -0700 Subject: [PATCH 13/17] Remove unnecessary section subheading --- docs/conceptual-guides/package-management.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/conceptual-guides/package-management.md b/docs/conceptual-guides/package-management.md index 2bc67e9ca..10a351361 100644 --- a/docs/conceptual-guides/package-management.md +++ b/docs/conceptual-guides/package-management.md @@ -93,9 +93,8 @@ It not only installs packages, but can set up other things using an extensible s Buildout does not install Python packages into a virtual environment. Instead, it creates scripts that add the necessary packages to `sys.path` before running the script target. -## Manage frontend Node.js packages -### pnpm +## Manage frontend Node.js packages Plone uses {term}`pnpm` to install Node.js packages. From cd86376dff4c1507af8f9687ecda4a2d14f7ca50 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 02:59:49 -0700 Subject: [PATCH 14/17] Promote uv as the first package manager, and combine its first two sentences. --- docs/conceptual-guides/package-management.md | 24 ++++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/conceptual-guides/package-management.md b/docs/conceptual-guides/package-management.md index 10a351361..c2c59b109 100644 --- a/docs/conceptual-guides/package-management.md +++ b/docs/conceptual-guides/package-management.md @@ -26,10 +26,21 @@ Python itself has a complex and convoluted history with package management, as [ ## Manage backend Python packages -pip with mxdev and uv are supported tools to manage the Python packages in the Plone backend. +uv, pip with mxdev, buildout and are supported tools to manage the Python packages in the Plone backend. The following sections explain each of these tools in more detail. +### uv + +{term}`uv` is a package manager which is popular for its speed, its ability to manage the installation of Python itself, and its ability to consistently reproduce installed packages using a {file}`uv.lock` file. + +When a project is fully managed using uv, it is configured in `pyproject.toml` and the packages are installed using `uv sync`. + +uv also has a backwards-compatible mode which works more like pip, and installs packages into a virtual environment via the command `uv pip install`. + +If you create a Plone project using Cookieplone, it creates a backend managed by uv. + + ### pip By convention in the Python community, {term}`pip` is commonly used to install Python packages. @@ -73,17 +84,6 @@ You or your development tools, such as GNU Make, must perform that step. {doc}`/admin-guide/add-ons` ``` -### uv - -More recently, {term}`uv` has become popular as a way to install Python packages. -This package manager is popular for its speed, its ability to manage the installation of Python itself, and its ability to consistently reproduce installed packages using a {file}`uv.lock` file. - -When a project is fully managed using uv, it is configured in `pyproject.toml` and the packages are installed using `uv sync`. - -uv also has a backwards-compatible mode which works more like pip, and installs packages into a virtual environment via the command `uv pip install`. - -If you create a Plone project using Cookieplone, it creates a backend managed by uv. - ### buildout {term}`Buildout` is a tool for installing Python packages that has been used in the Plone community since about 2007, and is still preferred by some members of the community. From 8e78a90e83fe24ed88d3f858232377f50dbc8340 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 03:08:44 -0700 Subject: [PATCH 15/17] MyST markup, grammar, link to the pip interface for uv --- docs/conceptual-guides/package-management.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conceptual-guides/package-management.md b/docs/conceptual-guides/package-management.md index c2c59b109..99859eee7 100644 --- a/docs/conceptual-guides/package-management.md +++ b/docs/conceptual-guides/package-management.md @@ -34,9 +34,9 @@ The following sections explain each of these tools in more detail. {term}`uv` is a package manager which is popular for its speed, its ability to manage the installation of Python itself, and its ability to consistently reproduce installed packages using a {file}`uv.lock` file. -When a project is fully managed using uv, it is configured in `pyproject.toml` and the packages are installed using `uv sync`. +When a project is fully managed using uv, it is configured in its {file}`pyproject.toml` file, and its packages are installed using `uv sync`. -uv also has a backwards-compatible mode which works more like pip, and installs packages into a virtual environment via the command `uv pip install`. +uv also has a [pip interface](https://docs.astral.sh/uv/pip/), and installs packages into a virtual environment via the command `uv pip install`. If you create a Plone project using Cookieplone, it creates a backend managed by uv. From 89f00c0ff2f3835236442741e09a9e0a4afa319d Mon Sep 17 00:00:00 2001 From: David Glick Date: Fri, 27 Mar 2026 09:52:20 -0700 Subject: [PATCH 16/17] Update docs/conceptual-guides/package-management.md --- docs/conceptual-guides/package-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conceptual-guides/package-management.md b/docs/conceptual-guides/package-management.md index 99859eee7..e488a89f7 100644 --- a/docs/conceptual-guides/package-management.md +++ b/docs/conceptual-guides/package-management.md @@ -26,7 +26,7 @@ Python itself has a complex and convoluted history with package management, as [ ## Manage backend Python packages -uv, pip with mxdev, buildout and are supported tools to manage the Python packages in the Plone backend. +uv, pip with mxdev, and buildout are supported tools to manage the Python packages in the Plone backend. The following sections explain each of these tools in more detail. From 096965237c8c2f38adac20d1d9ef0cb92c556d53 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 27 Mar 2026 15:08:21 -0700 Subject: [PATCH 17/17] Update docs/admin-guide/override-core.md Co-authored-by: David Glick --- docs/admin-guide/override-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md index 8ca79527e..f428fa841 100644 --- a/docs/admin-guide/override-core.md +++ b/docs/admin-guide/override-core.md @@ -16,7 +16,7 @@ Sometimes you will need to override one or more package versions to fix a bug. ## Override the version of a core Plone package -The Python packages on which Plone depends are pinned to specific versions at the time a Plone release is created. +Plone's Python package dependencies are pinned to specific versions at the time a Plone release is created. This section describes how to override the version of one of these packages, in case you need a newer one. ```{caution}