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.

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.

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.

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.

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.

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.

    GitHub Edit this file
  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 spellcheck build will be required, but not at this time. We welcome improvements to the dictionary.

  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.