Contributing to Plone

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.

If instead you want to create a web application project using Plone, see Install Plone.

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, MIT License, or Creative Commons Attribution-ShareAlike 4.0 International license. You grant permission by signing and returning the Plone Contributor Agreement.

A volunteer member of the Plone Foundation will review your signed agreement.

If accepted, your GitHub account will be added to a team in the Plone GitHub organization with appropriate access, and you will simultaneously receive an email from GitHub for you to accept the invitation to join the team.

Allow up to one week for processing. Contact the Plone Foundation by its email address for further information, including the status of your request.

Sign the Plone Contributor Agreement

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.

Report bugs and request features#

When you experience a bug with, or want to request a feature for Plone, but you don't know in which package you should create the GitHub issue, you can create an issue in the primary Plone repository, Products.CMFPlone. Someone will help identify in which of the dozens of repositories that make up Plone the actual change and pull request should be made.

Continuous integration#

Plone project repositories use continuous integration (CI) to run tests, ensure code quality, or provide previews for every contribution. Plone uses GitHub workflows, Jenkins, Cypress, Read the Docs, and other services for CI. All of a project's CI jobs must pass before a contribution may be accepted.

Change log entry#

Plone packages 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 package. When a package 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.

Create a news item file#

To create a change log entry or news item, create a file in the news directory, located in the root of the package.

For Volto, its repository is in a monorepo structure, consisting of several packages in the packages folder. Thus for Volto and its packages, change log entries should be created in packages/PACKAGE_NAME/news/, which is the root of the package. When making a change to its documentation, set up, continuous integration, or other repository-wide items, place a change log entry in packages/volto/news/ as a default.

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

A package configures the types it allows in a file towncrier.toml located at the root of its package directory.

Write a good change log entry#

Important

These change log entries become narrative documentation.

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.

You can write a good change log entry with the following guidance.

Use a narrative format, in the past tense, proper English spelling and grammar, and inline markup as needed.
Write your change log entry for its appropriate audience.
- Most entries should address users of the software.
- An entry for a change to a public API should address developers.
If you fix a bug, write what was broken and is now fixed. You should not write how you fixed it.
If you add or change a feature or public API, write a summary of previous behavior, what it does now, and how to use it.
Refer to narrative documentation as needed.

The following text is an example of a good change log entry, placed inside /news/4470.documentation.

Changed a few broken links in {file}`CHANGELOG.md` from URLs to inline literals to avoid errors when validating links. See https://6.docs.plone.org/volto/contributing/documentation.html#docs-linkcheckbroken for usage. @stevepiercy

The following would be a poor change log entry.

Fix #123456 by chaning config of additionalToolbarComponents [did_not_read_this_guide]

Project configuration files#

To standarize the developer experience across packages, a configuration tool is used.

See the tool documentation for more information.

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 Contribute to documentation.
Plone API: API methods for Plone functionality. See Contribute to plone.api.
Plone REST API: A RESTful API for Plone. See Contribute to plone.restapi.
Volto: Plone 6 default frontend. See Contributing to Volto.

Releases#

The Plone Release Team manages the release of new versions of Plone.

We use zest.releaser for releasing the Python packages used in Plone, including Plone core (Products.CMFPlone), Classic UI, REST API, plone.api, and Backend.

We use release-it for releasing the Node.js packages used in Plone, including Volto and the Classic UI mockup.