Merge branch '6.0' into migrate-backing-up-plone

Author: stevepiercy

Makefile

@@ -73,6 +73,18 @@ docs/volto:  ## Setup Volto docs
 	@echo "Documentation of volto initialized."
 	@echo
 
+ln-seven:  ## Toggle the symlink to Seven
+	rm docs/volto
+	ln -s ../submodules/volto/docs ./docs/volto
+	@echo "Symlink to Volto changed to Seven."
+	@echo
+
+ln-volto:  ## Toggle the symlink to Volto
+	rm docs/volto
+	ln -s ../submodules/volto/docs/source ./docs/volto
+	@echo "Symlink to Seven changed to Volto."
+	@echo
+
 .PHONY: deps
 deps: venv/bin/python docs/volto docs/plone.restapi venv/plone.api-install  ## Create Python virtual environment, install requirements, initialize or update the volto, plone.restapi, and plone.api submodules, create symlinks to the source files, and finally install plone.api.
 

docs/_inc/_hardware-requirements.md

@@ -0,0 +1,9 @@
+Installing Python is beyond the scope of this documentation.
+However, it is recommended to use a Python version manager, {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.1 requires Python version {{SUPPORTED_PYTHON_VERSIONS_PLONE61}}.

docs/_inc/_install-python-plone61.md

@@ -60,7 +60,7 @@ Here, the event handler code will only be executed if the object is a content ty
 If you want this to be interface agnostic, insert an asterix `*` as a wildcard instead.
 
 The third line defines the event on which this should happen, which is `IObjectCreatedEvent`. 
-For more available possible events to use as a trigger, see {ref}`subscribers-event-handlers`. 
+For more available possible events to use as a trigger, see {ref}`subscribers-event-types-label`. 
 
 The fourth line gives the path to the callable function to be executed.
 

docs/_inc/_install-uv.md

@@ -371,7 +371,7 @@ The Plone Documentation Team adopted additional guidelines.
     To make that work in Volto, set your browser width to 1180 pixels.
     You will notice that the drag and trash icons for each block move inside the block from outside.
 
-    If you create images wider than 740 pixels, then you must use image display enhancement as described in {ref}`enhance-images-label`.
+    If you create images wider than 740 pixels, then you must use image display enhancement as described in {ref}`enhance-media-label`.
 -   In user documentation, provide screenshots of each step where the interface changes.
     It is painstaking, but worth the effort.
     Provide sufficient detail of what each option is and does.

docs/backend/subscribers.md

@@ -20,6 +20,7 @@ To contribute to any project in Plone, you must follow the policies of the [Plon
 This chapter covers policies that apply to all Plone projects.
 Other chapters cover any variations and additional policies for each project.
 
+
 (contributing-sign-and-return-the-plone-contributor-agreement-label)=
 
 ## Sign and return the Plone Contributor Agreement
@@ -77,6 +78,7 @@ Someone will help identify in which of the dozens of repositories that make up P
 ```{include} /_inc/_continuous-integration.md
 ```
 
+
 (contributing-change-log-label)=
 
 ## Change log entry
@@ -102,11 +104,11 @@ When making a change to its documentation, set up, continuous integration, or ot
 
 The change log entry's format must be `###.type`, where `###` is the referenced GitHub issue or pull request number, `.` is the literal extension delimiter, and `type` is one of the following strings.
 
-- `breaking` for breaking changes
-- `bugfix` for bug fixes
-- `documentation` for documentation
-- `feature` for new features
-- `internal` for internal changes
+-   `breaking` for breaking changes
+-   `bugfix` for bug fixes
+-   `documentation` for documentation
+-   `feature` for new features
+-   `internal` for internal changes
 
 A package configures the types it allows in a file `towncrier.toml` located at the root of its package directory.
 
@@ -156,6 +158,25 @@ To standarize the developer experience across packages, a configuration tool is
 
 See the [tool documentation](https://github.com/plone/meta) for more information.
 
+
+(contributing-guidance-for-merging-pull-requests-label)=
+
+## Guidance for merging pull requests
+
+-   If you have any doubt, don't merge, but ask.
+-   All {doc}`CI checks <core/continuous-integration>` must pass, unless there is a good reason to ignore it.
+    If you ignore a check, then write the good reason either in a comment or in the merge message.
+-   Get at least one approval from another Plone contributor, preferably a member of the GitHub Team for the repository.
+-   If the pull request has documentation, ask for a review from `@plone/documentation-team`.
+-   Usually the merge message populates with all the commit messages, but some repositories aren't configured to do this.
+    It's helpful to include a descriptive message in the merge request.    
+-   After merging, look for any linked issues that should be closed, and close them.
+    Sometimes the contributor forgets to include `closes #123` in the description, which would automatically close the related issue.
+-   If the change is a bugfix, make sure that it is not merged to an older release branch unless it is also merged in separate pull request to `main`.
+-   Thank the contributor.
+-   🍻
+
+
 (contributing-specific-contribution-policies-for-projects-label)=
 
 ## Specific contribution policies of projects

docs/contributing/documentation/authors.md

@@ -28,10 +28,9 @@ You will need to work in one repository for Plone core, and optionally another o
 ## Prerequisites
 
 Request write access to https://github.com/collective/plone.app.locales to be able to commit your translation directly.
-
 To do so, [join the collective GitHub organization](https://collective.github.io/).
 
-Optionally sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement) for translating Volto.
+Because translation strings do not constitute an original "work", translators are not required to sign the [Plone Contributor Agreement (PCA)](https://plone.org/foundation/contributors-agreement) to contribute translations to either Plone or Volto.
 
 
 (contributing-plone-core-translations-translate-plone-classic-ui-label)=
@@ -75,10 +74,7 @@ The process of translating the Volto frontend is the following.
     -  To update a translation, translate your language's `po` file found at `locales/{language_code}/LC_MESSAGES/volto.po`.
     -  To create a new translation, create a new directory at `locales/{language_code}/LC_MESSAGES/`, copy the file `locales/volto.pot` to `locales/{language_code}/LC_MESSAGES/volto.po` (note to drop the trailing `t`), and start translating.
 
-4. Run `make i18n` to convert your `po` files into `json`.
-   Volto loads these `json` files to provide translated text strings in the interface.
-
-5. Commit your changes, and create a pull request.
+4.  Commit your changes, and create a pull request.
 
 ```{seealso}
 {doc}`Volto frontend development internationalization </volto/development/i18n>`
@@ -98,17 +94,13 @@ Plone gets free hosting at the [Hosted](https://hosted.weblate.org/) platform th
 
 Translators will need to create an account on Weblate with an email and password.
 Authentication with GitHub and other third-party accounts might not work.
+You can [configure your Weblate account to receive notifications](https://hosted.weblate.org/accounts/profile/#notifications) either automatically whenever you make a contribution to a project or manually watch specific projects.
 
 Translators can go to the [Plone project in Weblate](https://hosted.weblate.org/projects/plone/).
 
 You will see several components listed.
 The `volto` component is for the package `volto`, whose repository is at https://github.com/plone/volto.
 
-```{note}
-At this moment Volto translations can't be contributed using Weblate.
-The Volto Team are working on this issue, and hope to fix it as soon as possible.
-```
-
 All other components are for the package `plone.app.locales`, whose repository is at https://github.com/collective/plone.app.locales.
 
 See the Weblate documentation, [Translating using Weblate](https://docs.weblate.org/en/latest/user/translating.html), for how to use it to write translations.
@@ -117,7 +109,7 @@ When you save a translation, then it is committed on a branch used only for tran
 
 [See recent commits to the package `plone.app.locales`](https://github.com/collective/plone.app.locales/commits/master/).
 
-Maintainers will periodically create a pull request from the changes, and merge it.
+Maintainers will periodically review the pull request that Weblate creates automatically, and merge it.
 
 
 (contributing-plone-core-translations-support-label)=

docs/contributing/index.md

@@ -12,41 +12,40 @@ myst:
 
 # Install Plone with Cookieplone
 
-This chapter describes how you can create a web application using the {term}`Cookieplone` template.
-
-This template is the recommended way to start a new Plone project using the Volto frontend.
+This chapter describes how you can create a web application using {term}`Cookieplone`.
+Cookieplone is the recommended way to create a Plone project as an add-on using the Volto frontend.
 It also includes tools for development and deployment.
 
 ```{seealso}
 For other installation options, see {ref}`get-started-install-label`.
 ```
 
 ```{versionadded} Volto 18.0.0-alpha.43
-{term}`Cookieplone` was added as the recommended template to create a Plone project with Volto starting in Volto 18.0.0-alpha.43 and above.
+{term}`Cookieplone` was added as the recommended tool to create a Plone project with Volto starting in Volto 18.0.0-alpha.43 and above.
 ```
 
 
 (create-project-cookieplone-system-requirements)=
 
 ## System requirements
 
-Plone 6 has both hardware requirements and software prerequisites.
+Plone has both hardware requirements and software prerequisites.
 
 
-### Supported web browsers
+(create-project-cookieplone-hardware-requirements-label)=
 
-```{include} /volto/_inc/_install-browser-reqs-volto.md
-```
+### Hardware requirements
 
-```{include} /_inc/_install-browser-reqs-classic-ui.md
+```{include} /volto/_inc/_hardware-requirements.md
 ```
 
 
-(create-project-cookieplone-hardware-requirements-label)=
+### Supported web browsers
 
-### Hardware requirements
+```{include} /volto/_inc/_install-browser-reqs-volto.md
+```
 
-```{include} /_inc/_hardware-requirements.md
+```{include} /_inc/_install-browser-reqs-classic-ui.md
 ```
 
 
@@ -66,32 +65,23 @@ Plone 6 has both hardware requirements and software prerequisites.
 
 #### uv
 
-```{include} /_inc/_install-uv.md
+```{include} ../volto/_inc/_install-uv.md
 ```
 
 
-#### Python
-
-{term}`uv` will download and install the required Python version for your project.
-
-
 #### nvm
 
 ```{include} ../volto/_inc/_install-nvm.md
 ```
 
 
+(prerequisites-for-installation-nodejs-label)=
+
 #### Node.js
 
 ```{include} ../volto/_inc/_install-nodejs.md
 ```
 
-3.  Enable {term}`corepack` so that Node.js will install {term}`pnpm` as a package manager.
-
-    ```shell
-    npm i -g corepack@latest && corepack enable
-    ```
-
 
 #### Make
 
@@ -109,8 +99,7 @@ Plone 6 has both hardware requirements and software prerequisites.
 
 ## Generate the project
 
-After satisfying the prerequisites and having activated an LTS version of Node,
-generate the project.
+After satisfying the prerequisites and having {ref}`activated an LTS version of Node.js <prerequisites-for-installation-nodejs-label>`, generate the project.
 
 ```shell
 uvx cookieplone project