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 Create a 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 notification from GitHub.
Allow up to one week for processing. Contact the Plone Foundation by its email address for further information, including the status of 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.
First-time contributors should read and follow our guide First-time contributors.
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 packages require that you include a change log entry or news item with your contribution. This is enforced by continuous integration through GitHub Actions.
towncrier to manage change log entries and to automatically generate history or change log files from the entries.
The log file is usually named
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.
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
Thus for Volto and its packages, change log entries should be created in
packages/PACKAGE_NAME/news/, which is the root of the package.
The change log entry's format must be
### is the referenced GitHub issue or pull request number,
. is the literal extension delimiter, and
type is one of the following strings.
breakingfor breaking changes
bugfixfor bug fixes
featurefor new features
internalfor internal changes
A package configures the types it allows in a file
towncrier.toml located at the root of its package directory.
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
These change log entries become narrative documentation.
You can write good change log entries 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.
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
Changed a few broken links in `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.
The primary Plone project. See its repository.
"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.
Plone 6 default frontend. See Contributing to Volto.
The Plone Release Team manages the release of new versions of Plone.