Prepare for Plone 6.2 release v2

docs/_inc/_install-python-plone62.md

@@ -0,0 +1,9 @@
+Installing Python is beyond the scope of this documentation.
+However, it is recommended to use a Python version manager, such as {term}`uv` or {term}`pyenv`, that allows you to install multiple versions of Python on your development environment without destroying your system's Python.
+
+```{warning}
+Do not create or activate a Python virtual environment at this time.
+The instructions below will create one.
+```
+
+Plone 6.2 requires Python version {{SUPPORTED_PYTHON_VERSIONS_PLONE62}}.

docs/admin-guide/add-ons.md

@@ -18,206 +18,168 @@ 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
+## Cookieplone
 
-This section describes how to install an add-on that is released on {term}`PyPI`.
+Use the following instructions if you installed Plone with Cookieplone.
 
 
-(configure-add-on-installation-pypi-label)=
-
-### Configure add-on installation
-
-First, configure your project according to the instructions in the tabbed interface below.
-Select the tab according to the method you used to create your project.
-
-`````{tab-set}
-````{tab-item} Cookieplone
-:sync: cookieplone
+### Install an add-on
 
 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.4",
+    "Products.CMFPlone==6.1.1",
     "plone.api",
     "plone.classicui",
     "plone.app.caching",
-    "collective.easyform==4.5.1",
+    "collective.easyform==4.4.0",
 ]
 ```
 
-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.
+```{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
 ```
-````
-
-````{tab-item} Buildout
-:sync: buildout
 
-Update the file {file}`buildout.cfg`.
-This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
+Stop the backend with {kbd}`ctrl-c`.
 
-```cfg
-[buildout]
-extends =
-    https://dist.plone.org/release/6-latest/versions.cfg
+To actually download and install the new add-on, run the following command.
 
-parts =
-    instance
+```shell
+make backend-build
+```
 
-[instance]
-recipe = plone.recipe.zope2instance
-user = admin:admin
-http-address = 8080
-eggs =
-    Plone
-    collective.easyform
+Now restart the backend.
 
-[versions]
-collective.easyform = 4.5.1
+```{seealso}
+{doc}`run-plone`
 ```
-````
-`````
 
-```{tip}
-You can control which version of an add-on to install through "version pinning."
+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.
 
--   Specify the add-on version to avoid its unintentional upgrade.
--   Leave it off to always install the latest version.
-```
+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.
 
-(install-the-add-on-pypi-label)=
 
-### Install the add-on
+### Install an add-on from source
 
-If the backend is running, stop it with {kbd}`ctrl-c`.
+An add-on can be installed from a source control system such as GitHub.
 
-To actually download and install the new add-on, run the following command.
+Add a line with the name of your add-on in the file {file}`backend/requirements.txt`.
+This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
 
-`````{tab-set}
-````{tab-item} Cookieplone
-:sync: cookieplone
+```
+collective.easyform
+```
 
-```shell
-make backend-build
+```{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.
 ```
-````
 
-````{tab-item} Buildout
-:sync: buildout
+Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load.
 
-```shell
-bin/buildout -N
+```yaml
+default_context:
+    zcml_package_includes: project_title, collective.easyform
 ```
-````
-`````
 
-Next, restart the backend.
+Finally, add the package's source to the file {file}`mx.ini`.
 
-```{seealso}
-{doc}`run-plone`
+```cfg
+[collective.easyform]
+url=git@github.com:collective/collective.easyform.git
+branch=dev-branch-name
+extras=test
 ```
 
-```{include} /_inc/_add-on-complete-install.md
+```{seealso}
+The {file}`mx.ini` file configures a tool called {term}`mxdev`.
+See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/mxdev/blob/main/README.md) for complete information.
 ```
 
+Stop the backend with {kbd}`ctrl-c`.
 
-(install-an-add-on-from-source-label)=
-
-## Install an add-on from source
+To actually download and install the new add-on, run the following command.
 
-This section describes how to install an unreleased add-on from a source control system, such as GitHub.
+```shell
+make backend-build
+```
 
+Now restart the backend.
 
-(configure-add-on-installation-source-label)=
+```{seealso}
+{doc}`run-plone`
+```
 
-### Configure add-on installation
+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.
+An upgrade step might need to be performed in the Plone control panel.
+Follow the upgrade information, if present.
+Else click the {guilabel}`Install` button to complete installation of the add-on.
 
-First, configure your project according to the instructions in the tabbed interface below.
-Select the tab according to your Python package manager.
 
-```{tip}
-For projects created with Cookieplone, select the tab labeled:
+## Buildout
 
--   {guilabel}`pip` if your project has the file {file}`backend/mx.ini`
--   {guilabel}`uv` if your project doesn't have this file
-```
+Use the following instructions if you installed Plone with Buildout.
 
-`````{tab-set}
-````{tab-item} uv
-:sync: uv
+### Install an add-on
 
-Clone the repository into a local directory.
+Update the file {file}`buildout.cfg`.
 This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
 
-```shell
-git clone git@github.com:collective/collective.easyform.git
-```
-
-Add the local directory to your uv project as an editable package.
+```cfg
+[buildout]
+extends =
+    https://dist.plone.org/release/6-latest/versions.cfg
 
-```shell
-cd backend
-uv add --editable ../collective.easyform
-```
+parts =
+    instance
 
-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.
+[instance]
+recipe = plone.recipe.zope2instance
+user = admin:admin
+http-address = 8080
+eggs =
+    Plone
+    collective.easyform
 
-```yaml
-default_context:
-    zcml_package_includes: project_title, collective.easyform
+[versions]
+collective.easyform = 4.2.1
 ```
-````
-
-````{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/).
 
-```{code-block} toml
-:emphasize-lines: 6
-dependencies = [
-    "Products.CMFPlone==6.1.4",
-    "plone.api",
-    "plone.classicui",
-    "plone.app.caching",
-    "collective.easyform",
-]
+```{tip}
+Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
 ```
 
-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.
+To actually download and install the new add-on, run the following command.
 
-```yaml
-default_context:
-    zcml_package_includes: project_title, collective.easyform
+```shell
+bin/buildout
 ```
 
-Finally, add the package's source to the file {file}`mx.ini`.
-
-```cfg
-[collective.easyform]
-url=git@github.com:collective/collective.easyform.git
-branch=dev-branch-name
-extras=test
-```
+Then restart your instance.
 
 ```{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`.
+{doc}`run-plone`
 ```
-````
 
-````{tab-item} Buildout
-:sync: buildout
+
+### Install an add-on from source
+
+You can install an add-on from a source control system such as GitHub.
 
 Update the file {file}`buildout.cfg`.
 This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
@@ -245,25 +207,18 @@ eggs =
 collective.easyform = git https://github.com/collective/collective.easyform.git
 ```
 
-```{seealso}
-This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
-```
-
-````
-`````
+To actually download and install the new add-on, run the following command.
 
-```{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.
+```shell
+bin/buildout
 ```
 
+Then restart your instance.
 
-(install-the-add-on-source-label)=
-
-### Install the add-on
-
-```{include} /_inc/_build-and-restart.md
+```{seealso}
+{doc}`run-plone`
 ```
 
-```{include} /_inc/_add-on-complete-install.md
+```{seealso}
+This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
 ```