From a339a7d8c1946e7d1d8fd39e9745ef3d71963238 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Sat, 1 Apr 2023 06:19:35 -0700
Subject: [PATCH 01/12] Create Plone Core Code contributing documentation -
 Demote documentation contributing into its own folder - Create First-time
 contributors documentation

---
 .../{ => documentation}/admins.md             |   0
 .../{ => documentation}/authors.md            |   0
 docs/contributing/documentation/index.md      | 321 ++++++++++++++++
 .../{ => documentation}/myst-reference.md     |   4 +-
 .../{ => documentation}/setup-build.md        |   0
 .../{ => documentation}/sphinx-extensions.md  |   0
 docs/contributing/first-time.md               | 174 +++++++++
 docs/contributing/index.md                    | 353 +++++-------------
 8 files changed, 595 insertions(+), 257 deletions(-)
 rename docs/contributing/{ => documentation}/admins.md (100%)
 rename docs/contributing/{ => documentation}/authors.md (100%)
 create mode 100644 docs/contributing/documentation/index.md
 rename docs/contributing/{ => documentation}/myst-reference.md (99%)
 rename docs/contributing/{ => documentation}/setup-build.md (100%)
 rename docs/contributing/{ => documentation}/sphinx-extensions.md (100%)
 create mode 100644 docs/contributing/first-time.md

diff --git a/docs/contributing/admins.md b/docs/contributing/documentation/admins.md
similarity index 100%
rename from docs/contributing/admins.md
rename to docs/contributing/documentation/admins.md
diff --git a/docs/contributing/authors.md b/docs/contributing/documentation/authors.md
similarity index 100%
rename from docs/contributing/authors.md
rename to docs/contributing/documentation/authors.md
diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md
new file mode 100644
index 000000000..3e25cf78b
--- /dev/null
+++ b/docs/contributing/documentation/index.md
@@ -0,0 +1,321 @@
+---
+myst:
+  html_meta:
+    "description": "Contributing to Plone 6 Documentation"
+    "property=og:description": "Contributing to Plone 6 Documentation"
+    "property=og:title": "Contributing to Plone 6 Documentation"
+    "keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct"
+---
+
+(contributing-documentation-index-label)=
+
+# Contributing to documentation
+
+This document describes how to contribute to Plone Documentation.
+
+Contributions to the Plone Documentation are welcome.
+
+
+(contributing-permission-to-publish-label)=
+
+## Granting permission to publish
+
+Before you contribute, you must give permission to publish your contribution according to the license we use.
+You may give that permission in two ways.
+
+- Sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement).
+  This method also covers contributions to Plone code.
+  It is a one-time only process.
+- In every pull request or commit message, include the following statement.
+
+  > I, [full name], agree to have this contribution published under Creative Commons 4.0 International License (CC BY 4.0), with attribution to the Plone Foundation.
+
+The Plone Documentation is licensed under the [Creative Commons Attribution 4.0 International License (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
+A copy of the license is included in the root of this repository.
+
+
+(contributing-roles-label)=
+
+## Contributor roles
+
+Contributors to the Plone Documentation may perform one or many roles.
+
+- **Plone users and developers** use this documentation because it is accurate and actively maintained.
+  People in these roles typically contribute minor corrections.
+  They should read {doc}`setup-build` and {doc}`myst-reference`.
+- **Authors** create Plone Documentation.
+  They should read {doc}`setup-build` and {doc}`myst-reference`.
+  They should also read {doc}`authors` for guidance and tips for writing good technical documentation.
+
+
+(contributing-quality-requirements-label)=
+
+## Documentation quality requirements
+
+We use GitHub Actions with every pull request to enforce Plone Documentation quality.
+We recommend that you build the documentation locally to catch errors and warnings early on.
+See {doc}`setup-build` for instructions for how to set up and build the documentation and to run quality checks.
+
+
+(contributing-manage-on-github-label)=
+
+## Making contributions on GitHub
+
+Contributions are managed through git repositories on GitHub.
+
+-   [`documentation`](https://github.com/plone/documentation)
+-   [`plone.api`](https://github.com/plone/plone.api)
+-   [`plone.restapi`](https://github.com/plone/plone.restapi)
+-   [`volto`](https://github.com/plone/volto)
+
+In the Plone organization, it is strongly recommended that you read {ref}`contributing-permission-to-publish-label` and take appropriate action.
+
+After your Plone Contributor Agreement has been approved, and you have been added to the Plone GitHub organization as a member of the [Developers](https://github.com/orgs/plone/teams/developers) team, we recommend that you follow our guidelines.
+
+1.  Discuss whether you should perform any work.
+    Any method below is acceptable, but are listed in order of most likely to get a response.
+
+    -   Search for open issues in the issue trackers of documented projects, and comment on them.
+        If an issue does not already exist for what you want to work on, then create a new issue in its issue tracker.
+
+        As a convenience, at the top right of every page, there is a GitHub navigation menu.
+        Tap, click, or hover over the GitHub Octocat icon for options.
+
+        ```{image} /_static/github-navigation.png
+        :alt: GitHub navigation menu 
+        ```
+
+        You can use this menu to quickly navigate to the `documentation` source repository or open an issue.
+        Note that this navigation convenience is provided only for the `documentation` repository.
+
+        -   [`documentation`](https://github.com/plone/documentation/issues)
+        -   [`plone.api`](https://github.com/plone/plone.api/issues)
+        -   [`plone.restapi`](https://github.com/plone/plone.restapi/issues)
+        -   [`volto`](https://github.com/plone/volto/issues)
+
+    -   Discuss during sprints, conferences, trainings, and other Plone events.
+    -   Ask on the [Plone Community Forum, Documentation topic](https://community.plone.org/c/documentation/13).
+    -   Ask in the [Plone chat on Discord](https://discord.com/invite/zFY3EBbjaj).
+
+1.  For first-time contributors especially, **you do not need to ask to be assigned to, or to work on, an open issue**.
+    As in any open source project, you can start work on open issues at your convenience.
+
+    ```{tip}
+    Working on documentation or on issues labeled with either `33 needs: docs` or `41 lvl: easy` are the two best ways for first-timers to contribute.
+    This is because first-timers have a fresh perspective that might be overlooked by old-timers.
+    ```
+
+1.  Clarify the scope of work that needs to be done.
+    Check for previous work, assignment to another developer, or whether the requirements have changed.
+1.  [Assign yourself to the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users).
+    This signals to other developers that you are working on the issue.
+
+From here, you can either make {ref}`contributing-quick-edits-label` or {ref}`contributing-large-edits-label`.
+
+
+(contributing-quick-edits-label)=
+
+### Quick edits
+
+Quick edits for minor issues, such as typographical errors, misspellings, and English grammar and syntax, can be made through the GitHub user interface.
+
+1.  Navigate to the repository as noted in {ref}`contributing-manage-on-github-label`.
+1.  Navigate with the `docs` directory to find the source file to edit.
+1.  Click the {guilabel}`pencil icon` to edit the file in the browser.
+
+    ```{image} /_static/edit-pencil-icon.png
+    :alt: GitHub Edit this file
+    ```
+1.  Make edits, add a commit message, select {guilabel}`Create a new branch for this commit and start a pull request`, then click {guilabel}`Propose changes`.
+1.  Make your pull request against the branch `6-dev`.
+1.  Members who subscribe to the repository will receive a notification and review your request.
+1.  Request a review from other team members.
+
+
+(contributing-large-edits-label)=
+
+### Large edits
+
+For large edits, first follow the instructions in {doc}`setup-build`.
+
+Once you have your environment set up, then you can follow the standard practice for making a pull request.
+This practice differs depending on whether you are making contributions to only the core `documentation` files, or `plone.api`, `plone.restapi` and `volto` files as well.
+
+
+(contributing-documentation-only-label)=
+
+### Working with only the `plone/documentation` repository
+
+This section describes how to make contributions to files in the `plone/documentation` repository only, and excludes files in `submodules/plone.api/docs`, `submodules/plone.restapi/docs` and `submodules/volto/docs`.
+
+1.  From the project root directory, sync your local `6-dev` branch with its remote.
+    You might need to resolve conflicts.
+
+    ```shell
+    git checkout 6-dev
+    git pull
+    ```
+
+1.  Create a new branch from `6-dev`.
+
+    ```shell
+    git checkout -b <new_branch>
+    ```
+
+1.  Edit files, save, preview, and test.
+    You must run and pass the builds `html` and `linkcheck` without causing new errors.
+
+    ```shell
+    # Optionally clean the builds to avoid cache issues
+    make clean
+    make html
+    make linkcheck
+    ```
+
+    ```{note}
+    Currently there are some errors on the `html` build, mostly due to empty `meta` HTML tags.
+    You are welcome to fix as many errors as you like.
+    You are only responsible to fix errors that you create.
+    ```
+
+    ```{note}
+    Eventually the `vale` build will be required, but not at this time.
+    We welcome improvements to the dictionary.
+    ```
+
+    ```{seealso}
+    {ref}`setup-build-available-documentation-builds-label`.
+    ```
+
+1.  After the builds pass, commit changes to your branch, and push it to the remote repository on GitHub.
+    The remote repository may be either a branch in your fork of the project or a branch in the `plone/documentation` upstream repository.
+
+    ```shell
+    git commit -m "My descriptive commit message"
+    git push
+    ```
+
+1.  Visit the GitHub `documentation` repository, and [create a pull request](https://github.com/plone/documentation/compare) against the branch `6-dev`.
+1.  Members who subscribe to the repository will receive a notification and review your request.
+1.  Request a review from other team members.
+
+
+(contributing-editing-external-package-documentation-label)=
+
+### Editing external package documentation
+
+If you want to edit documentation of imported external packages, the process is slightly different.
+We use `git submodules` to manage multiple repositories.
+We imported the external repositories the `plone/documentation` repository as described in {doc}`setup-build`.
+
+```{important}
+We currently use the branches `plone/documentation@6-dev`, `plone/plone.api@master`, `plone/plone.restapi@master`, and `plone/volto@master` as the main branches for developing Plone 6 Documentation.
+These branches may change as we get closer to a production release.
+```
+
+1.  From the project root directory, sync your local `6-dev` branch with its remote.
+    You might need to resolve conflicts.
+
+    ```shell
+    git checkout 6-dev
+    git pull
+    ```
+
+1.  Change your working directory to the imported package's directory under `submodules/`.
+
+    ```shell
+    # Choose one.
+    cd submodules/plone.api
+    cd submodules/plone.restapi
+    cd submodules/volto
+    ```
+
+1.  Update the submodule, and sync your local development branch with its remote.
+    You might need to resolve conflicts.
+
+    ```shell
+    git submodule update
+
+    # for plone.api
+    git checkout master
+
+    # for plone.restapi
+    git checkout master
+
+    # for volto
+    git checkout master
+
+    git pull
+    ```
+
+1.  Create a new branch from the development branch.
+
+    ```shell
+    git checkout -b <new_branch>
+    ```
+
+1.  Make edits to files in `docs/<external_package>` using your favorite editor, and save, preview, and test.
+    You must run and pass the builds `html` and `linkcheck` without causing new errors.
+
+    ```shell
+    # Optionally clean the builds to avoid cache issues.
+    # Note that for the external packages' documentation only,
+    # we use "docs-" as a prefix for make targets to avoid a conflicts.
+    make docs-clean
+    make docs-html
+    make docs-linkcheck
+    ```
+
+1.  Back in `submodules/<external_package>`, commit and push your changes to the remote.
+
+    ```shell
+    git add <files>
+    git commit -m "My commit message"
+    git push
+    ```
+
+1.  Now return to the project root directory, and update the submodule to point to the commit you just made, and push your changes to the remote repository.
+
+    ```shell
+    cd ../..
+
+    # for plone.api
+    git add submodules/plone.api
+    git commit -m "Update submodules/plone.api tip"
+
+    # for plone.restapi
+    git add submodules/plone.restapi
+    git commit -m "Update submodules/plone.restapi tip"
+
+    # for Volto
+    git add submodules/volto
+    git commit -m "Update submodules/volto tip"
+
+    git push
+    ```
+
+1.  Visit the GitHub `plone/<external_package>` repository, and create a pull request against the development branch.
+1.  Members who subscribe to the `plone/<external_package>` repository will receive a notification and review your request.
+1.  Request a review from other team members.
+
+
+(contributing-documentation-code-of-conduct-label)=
+
+## Code of Conduct
+
+See {ref}`contributing-code-of-conduct-label`.
+
+
+```{toctree}
+---
+caption: Contributing to Documentation
+maxdepth: 2
+hidden: true
+---
+
+setup-build
+authors
+myst-reference
+sphinx-extensions
+admins
+```
diff --git a/docs/contributing/myst-reference.md b/docs/contributing/documentation/myst-reference.md
similarity index 99%
rename from docs/contributing/myst-reference.md
rename to docs/contributing/documentation/myst-reference.md
index 7354d4af3..73f83ebc6 100644
--- a/docs/contributing/myst-reference.md
+++ b/docs/contributing/documentation/myst-reference.md
@@ -48,10 +48,10 @@ Official MyST documentation
 #### Link to a chapter or page
 
 ```md
-Here is how to set up and build the documentation locally {doc}`/contributing/setup-build`.
+Here is how to set up and build the documentation locally {doc}`/contributing/documentation/setup-build`.
 ```
 
-Here is how to set up and build the documentation locally {doc}`/contributing/setup-build`.
+Here is how to set up and build the documentation locally {doc}`/contributing/documentation/setup-build`.
 
 
 (myst-reference-link-heading-label)=
diff --git a/docs/contributing/setup-build.md b/docs/contributing/documentation/setup-build.md
similarity index 100%
rename from docs/contributing/setup-build.md
rename to docs/contributing/documentation/setup-build.md
diff --git a/docs/contributing/sphinx-extensions.md b/docs/contributing/documentation/sphinx-extensions.md
similarity index 100%
rename from docs/contributing/sphinx-extensions.md
rename to docs/contributing/documentation/sphinx-extensions.md
diff --git a/docs/contributing/first-time.md b/docs/contributing/first-time.md
new file mode 100644
index 000000000..76922e068
--- /dev/null
+++ b/docs/contributing/first-time.md
@@ -0,0 +1,174 @@
+---
+myst:
+  html_meta:
+    "description": "First-time contributors to Plone"
+    "property=og:description": "First-time contributors to Plone"
+    "property=og:title": "First-time contributors to Plone"
+    "keywords": "Plone, first-time, GitHub, contributing, contributors"
+---
+
+(first-time-contributors-label)=
+
+# First-time contributors
+
+This chapter provides guidance to first-time contributors to Plone and all its packages and repositories under the Plone GitHub organization.
+
+It is assumed that the first-time contributor has already {doc}`installed Plone <../install/index>` on their development machine, has a GitHub account, and has basic knowledge of using git and GitHub.
+
+
+(first-time-requirements-label)=
+
+## Requirements
+
+All first-time contributors to Plone must follow the contributing requirements described in {doc}`index`.
+
+For [Plone Google Summer of Code (GSoC)](https://plone.org/community/gsoc) applicants, you must also follow both our and its program guidelines.
+
+
+(contributing-make-contributions-through-github-label)=
+
+## Make contributions through GitHub
+
+Contributions to Plone are managed through git repositories on GitHub.
+This section first discusses what not to do, then how to work effectively with a project on GitHub.
+
+
+### Things not to do
+
+The following is a list of the most frequent mistakes made by first-time contributors.
+Learn from their mistakes, and don't commit them yourself.
+
+1.  **Never ask to be assigned to an issue.**
+    You do not need to ask to be assigned to, or to work on, an open issue.
+    As in any open source software project, you can start work on open issues at your convenience.
+    Privileged team members may ignore or delete such comments.
+
+1.  **Never edit an issue description that you did not create.**
+    The issue description is the first comment in the issue.
+    Editing the description is destructive behavior.
+    If the description is not clear, then ask the author to clarify it.
+    
+    ```{todo}
+    Verify whether Contributors members can still do this.
+    ```
+
+1.  **Never close another contributor's pull request.**
+    This is extremly rude and disrespectful behavior.
+    Only members of privileged GitHub teams should close pull requests.
+    
+    ```{todo}
+    Verify whether Contributors members can still do this.
+    ```
+
+1.  **Avoid duplicate effort.**
+    Don't work on issues that have already been claimed or worked on, unless such effort has been abandoned by the author.
+    GitHub's interface provides links to related issues and pull requests, and who is assigned to an issue.
+    Pull requests will be reviewed in the order received.
+    Duplicate pull requests may be ignored and closed without comment by the privileged GitHub teams.
+
+
+### Plone Contributors Team
+
+The Plone GitHub organization uses GitHub Teams to grant groups of GitHub users appropriate access to its repositories.
+New users, including GSoC applicants, are assigned to the [Contributors](https://github.com/orgs/plone/teams/contributors) Team within a few days after they have signed and returned the {ref}`Plone Contributor Agreement <contributing-sign-and-return-the-plone-contributor-agreement-label>`.
+New contributors should wait for confirmation that they have been added to this team before creating a pull request to a Plone project.
+
+
+(first-time-mr-roboto-on-github-label)=
+
+### `mr-roboto` on GitHub
+
+[`mr-roboto`](https://github.com/plone/mr.roboto) enforces the requirement of a signed Plone Contributor Agreement from a new contributor, and being assigned to a Plone team on GitHub.
+
+New contributors to Plone who submit a pull request and do not wait for confirmation that they have been added to the Contributors team will be subjected to persistent nagging from `mr-roboto`.
+`mr-roboto` will not respond to you if you `@` it.
+Core developers may ignore your contribution because you did not follow these instructions.
+Please don't be "that person".
+
+
+### Work with GitHub issues
+
+1.  **Find issues that you want to work on.**
+    Working on documentation or on issues labeled with either `33 needs: docs` or `41 lvl: easy` are the two best ways for first-time contributors to contribute.
+    This is because first-timers have a fresh perspective that might be overlooked by old-timers.
+1.  **Discuss whether you should perform any work.**
+    Any method below is acceptable, but are listed in order of most likely to get a response.
+    -   Search for open issues in the issue trackers of Plone projects on GitHub, and comment on them.
+    -   If an issue does not already exist for what you want to work on, then create a new issue in its issue tracker.
+    -   Discuss during sprints, conferences, trainings, and other Plone events.
+    -   Ask on the [Plone Community Forum](https://community.plone.org/).
+    -   Ask in the [Plone chat on Discord](https://discord.com/invite/zFY3EBbjaj).
+1.  **Clarify the scope of work that needs to be done.**
+    Check for previous work in pull requests, assignment to another developer, or whether the requirements have changed.
+
+
+### Set up your environment
+
+1.  Start by [forking the project's repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) to your account through the GitHub interface.
+1.  [Clone your forked repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository).
+1.  [Configure git to sync your fork with the upstream repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository).
+
+
+### Write code
+
+Once you have your environment set up, then you can follow standard best practices for working with git.
+
+Always start by checking out the default branch, usually `main` or `master`, then update the default branch.
+
+```shell
+git checkout main
+git pull
+```
+
+Then create a new branch from the default branch, and check it out to work on it.
+We recommend using a branch name that includes the issue number and is descriptive of what it resolves.
+
+```shell
+git checkout -b branch_name
+```
+
+Now you can edit your code without affecting the default branch.
+
+```{note}
+The Plone organization is aware of the racially insensitive terms that exist in our projects.
+We are working to correct this mistake.
+We ask for your patience as we work through complex automated workflows that need to be updated.
+```
+
+
+### Test and code quality
+
+Follow the project's testing and code quality policies.
+Most projects have a test suite and code quality checkers and formatters.
+We strongly recommend that you run the project's test suite and code quality checks locally before proceeding.
+This will save you and reviewers a lot of time and frustration.
+
+A bug fix or new feature should have a test that ensures that it works as intended.
+
+
+### Create a pull request from your fork
+
+Once you have completed, tested, and linted your code, and created a {ref}`contributing-change-log-label`, then you can follow the standard practice for making a pull request.
+
+1.  Commit and push your changes to your fork.
+
+    ```shell
+    git add <files>
+    git commit -m "My commit message"
+    git push
+    ```
+
+1.  Visit your fork of the Plone repository on GitHub, and [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) against the development branch.
+    -   Make your title and description descriptive.
+        Don't be lazy with "Fixes bug" or other useless drivel.
+    -   To automatically close the original issue when your pull request is merged, include "Closes #issue_number" in your description.
+        This also creates a hyperlink to the original issue for easy reference.
+1.  [Request a review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) from other team members.
+1.  Members who subscribe to the repository will receive a notification and review your request.
+
+```{todo}
+Provide instructions when the contributor needs to update their pull request with changes from the default branch.
+Members of Contributors do not have the button "Update branch" to easily do this, and must use git foo to manage the situation.
+```
+
+Welcome to the Plone community, and thank you for contributing!
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 0bb915495..84c8a0aaa 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -1,310 +1,153 @@
 ---
 myst:
   html_meta:
-    "description": "Contributing to Plone 6 Documentation"
-    "property=og:description": "Contributing to Plone 6 Documentation"
-    "property=og:title": "Contributing to Plone 6 Documentation"
-    "keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct"
+    "description": "Contributing to Plone Core Code"
+    "property=og:description": "Contributing to Plone Core Code"
+    "property=og:title": "Contributing to Plone Core Code"
+    "keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct, core, code"
 ---
 
-(contributing-index-label)=
+(contributing-to-plone-core-code-index-label)=
 
-# Contributing to documentation
+# Contributing to Plone core code
 
-This document describes how to contribute to Plone Documentation.
+This part of the documentation describes how to contribute to Plone core code, including all its packages and repositories under the Plone GitHub organization.
 
-Contributions to the Plone Documentation are welcome.
+To contribute to any package in Plone, you must follow the policies of the [Plone Foundation](https://plone.org/foundation), [Plone GitHub organization](https://github.com/plone/) and the specific package.
 
+This chapter covers policies that apply to all Plone packages.
+Other chapters cover any variations and additional policies for each package.
 
-(contributing-permission-to-publish-label)=
 
-## Granting permission to publish
+(contributing-sign-and-return-the-plone-contributor-agreement-label)=
 
-Before you contribute, you must give permission to publish your contribution according to the license we use.
-You may give that permission in two ways.
+## Sign and return the Plone Contributor Agreement
 
-- Sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement).
-  This method also covers contributions to Plone code.
-  It is a one-time only process.
-- In every pull request or commit message, include the following statement.
+You must give permission to the Plone Foundation to publish your contribution, according to the license we use.
+Plone uses the [GNU General Public License, version 2](https://github.com/plone/Products.CMFPlone/blob/master/LICENSE).
+You grant permission by signing and returning the Plone Contributor Agreement.
 
-  > I, [full name], agree to have this contribution published under Creative Commons 4.0 International License (CC BY 4.0), with attribution to the Plone Foundation.
+```{button-link} https://plone.org/foundation/contributors-agreement
+:color: primary
 
-The Plone Documentation is licensed under the [Creative Commons Attribution 4.0 International License (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
-A copy of the license is included in the root of this repository.
-
-
-(contributing-roles-label)=
-
-## Contributor roles
-
-Contributors to the Plone Documentation may perform one or many roles.
-
-- **Plone users and developers** use this documentation because it is accurate and actively maintained.
-  People in these roles typically contribute minor corrections.
-  They should read {doc}`setup-build` and {doc}`myst-reference`.
-- **Authors** create Plone Documentation.
-  They should read {doc}`setup-build` and {doc}`myst-reference`.
-  They should also read {doc}`authors` for guidance and tips for writing good technical documentation.
-
-
-(contributing-quality-requirements-label)=
-
-## Documentation quality requirements
-
-We use GitHub Actions with every pull request to enforce Plone Documentation quality.
-We recommend that you build the documentation locally to catch errors and warnings early on.
-See {doc}`setup-build` for instructions for how to set up and build the documentation and to run quality checks.
-
-
-(contributing-manage-on-github-label)=
-
-## Making contributions on GitHub
-
-Contributions are managed through git repositories on GitHub.
-
--   [`documentation`](https://github.com/plone/documentation)
--   [`plone.api`](https://github.com/plone/plone.api)
--   [`plone.restapi`](https://github.com/plone/plone.restapi)
--   [`volto`](https://github.com/plone/volto)
-
-In the Plone organization, it is strongly recommended that you read {ref}`contributing-permission-to-publish-label` and take appropriate action.
-
-After your Plone Contributor Agreement has been approved, and you have been added to the Plone GitHub organization as a member of the [Developers](https://github.com/orgs/plone/teams/developers) team, we recommend that you follow our guidelines.
-
-1.  Discuss whether you should perform any work.
-    Any method below is acceptable, but are listed in order of most likely to get a response.
-
-    -   Search for open issues in the issue trackers of documented projects, and comment on them.
-        If an issue does not already exist for what you want to work on, then create a new issue in its issue tracker.
-
-        As a convenience, at the top right of every page, there is a GitHub navigation menu.
-        Tap, click, or hover over the GitHub Octocat icon for options.
-
-        ```{image} /_static/github-navigation.png
-        :alt: GitHub navigation menu 
-        ```
-
-        You can use this menu to quickly navigate to the `documentation` source repository or open an issue.
-        Note that this navigation convenience is provided only for the `documentation` repository.
-
-        -   [`documentation`](https://github.com/plone/documentation/issues)
-        -   [`plone.api`](https://github.com/plone/plone.api/issues)
-        -   [`plone.restapi`](https://github.com/plone/plone.restapi/issues)
-        -   [`volto`](https://github.com/plone/volto/issues)
-
-    -   Discuss during sprints, conferences, trainings, and other Plone events.
-    -   Ask on the [Plone Community Forum, Documentation topic](https://community.plone.org/c/documentation/13).
-    -   Ask in the [Plone chat on Discord](https://discord.com/invite/zFY3EBbjaj).
-
-1.  For first-time contributors especially, **you do not need to ask to be assigned to, or to work on, an open issue**.
-    As in any open source project, you can start work on open issues at your convenience.
-
-    ```{tip}
-    Working on documentation or on issues labeled with either `33 needs: docs` or `41 lvl: easy` are the two best ways for first-timers to contribute.
-    This is because first-timers have a fresh perspective that might be overlooked by old-timers.
-    ```
-
-1.  Clarify the scope of work that needs to be done.
-    Check for previous work, assignment to another developer, or whether the requirements have changed.
-1.  [Assign yourself to the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users).
-    This signals to other developers that you are working on the issue.
-
-From here, you can either make {ref}`contributing-quick-edits-label` or {ref}`contributing-large-edits-label`.
-
-
-(contributing-quick-edits-label)=
-
-### Quick edits
-
-Quick edits for minor issues, such as typographical errors, misspellings, and English grammar and syntax, can be made through the GitHub user interface.
-
-1.  Navigate to the repository as noted in {ref}`contributing-manage-on-github-label`.
-1.  Navigate with the `docs` directory to find the source file to edit.
-1.  Click the {guilabel}`pencil icon` to edit the file in the browser.
-
-    ```{image} /_static/edit-pencil-icon.png
-    :alt: GitHub Edit this file
-    ```
-1.  Make edits, add a commit message, select {guilabel}`Create a new branch for this commit and start a pull request`, then click {guilabel}`Propose changes`.
-1.  Make your pull request against the branch `6-dev`.
-1.  Members who subscribe to the repository will receive a notification and review your request.
-1.  Request a review from other team members.
+Sign the Plone Contributor Agreement
+```
 
+After a member of the Plone Foundation reviews and accepts your signed agreement, your GitHub account will be added to a team in the Plone GitHub organization with appropriate access.
+This process may take a few business days.
 
-(contributing-large-edits-label)=
+```{seealso}
+[Plone License FAQ](https://plone.org/foundation/copyright-licensing-logo/license-faq)
+```
 
-### Large edits
 
-For large edits, first follow the instructions in {doc}`setup-build`.
+(contributing-code-of-conduct-label)=
 
-Once you have your environment set up, then you can follow the standard practice for making a pull request.
-This practice differs depending on whether you are making contributions to only the core `documentation` files, or `plone.api`, `plone.restapi` and `volto` files as well.
+## Code of Conduct
 
+The Plone Foundation has published a [Code of Conduct](https://plone.org/foundation/materials/foundation-resolutions/code-of-conduct).
+All contributors to the Plone Documentation follow the Code of Conduct.
 
-(contributing-documentation-only-label)=
 
-### Working with only the `plone/documentation` repository
+(contributing-first-time-contributors-label)=
 
-This section describes how to make contributions to files in the `plone/documentation` repository only, and excludes files in `submodules/plone.api/docs`, `submodules/plone.restapi/docs` and `submodules/volto/docs`.
+## First-time contributors
 
-1.  From the project root directory, sync your local `6-dev` branch with its remote.
-    You might need to resolve conflicts.
+First-time contributors should read and follow our guide {doc}`first-time`.
 
-    ```shell
-    git checkout 6-dev
-    git pull
-    ```
 
-1.  Create a new branch from `6-dev`.
+(contributing-continuous-integration-label)=
 
-    ```shell
-    git checkout -b <new_branch>
-    ```
+## Continuous integration
 
-1.  Edit files, save, preview, and test.
-    You must run and pass the builds `html` and `linkcheck` without causing new errors.
+Plone project repositories use continuous integration (CI) to run tests, ensure code quality, or provide previews for every contribution.
+Plone uses GitHub Actions, Jenkins, Cypress, Netlify, and other services for CI.
+All of a project's CI jobs must pass before a contribution may be accepted.
 
-    ```shell
-    # Optionally clean the builds to avoid cache issues
-    make clean
-    make html
-    make linkcheck
-    ```
 
-    ```{note}
-    Currently there are some errors on the `html` build, mostly due to empty `meta` HTML tags.
-    You are welcome to fix as many errors as you like.
-    You are only responsible to fix errors that you create.
-    ```
+(contributing-change-log-label)=
 
-    ```{note}
-    Eventually the `vale` build will be required, but not at this time.
-    We welcome improvements to the dictionary.
-    ```
+## Change log entry
 
-    ```{seealso}
-    {ref}`setup-build-available-documentation-builds-label`.
-    ```
+Plone projects require that you include a change log entry or news item with your contribution.
+This is enforced by continuous integration through GitHub Actions.
 
-1.  After the builds pass, commit changes to your branch, and push it to the remote repository on GitHub.
-    The remote repository may be either a branch in your fork of the project or a branch in the `plone/documentation` upstream repository.
+Plone uses [`towncrier`](https://github.com/collective/zestreleaser.towncrier) to manage change log entries and to automatically generate history or change log files from the entries.
+The log file is usually named `CHANGES.rst`, `CHANGES.md`, or `CHANGELOG.md`, and is located at the root of the project.
+When a project is released with a new version, the release manager runs `towncrier` as part of the release process.
+Because the log file is automatically generated, you should not edit it directly, except to make corrections, such as broken links.
 
-    ```shell
-    git commit -m "My descriptive commit message"
-    git push
-    ```
+To create a change log entry or news item, create a file that is placed in the root of the repository directory at `/news`.
+Its 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.
 
-1.  Visit the GitHub `documentation` repository, and [create a pull request](https://github.com/plone/documentation/compare) against the branch `6-dev`.
-1.  Members who subscribe to the repository will receive a notification and review your request.
-1.  Request a review from other team members.
+-   `breaking` for breaking changes
+-   `bugfix` for bug fixes
+-   `documentation` for documentation
+-   `feature` for new features
+-   `internal` for internal changes
 
+A project configures the types it allows in a file `towncrier.toml` located at the root of its repository.
 
-(contributing-editing-external-package-documentation-label)=
+The content of this file must include the following.
 
-### Editing external package documentation
+-   A brief message that summarizes the changes in your contribution.
+-   An attribution to yourself, either in the format of `@github_username` or `[github_username]`.
 
-If you want to edit documentation of imported external packages, the process is slightly different.
-We use `git submodules` to manage multiple repositories.
-We imported the external repositories the `plone/documentation` repository as described in {doc}`setup-build`.
+The following text is an example change log entry, placed inside {file}`/news/4569.documentation`.
 
-```{important}
-We currently use the branches `plone/documentation@6-dev`, `plone/plone.api@master`, `plone/plone.restapi@master`, and `plone/volto@master` as the main branches for developing Plone 6 Documentation.
-These branches may change as we get closer to a production release.
+```text
+Fix broken links for ReactJS.org. @stevepiercy
 ```
 
-1.  From the project root directory, sync your local `6-dev` branch with its remote.
-    You might need to resolve conflicts.
-
-    ```shell
-    git checkout 6-dev
-    git pull
-    ```
-
-1.  Change your working directory to the imported package's directory under `submodules/`.
-
-    ```shell
-    # Choose one.
-    cd submodules/plone.api
-    cd submodules/plone.restapi
-    cd submodules/volto
-    ```
 
-1.  Update the submodule, and sync your local development branch with its remote.
-    You might need to resolve conflicts.
+(contributing-plone-packages-label)=
 
-    ```shell
-    git submodule update
+## Plone core packages
 
-    # for plone.api
-    git checkout master
+Each Plone core package may have specific policies and guidance.
+This may include writing tests, developing add-ons, internationalization and localization, logging, and debugging.
 
-    # for plone.restapi
-    git checkout master
+The following is an abridged list of actively developed Plone core packages with links to how to contribute to them.
 
-    # for volto
-    git checkout master
+`Products.CMFPlone`
+:   The primary Plone package.
+    See its [repository](https://github.com/plone/Products.CMFPlone).
 
-    git pull
-    ```
+Documentation
+:   "If it's not documented, it's broken."
+    See {doc}`documentation/index`.
 
-1.  Create a new branch from the development branch.
+Plone API
+:    API methods for Plone functionality.
+    See {doc}`../plone.api/contribute/index`.
 
-    ```shell
-    git checkout -b <new_branch>
-    ```
+Plone REST API
+:   A RESTful API for Plone.
+    See {doc}`plone.restapi/docs/source/contributing/index`.
 
-1.  Make edits to files in `docs/<external_package>` using your favorite editor, and save, preview, and test.
-    You must run and pass the builds `html` and `linkcheck` without causing new errors.
+Volto
+:   Plone 6 default frontend.
+    See {doc}`../volto/developer-guidelines/contributing`.
 
-    ```shell
-    # Optionally clean the builds to avoid cache issues.
-    # Note that for the external packages' documentation only,
-    # we use "docs-" as a prefix for make targets to avoid a conflicts.
-    make docs-clean
-    make docs-html
-    make docs-linkcheck
-    ```
+`plone.app.contentlisting`
+:   Facilitates working with Plone content objects.
+    See https://github.com/plone/plone.app.contenttypes
 
-1.  Back in `submodules/<external_package>`, commit and push your changes to the remote.
+`plone.app.contenttypes`
+:   Provides default content types for Plone.
+    See https://github.com/plone/plone.app.contenttypes
 
-    ```shell
-    git add <files>
-    git commit -m "My commit message"
-    git push
-    ```
+`plone.app.event`
+:   A calendar framework for Plone.
+    See https://github.com/plone/plone.app.event
 
-1.  Now return to the project root directory, and update the submodule to point to the commit you just made, and push your changes to the remote repository.
+`plone.app.multilingual`
+:   The default solution to create multilingual content in a Plone site.
+    See https://github.com/plone/plone.app.multilingual
 
-    ```shell
-    cd ../..
-
-    # for plone.api
-    git add submodules/plone.api
-    git commit -m "Update submodules/plone.api tip"
-
-    # for plone.restapi
-    git add submodules/plone.restapi
-    git commit -m "Update submodules/plone.restapi tip"
-
-    # for Volto
-    git add submodules/volto
-    git commit -m "Update submodules/volto tip"
-
-    git push
-    ```
-
-1.  Visit the GitHub `plone/<external_package>` repository, and create a pull request against the development branch.
-1.  Members who subscribe to the `plone/<external_package>` repository will receive a notification and review your request.
-1.  Request a review from other team members.
-
-
-(contributing-code-of-conduct-label)=
-
-## Code of Conduct
-
-The Plone Foundation has published a [Code of Conduct](https://plone.org/foundation/materials/foundation-resolutions/code-of-conduct).
-All contributors to the Plone Documentation follow the Code of Conduct.
+```{todo}
+Add other important Plone packages to both the above list and the `toctree`.
+```
 
 
 ```{toctree}
@@ -314,9 +157,9 @@ maxdepth: 2
 hidden: true
 ---
 
-setup-build
-authors
-myst-reference
-sphinx-extensions
-admins
+first-time
+documentation/index
+../plone.api/contribute/index
+../plone.restapi/docs/source/contributing/index
+../volto/developer-guidelines/contributing
 ```

From 313fc8ded3eab199e47083c0e6ccbffe8cc80d9e Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Sat, 1 Apr 2023 06:28:58 -0700
Subject: [PATCH 02/12] Ignore all teams

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index d8ab910b5..63666a11d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -80,7 +80,7 @@
     r"http://yoursite",
     r"https://www.linode.com",
     r"https://vhs-ehrenamtsportal.de", # SSLError(SSLCertVerificationError
-    r"https://github.com/orgs/plone/teams/developers",  # requires auth
+    r"https://github.com/orgs/plone/teams/",  # requires auth
     r"https://github.com/plone/documentation/issues/new/choose",  # requires auth
     # Ignore specific anchors
     r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",

From ff6115527c03f77b61c8a51f11bb738d8da4edb2 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Tue, 4 Apr 2023 12:56:43 -0700
Subject: [PATCH 03/12] Change "important" to "selected".

---
 docs/contributing/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 84c8a0aaa..6dbace229 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -146,7 +146,7 @@ Volto
     See https://github.com/plone/plone.app.multilingual
 
 ```{todo}
-Add other important Plone packages to both the above list and the `toctree`.
+Add other selected Plone packages to both the above list and the `toctree`.
 ```
 
 

From e0a3247c2f9a4941896192b4cc85cfce251078dc Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Tue, 4 Apr 2023 12:57:28 -0700
Subject: [PATCH 04/12] Make an arbitrary executive decision of
 @github_username for attribution in news item

---
 docs/contributing/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 6dbace229..a91697676 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -91,7 +91,7 @@ A project configures the types it allows in a file `towncrier.toml` located at t
 The content of this file must include the following.
 
 -   A brief message that summarizes the changes in your contribution.
--   An attribution to yourself, either in the format of `@github_username` or `[github_username]`.
+-   An attribution to yourself, in the format of `@github_username`.
 
 The following text is an example change log entry, placed inside {file}`/news/4569.documentation`.
 

From caf5a0b3ad1c18733247fe5570b4479e3476f6f6 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Tue, 4 Apr 2023 13:20:13 -0700
Subject: [PATCH 05/12] Revise licensing language to include modified BSD.

---
 docs/contributing/index.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index a91697676..64182c372 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -24,7 +24,8 @@ Other chapters cover any variations and additional policies for each package.
 ## Sign and return the Plone Contributor Agreement
 
 You must give permission to the Plone Foundation to publish your contribution, according to the license we use.
-Plone uses the [GNU General Public License, version 2](https://github.com/plone/Products.CMFPlone/blob/master/LICENSE).
+Plone uses the [GNU General Public License, version 2](https://github.com/plone/Products.CMFPlone/blob/master/LICENSE) for most of its packages and for any new packages.
+A few other packages use the [modified BSD license](https://opensource.org/license/bsd-3-clause/).
 You grant permission by signing and returning the Plone Contributor Agreement.
 
 ```{button-link} https://plone.org/foundation/contributors-agreement
@@ -37,7 +38,8 @@ After a member of the Plone Foundation reviews and accepts your signed agreement
 This process may take a few business days.
 
 ```{seealso}
-[Plone License FAQ](https://plone.org/foundation/copyright-licensing-logo/license-faq)
+-   [Plone License FAQ](https://plone.org/foundation/copyright-licensing-logo/license-faq)
+-   [Plone Framework Components Relicensing Policy, Framework Components Available Under a BSD License](https://plone.org/foundation/about/materials/foundation-resolutions/plone-framework-components-relicensing-policy#3b050ad2-361a-46de-b5c6-9b90f8947eb7)
 ```
 
 

From 2cc61b4fe82da32cf3d87e4b1c14d4b0562441f0 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 7 Apr 2023 03:03:07 -0700
Subject: [PATCH 06/12] Remove "core"

---
 docs/contributing/index.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 64182c372..2225ae5cd 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -1,17 +1,17 @@
 ---
 myst:
   html_meta:
-    "description": "Contributing to Plone Core Code"
-    "property=og:description": "Contributing to Plone Core Code"
-    "property=og:title": "Contributing to Plone Core Code"
-    "keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct, core, code"
+    "description": "Contributing to Plone Code"
+    "property=og:description": "Contributing to Plone Code"
+    "property=og:title": "Contributing to Plone Code"
+    "keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct, code"
 ---
 
 (contributing-to-plone-core-code-index-label)=
 
-# Contributing to Plone core code
+# Contributing to Plone code
 
-This part of the documentation describes how to contribute to Plone core code, including all its packages and repositories under the Plone GitHub organization.
+This part of the documentation describes how to contribute to Plone code, including all its packages and repositories under the Plone GitHub organization.
 
 To contribute to any package in Plone, you must follow the policies of the [Plone Foundation](https://plone.org/foundation), [Plone GitHub organization](https://github.com/plone/) and the specific package.
 
@@ -104,12 +104,12 @@ Fix broken links for ReactJS.org. @stevepiercy
 
 (contributing-plone-packages-label)=
 
-## Plone core packages
+## Plone packages
 
-Each Plone core package may have specific policies and guidance.
+Each Plone package may have specific policies and guidance.
 This may include writing tests, developing add-ons, internationalization and localization, logging, and debugging.
 
-The following is an abridged list of actively developed Plone core packages with links to how to contribute to them.
+The following is an abridged list of actively developed Plone packages with links to how to contribute to them.
 
 `Products.CMFPlone`
 :   The primary Plone package.

From 1e8a65a88494cb95183530b907dcfa9a3fe517f1 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 7 Apr 2023 03:05:04 -0700
Subject: [PATCH 07/12] Remove "code"

---
 docs/contributing/index.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 2225ae5cd..735cd328b 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -1,17 +1,17 @@
 ---
 myst:
   html_meta:
-    "description": "Contributing to Plone Code"
-    "property=og:description": "Contributing to Plone Code"
-    "property=og:title": "Contributing to Plone Code"
-    "keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct, code"
+    "description": "Contributing to Plone"
+    "property=og:description": "Contributing to Plone"
+    "property=og:title": "Contributing to Plone"
+    "keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct"
 ---
 
-(contributing-to-plone-core-code-index-label)=
+(contributing-to-plone-index-label)=
 
-# Contributing to Plone code
+# Contributing to Plone
 
-This part of the documentation describes how to contribute to Plone code, including all its packages and repositories under the Plone GitHub organization.
+This part of the documentation describes how to contribute to Plone, including all its packages and repositories under the Plone GitHub organization.
 
 To contribute to any package in Plone, you must follow the policies of the [Plone Foundation](https://plone.org/foundation), [Plone GitHub organization](https://github.com/plone/) and the specific package.
 

From 3290b67deb802678f1cf194f435b849164b86913 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 7 Apr 2023 04:02:01 -0700
Subject: [PATCH 08/12] Remove obscure packages, and clarify the purpose of the
 index as an entry point to actively developed packages

---
 docs/contributing/index.md | 28 ++++------------------------
 1 file changed, 4 insertions(+), 24 deletions(-)

diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 735cd328b..0093edd4d 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -102,11 +102,11 @@ Fix broken links for ReactJS.org. @stevepiercy
 ```
 
 
-(contributing-plone-packages-label)=
+(contributing-specific-contribution-policies-for-packages-label)=
 
-## Plone packages
+## Specific contribution policies of packages
 
-Each Plone package may have specific policies and guidance.
+Each Plone package may have specific contribution policies and guidance.
 This may include writing tests, developing add-ons, internationalization and localization, logging, and debugging.
 
 The following is an abridged list of actively developed Plone packages with links to how to contribute to them.
@@ -120,7 +120,7 @@ Documentation
     See {doc}`documentation/index`.
 
 Plone API
-:    API methods for Plone functionality.
+:   API methods for Plone functionality.
     See {doc}`../plone.api/contribute/index`.
 
 Plone REST API
@@ -131,26 +131,6 @@ Volto
 :   Plone 6 default frontend.
     See {doc}`../volto/developer-guidelines/contributing`.
 
-`plone.app.contentlisting`
-:   Facilitates working with Plone content objects.
-    See https://github.com/plone/plone.app.contenttypes
-
-`plone.app.contenttypes`
-:   Provides default content types for Plone.
-    See https://github.com/plone/plone.app.contenttypes
-
-`plone.app.event`
-:   A calendar framework for Plone.
-    See https://github.com/plone/plone.app.event
-
-`plone.app.multilingual`
-:   The default solution to create multilingual content in a Plone site.
-    See https://github.com/plone/plone.app.multilingual
-
-```{todo}
-Add other selected Plone packages to both the above list and the `toctree`.
-```
-
 
 ```{toctree}
 ---

From 25cd35e804664b907d9218274398acdf2980b5c0 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 7 Apr 2023 05:01:27 -0700
Subject: [PATCH 09/12] Add heading labels

---
 docs/contributing/first-time.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/contributing/first-time.md b/docs/contributing/first-time.md
index 76922e068..88f219989 100644
--- a/docs/contributing/first-time.md
+++ b/docs/contributing/first-time.md
@@ -33,6 +33,8 @@ Contributions to Plone are managed through git repositories on GitHub.
 This section first discusses what not to do, then how to work effectively with a project on GitHub.
 
 
+(things-not-to-do-label)=
+
 ### Things not to do
 
 The following is a list of the most frequent mistakes made by first-time contributors.
@@ -67,6 +69,8 @@ Learn from their mistakes, and don't commit them yourself.
     Duplicate pull requests may be ignored and closed without comment by the privileged GitHub teams.
 
 
+(plone-contributors-team-label)=
+
 ### Plone Contributors Team
 
 The Plone GitHub organization uses GitHub Teams to grant groups of GitHub users appropriate access to its repositories.
@@ -86,6 +90,8 @@ Core developers may ignore your contribution because you did not follow these in
 Please don't be "that person".
 
 
+(work-with-github-issues-label)=
+
 ### Work with GitHub issues
 
 1.  **Find issues that you want to work on.**
@@ -102,6 +108,8 @@ Please don't be "that person".
     Check for previous work in pull requests, assignment to another developer, or whether the requirements have changed.
 
 
+(set-up-your-environment-label)=
+
 ### Set up your environment
 
 1.  Start by [forking the project's repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) to your account through the GitHub interface.
@@ -109,6 +117,8 @@ Please don't be "that person".
 1.  [Configure git to sync your fork with the upstream repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository).
 
 
+(write-code-label)=
+
 ### Write code
 
 Once you have your environment set up, then you can follow standard best practices for working with git.
@@ -136,6 +146,8 @@ We ask for your patience as we work through complex automated workflows that nee
 ```
 
 
+(test-and-code-quality-label)=
+
 ### Test and code quality
 
 Follow the project's testing and code quality policies.
@@ -146,6 +158,8 @@ This will save you and reviewers a lot of time and frustration.
 A bug fix or new feature should have a test that ensures that it works as intended.
 
 
+(create-a-pull-request-from-your-fork-label)=
+
 ### Create a pull request from your fork
 
 Once you have completed, tested, and linted your code, and created a {ref}`contributing-change-log-label`, then you can follow the standard practice for making a pull request.

From 6db5127e9d76ee9c2af42dae4072e70b5911e490 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 7 Apr 2023 05:02:00 -0700
Subject: [PATCH 10/12] Clarify things not to do

---
 docs/contributing/first-time.md | 25 +++++++------------------
 1 file changed, 7 insertions(+), 18 deletions(-)

diff --git a/docs/contributing/first-time.md b/docs/contributing/first-time.md
index 88f219989..1c90fa4bf 100644
--- a/docs/contributing/first-time.md
+++ b/docs/contributing/first-time.md
@@ -40,29 +40,18 @@ This section first discusses what not to do, then how to work effectively with a
 The following is a list of the most frequent mistakes made by first-time contributors.
 Learn from their mistakes, and don't commit them yourself.
 
+(mistake-1-label)=
+
 1.  **Never ask to be assigned to an issue.**
+    Instead you may post a comment to claim it, if no one else has claimed it (see {ref}`Avoid duplicate effort <mistake-2-label>`).
+    For example, "I am working on this issue in pull request #123."
     You do not need to ask to be assigned to, or to work on, an open issue.
     As in any open source software project, you can start work on open issues at your convenience.
-    Privileged team members may ignore or delete such comments.
-
-1.  **Never edit an issue description that you did not create.**
-    The issue description is the first comment in the issue.
-    Editing the description is destructive behavior.
-    If the description is not clear, then ask the author to clarify it.
-    
-    ```{todo}
-    Verify whether Contributors members can still do this.
-    ```
+    Privileged team members may ignore or delete comments asking to be assigned to an issue.
 
-1.  **Never close another contributor's pull request.**
-    This is extremly rude and disrespectful behavior.
-    Only members of privileged GitHub teams should close pull requests.
-    
-    ```{todo}
-    Verify whether Contributors members can still do this.
-    ```
+    (mistake-2-label)=
 
-1.  **Avoid duplicate effort.**
+2.  **Avoid duplicate effort.**
     Don't work on issues that have already been claimed or worked on, unless such effort has been abandoned by the author.
     GitHub's interface provides links to related issues and pull requests, and who is assigned to an issue.
     Pull requests will be reviewed in the order received.

From 5771fc44404c426042c9aa667713cab475db824e Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 7 Apr 2023 05:05:31 -0700
Subject: [PATCH 11/12] Enhance Work with GitHub issues - Refer to Avoid
 duplicate effort - Improve wording

---
 docs/contributing/first-time.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/contributing/first-time.md b/docs/contributing/first-time.md
index 1c90fa4bf..c6365b46d 100644
--- a/docs/contributing/first-time.md
+++ b/docs/contributing/first-time.md
@@ -87,14 +87,19 @@ Please don't be "that person".
     Working on documentation or on issues labeled with either `33 needs: docs` or `41 lvl: easy` are the two best ways for first-time contributors to contribute.
     This is because first-timers have a fresh perspective that might be overlooked by old-timers.
 1.  **Discuss whether you should perform any work.**
-    Any method below is acceptable, but are listed in order of most likely to get a response.
+    First see {ref}`Avoid duplicate effort <mistake-2-label>`.
+    Next, any discussion method listed below is acceptable, and they are listed in the order of most likely to get a response.
     -   Search for open issues in the issue trackers of Plone projects on GitHub, and comment on them.
     -   If an issue does not already exist for what you want to work on, then create a new issue in its issue tracker.
+        Use a descriptive title and description, include steps to reproduce the issue, and screenshots or videos that demonstrate the issue.
     -   Discuss during sprints, conferences, trainings, and other Plone events.
-    -   Ask on the [Plone Community Forum](https://community.plone.org/).
-    -   Ask in the [Plone chat on Discord](https://discord.com/invite/zFY3EBbjaj).
+    -   Discuss on the [Plone Community Forum](https://community.plone.org/).
+    -   Discuss in the [Plone chat on Discord](https://discord.com/invite/zFY3EBbjaj).
 1.  **Clarify the scope of work that needs to be done.**
-    Check for previous work in pull requests, assignment to another developer, or whether the requirements have changed.
+    Sometimes the issue description is blank or lacks clarity, the requirements have changed since it was created, or work has been completed in a pull request but the issue was not closed.
+    Ask for clarification, whether it is still relevant, or whether it should be closed.
+
+After you have satisfied the above steps and have clear direction on how to proceed, then you can begin work on the issue.
 
 
 (set-up-your-environment-label)=

From e7a15204751163efe67d514dd6448478465a33d4 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 7 Apr 2023 13:04:19 -0700
Subject: [PATCH 12/12] s/package/project

---
 docs/contributing/first-time.md |  2 +-
 docs/contributing/index.md      | 22 +++++++++++-----------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/contributing/first-time.md b/docs/contributing/first-time.md
index c6365b46d..22b4ec093 100644
--- a/docs/contributing/first-time.md
+++ b/docs/contributing/first-time.md
@@ -11,7 +11,7 @@ myst:
 
 # First-time contributors
 
-This chapter provides guidance to first-time contributors to Plone and all its packages and repositories under the Plone GitHub organization.
+This chapter provides guidance to first-time contributors to Plone and all its projects and repositories under the Plone GitHub organization.
 
 It is assumed that the first-time contributor has already {doc}`installed Plone <../install/index>` on their development machine, has a GitHub account, and has basic knowledge of using git and GitHub.
 
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 0093edd4d..2f0780ee5 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -11,12 +11,12 @@ myst:
 
 # Contributing to Plone
 
-This part of the documentation describes how to contribute to Plone, including all its packages and repositories under the Plone GitHub organization.
+This part of the documentation describes how to contribute to Plone, including all its projects and repositories under the Plone GitHub organization.
 
-To contribute to any package in Plone, you must follow the policies of the [Plone Foundation](https://plone.org/foundation), [Plone GitHub organization](https://github.com/plone/) and the specific package.
+To contribute to any project in Plone, you must follow the policies of the [Plone Foundation](https://plone.org/foundation), [Plone GitHub organization](https://github.com/plone/) and the specific project.
 
-This chapter covers policies that apply to all Plone packages.
-Other chapters cover any variations and additional policies for each package.
+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)=
@@ -24,8 +24,8 @@ Other chapters cover any variations and additional policies for each package.
 ## Sign and return the Plone Contributor Agreement
 
 You must give permission to the Plone Foundation to publish your contribution, according to the license we use.
-Plone uses the [GNU General Public License, version 2](https://github.com/plone/Products.CMFPlone/blob/master/LICENSE) for most of its packages and for any new packages.
-A few other packages use the [modified BSD license](https://opensource.org/license/bsd-3-clause/).
+Plone uses the [GNU General Public License, version 2](https://github.com/plone/Products.CMFPlone/blob/master/LICENSE) for most of its projects and for any new projects.
+A few other projects use the [modified BSD license](https://opensource.org/license/bsd-3-clause/).
 You grant permission by signing and returning the Plone Contributor Agreement.
 
 ```{button-link} https://plone.org/foundation/contributors-agreement
@@ -102,17 +102,17 @@ Fix broken links for ReactJS.org. @stevepiercy
 ```
 
 
-(contributing-specific-contribution-policies-for-packages-label)=
+(contributing-specific-contribution-policies-for-projects-label)=
 
-## Specific contribution policies of packages
+## Specific contribution policies of projects
 
-Each Plone package may have specific contribution policies and guidance.
+Each Plone project may have specific contribution policies and guidance.
 This may include writing tests, developing add-ons, internationalization and localization, logging, and debugging.
 
-The following is an abridged list of actively developed Plone packages with links to how to contribute to them.
+The following is an abridged list of actively developed Plone projects with links to how to contribute to them.
 
 `Products.CMFPlone`
-:   The primary Plone package.
+:   The primary Plone project.
     See its [repository](https://github.com/plone/Products.CMFPlone).
 
 Documentation