Contributing to Plone#

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 project in Plone, you must follow the policies of the Plone Foundation, Plone GitHub organization and the specific project.

This chapter covers policies that apply to all Plone projects. Other chapters cover any variations and additional policies for each project.

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 for most of its projects and for any new projects. A few other projects use the modified BSD license. You grant permission by signing and returning the Plone Contributor Agreement.

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.

See also

Code of Conduct#

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

First-time contributors#

First-time contributors should read and follow our guide First-time contributors.

Continuous integration#

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.

Change log entry#

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.

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

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.

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

The content of this file must include the following.

  • A brief message that summarizes the changes in your contribution.

  • An attribution to yourself, in the format of @github_username.

The following text is an example change log entry, placed inside /news/4569.documentation.

Fix broken links for ReactJS.org. @stevepiercy

Specific contribution policies of projects#

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 projects with links to how to contribute to them.

Products.CMFPlone

The primary Plone project. See its repository.

Documentation

"If it's not documented, it's broken." See Contributing to documentation.

Plone API

API methods for Plone functionality. See Contributing to plone.api.

Plone REST API

A RESTful API for Plone. See Contributing to plone.restapi.

Volto

Plone 6 default frontend. See Contributing to Volto.