Contributing to documentation

This document describes how to contribute to Plone Documentation.

Contributions to the Plone Documentation are welcome.

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. 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). A copy of the license is included in the root of this repository.

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 Building and checking the quality of documentation and MyST reference.

• Authors create Plone Documentation. They should read Building and checking the quality of documentation and MyST reference. They should also read Authors guide for guidance and tips for writing good technical documentation.

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 Building and checking the quality of documentation for instructions for how to set up and build the documentation and to run quality checks.

Making contributions on GitHub

Contributions are managed through git repositories on GitHub.

• documentation

• plone.api

• plone.restapi

• volto

First 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 documentation, plone.api, plone.restapi, or volto and comment on them.

• Create a new issue in documentation, plone.api, plone.restapi, or volto.

• Discuss during conferences, trainings, and other Plone events.

• Ask on the Plone Community Forum, Documentation topic.

• Ask in the Plone chat on Discord.

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.

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.

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 Making contributions on GitHub.

2. Navigate with the docs directory to find the source file to edit.

3. Click the pencil icon to edit the file in the browser.

   

4. Make edits, add a commit message, select Create a **new branch** for this commit and start a pull request, then click Propose changes.

5. Make your pull request against the branch 6-dev.

6. Members who subscribe to the repository will receive a notification and review your request.

Large edits

For large edits, first follow the instructions in Building and checking the quality of documentation.

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.

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.

   git checkout 6-dev
   git pull
   

2. Create a new branch from 6-dev.

   git checkout -b <new_branch>
   

3. Edit files, save, preview, and test. You must run and pass the builds html and linkcheck without causing new errors.

   # 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.

   See also

   Available documentation builds.

4. 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.

   git commit -m "My descriptive commit message"
   git push
   

5. Visit the GitHub documentation repository, and create a pull request against the branch 6-dev.

6. Members who subscribe to the repository will receive a notification and review your request.

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 Building and checking the quality of 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.

1. From the project root directory, sync your local 6-dev branch with its remote. You might need to resolve conflicts.

   git checkout 6-dev
   git pull
   

2. Change your working directory to the imported package's directory under submodules/.

   # Choose one.
   cd submodules/plone.api
   cd submodules/plone.restapi
   cd submodules/volto
   

3. Update the submodule, and sync your local development branch with its remote. You might need to resolve conflicts.

   git submodule update
   
   # for plone.api
   git checkout master
   
   # for plone.restapi
   git checkout master
   
   # for volto
   git checkout master
   
   git pull
   

4. Create a new branch from the development branch.

   git checkout -b <new_branch>
   

5. 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.

   # 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
   

6. Back in submodules/<external_package>, commit and push your changes to the remote.

   git add <files>
   git commit -m "My commit message"
   git push
   

7. 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.

   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
   

8. Visit the GitHub plone/<external_package> repository, and create a pull request against the development branch.

9. Members who subscribe to the plone/<external_package> repository will receive a notification and review your request.

Code of Conduct

The Plone Foundation has published a Code of Conduct. All contributors to the Plone Documentation follow the Code of Conduct.