From 31ac9dc8c3d94526b60228cb01fba315c23c9705 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 26 Mar 2026 00:57:14 -0700 Subject: [PATCH 1/6] Extension of PR #2072 - Break steps into subheadings, starting with configure the add-on installation --- docs/admin-guide/add-ons.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index a0411bdcf..664e9b1c8 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -20,7 +20,13 @@ See {doc}`/volto/development/add-ons/index`. ## Install an add-on from PyPI -For instructions to install an add-on that is released on {term}`PyPI`, select the tab below according to your Python package manager. +This section describes how to install an add-on that is released on {term}`PyPI` + + +### Configure add-on installation + +First, configure your project according to the instructions in the tabbed interface below. +Select the tab according to your Python package manager. ```{tip} Select the tab for uv if you have a project that was created using Cookieplone, and you have `managed = true` set in the `[tool.uv]` section of the file {file}`backend/pyproject.toml`. From f8b392b8d6f5727acdd940bccf35a129d3801b81 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 26 Mar 2026 00:59:28 -0700 Subject: [PATCH 2/6] Added guilabel role, and reversed the order of instructions in increasing specificity. --- docs/admin-guide/add-ons.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index 664e9b1c8..4b8756067 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -29,8 +29,8 @@ First, configure your project according to the instructions in the tabbed interf Select the tab according to your Python package manager. ```{tip} -Select the tab for uv if you have a project that was created using Cookieplone, and you have `managed = true` set in the `[tool.uv]` section of the file {file}`backend/pyproject.toml`. -Select the tab for pip if you have a project that was created using Cookieplone that does not have this setting. +Select the tab {guilabel}`uv` for projects created with Cookieplone which have in the file {file}`backend/pyproject.toml`, under the `[tool.uv]` table, the setting of `managed = true`. +Select the tab {guilabel}`pip` for projects created with Cookieplone that don't have this setting. ``` `````{tab-set} From a1ac3f9e9c6451de94412153b1b06bc18cd3c0f9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 26 Mar 2026 01:19:32 -0700 Subject: [PATCH 3/6] The instructions for installation from PyPI for both uv and pip were identical. Combine into the project creation method instead. --- docs/admin-guide/add-ons.md | 56 +++++-------------------------------- 1 file changed, 7 insertions(+), 49 deletions(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index 4b8756067..a7a71bb58 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -20,59 +20,17 @@ See {doc}`/volto/development/add-ons/index`. ## Install an add-on from PyPI -This section describes how to install an add-on that is released on {term}`PyPI` +This section describes how to install an add-on that is released on {term}`PyPI`. ### Configure add-on installation First, configure your project according to the instructions in the tabbed interface below. -Select the tab according to your Python package manager. - -```{tip} -Select the tab {guilabel}`uv` for projects created with Cookieplone which have in the file {file}`backend/pyproject.toml`, under the `[tool.uv]` table, the setting of `managed = true`. -Select the tab {guilabel}`pip` for projects created with Cookieplone that don't have this setting. -``` +Select the tab according to the method you used to create your project. `````{tab-set} -````{tab-item} uv - -Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`. -This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/). - -```{code-block} toml -:emphasize-lines: 6 -dependencies = [ - "Products.CMFPlone==6.1.1", - "plone.api", - "plone.classicui", - "plone.app.caching", - "collective.easyform==4.4.0", -] -``` - -```{tip} -Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future. -``` - -Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded. - -```yaml -default_context: - zcml_package_includes: project_title, collective.easyform -``` - -Stop the backend with {kbd}`ctrl-c`. - -To actually download and install the new add-on, run the following command. - -```shell -make backend-build -``` - -```` - -````{tab-item} pip +````{tab-item} Cookieplone Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`. This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/). @@ -80,11 +38,11 @@ This example adds [`collective.easyform`](https://pypi.org/project/collective.ea ```{code-block} toml :emphasize-lines: 6 dependencies = [ - "Products.CMFPlone==6.1.1", + "Products.CMFPlone==6.1.4", "plone.api", "plone.classicui", "plone.app.caching", - "collective.easyform==4.4.0", + "collective.easyform==4.5.1", ] ``` @@ -215,11 +173,11 @@ This example adds [`collective.easyform`](https://pypi.org/project/collective.ea ```{code-block} toml :emphasize-lines: 6 dependencies = [ - "Products.CMFPlone==6.1.1", + "Products.CMFPlone==6.1.4", "plone.api", "plone.classicui", "plone.app.caching", - "collective.easyform", + "collective.easyform==4.5.1", ] ``` From 72c0b9c5fc9af1d69dff6f5df14d3766789d143e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 26 Mar 2026 01:23:05 -0700 Subject: [PATCH 4/6] Move tip outside DRY, and combine both the original and new options. Its target audience is first-timers. --- docs/admin-guide/add-ons.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index a7a71bb58..ab364d097 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -46,10 +46,6 @@ dependencies = [ ] ``` -```{tip} -Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future. -``` - Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded. ```yaml @@ -92,10 +88,6 @@ eggs = collective.easyform = 4.2.1 ``` -```{tip} -Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future. -``` - To actually download and install the new add-on, run the following command. ```shell @@ -106,6 +98,13 @@ bin/buildout -N ````` +```{tip} +You can control which version of an add-on to install through "version pinning." + +- Specify the add-on version to avoid its unintentional upgrade. +- Leave it off to always install the latest version. +``` + Now restart the backend. ```{seealso} From 358fefc21d869e6a9e3129c8d47c7555d04cacf7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 26 Mar 2026 01:32:25 -0700 Subject: [PATCH 5/6] - Move tip outside DRY, and combine both the original and new options. Its target audience is first-timers. - Create new subsection for installation of the add-on. - Sync tabs. --- docs/admin-guide/add-ons.md | 50 +++++++++++++++++++++---------------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index ab364d097..dae68edde 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -29,8 +29,8 @@ First, configure your project according to the instructions in the tabbed interf Select the tab according to the method you used to create your project. `````{tab-set} - ````{tab-item} Cookieplone +:sync: cookieplone Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`. This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/). @@ -46,24 +46,16 @@ dependencies = [ ] ``` -Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded. +To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name. ```yaml default_context: zcml_package_includes: project_title, collective.easyform ``` - -Stop the backend with {kbd}`ctrl-c`. - -To actually download and install the new add-on, run the following command. - -```shell -make backend-build -``` - ```` ````{tab-item} Buildout +:sync: buildout Update the file {file}`buildout.cfg`. This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). @@ -85,17 +77,9 @@ eggs = collective.easyform [versions] -collective.easyform = 4.2.1 +collective.easyform = 4.5.1 ``` - -To actually download and install the new add-on, run the following command. - -```shell -bin/buildout -N -``` - ```` - ````` ```{tip} @@ -105,7 +89,31 @@ You can control which version of an add-on to install through "version pinning." - Leave it off to always install the latest version. ``` -Now restart the backend. +### Install the add-on + +Stop the backend 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 +``` +```` +````` + +Finally, restart the backend. ```{seealso} {doc}`run-plone` From bde905b1d6d56a41e87c3fa76fbe357f65a95011 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 26 Mar 2026 02:06:37 -0700 Subject: [PATCH 6/6] - Repeat for source installation the same DRY, split of configuration and installation, and sync tabs as that for PyPI installation --- docs/admin-guide/add-ons.md | 95 ++++++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 34 deletions(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index dae68edde..e010b7475 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -18,11 +18,15 @@ The Volto frontend has its own system of add-ons using Node.js packages. See {doc}`/volto/development/add-ons/index`. ``` +(install-an-add-on-from-pypi-label)= + ## Install an add-on from PyPI This section describes how to install an add-on that is released on {term}`PyPI`. +(configure-add-on-installation-pypi-label)= + ### Configure add-on installation First, configure your project according to the instructions in the tabbed interface below. @@ -89,6 +93,9 @@ You can control which version of an add-on to install through "version pinning." - Leave it off to always install the latest version. ``` + +(install-the-add-on-pypi-label)= + ### Install the add-on Stop the backend with {kbd}`ctrl-c`. @@ -113,7 +120,7 @@ bin/buildout -N ```` ````` -Finally, restart the backend. +Next, restart the backend. ```{seealso} {doc}`run-plone` @@ -130,18 +137,26 @@ At the bottom of the page, you should see the heading {guilabel}`Add-on Configur ## Install an add-on from source -An unreleased add-on can be installed from a source control system such as GitHub. +This section describes how to install an unreleased add-on from a source control system, such as GitHub. + -For instructions to install an add-on that is released on {term}`PyPI`, select the tab below according to your Python package manager. +(configure-add-on-installation-source-label)= + +### Configure add-on installation + +First, configure your project according to the instructions in the tabbed interface below. +Select the tab according to your Python package manager. ```{tip} -Select the tab for uv if you have a project that was created using Cookieplone, and you have `managed = true` set in the `[tool.uv]` section of the file {file}`backend/pyproject.toml`. -Select the tab for pip if you have a project that was created using Cookieplone that does not have this setting. +For projects created with Cookieplone, select either the tab labeled: + +- {guilabel}`uv` if the file {file}`backend/pyproject.toml`, under the table `[tool.uv]` has the setting of `managed = true` +- {guilabel}`pip` if your project doesn't have this setting ``` `````{tab-set} - ````{tab-item} uv +:sync: uv Clone the repository into a local directory. This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). @@ -157,22 +172,16 @@ cd backend uv add --editable ../collective.easyform ``` -```{note} -When installing an add-on from source, it's best not to pin a version. -This way you always get the version that's currently available in the source control system. -``` - -Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load. +To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name. ```yaml default_context: zcml_package_includes: project_title, collective.easyform ``` - -Stop the backend with {kbd}`ctrl-c`. ```` ````{tab-item} pip +:sync: pip Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`. This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/). @@ -184,16 +193,11 @@ dependencies = [ "plone.api", "plone.classicui", "plone.app.caching", - "collective.easyform==4.5.1", + "collective.easyform", ] ``` -```{note} -When installing an add-on from source, it's best not to pin a version. -This way you always get the version that's currently available in the source control system. -``` - -Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load. +To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name. ```yaml default_context: @@ -213,18 +217,10 @@ 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`. ``` - -Stop the backend with {kbd}`ctrl-c`. - -To actually download and install the new add-on, run the following command. - -```shell -make backend-build -``` - ```` ````{tab-item} Buildout +:sync: buildout Update the file {file}`buildout.cfg`. This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). @@ -251,22 +247,53 @@ eggs = [sources] collective.easyform = git https://github.com/collective/collective.easyform.git ``` +```` +````` + +```{tip} +When installing an add-on from source, it's best not to pin a version. +This way you always get the version that's currently available in the source control system. +``` + + +(install-the-add-on-source-label)= + +### Install the add-on + +Stop the backend with {kbd}`ctrl-c`. To actually download and install the new add-on, run the following command. +`````{tab-set} +````{tab-item} uv +:sync: uv + ```shell -bin/buildout +make backend-build ``` +```` + +````{tab-item} pip +:sync: pip + +```shell +make backend-build +``` +```` +````{tab-item} Buildout +:sync: buildout + +```shell +bin/buildout +``` ```{seealso} This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. ``` - ```` - ````` -Now restart the backend. +Next, restart the backend. ```{seealso} {doc}`run-plone`