Contributing to Volto
Contributing to Volto#
You may have an issue to report, make a feature request, report a security vulnerability, or you want to create a pull request. You have come to the right place to learn how to do so.
Reporting an issue or making a feature request#
If you know the issue or feature request is for Volto, first search for an existing item in the Volto issue tracker.
In your report, please specify a few things:
What are the steps to reproduce the problem?
What do you expect when you follow those steps?
What do you observe?
Which Plone version are you using?
Include relevant screenshots, error messages, and stack traces.
The Volto team enforces the following branch policy when developers contribute to its core.
Releases of general packages (
@plone/scripts, and so on) are cut from the
- stable and latest
The terms stable and latest mean the same thing in this policy. They refer to the stable and latest released version of Volto. They have no branch names in git.
The term canary refers to the metaphorical canary in a coalmine; if an issue is detected following its release, the damage is limited to only those users who have installed it. It usually includes experimental and breaking features for testing. During the development process, a canary release will be cut from the
masterbranch. When it becomes worthy of a beta or release candidate version, a new numbered branch should be cut, and non-breaking changes must be merged into it.
A version that it is unsupported and receives no bug fixes. It has no branch name in git.
This is the bleeding edge branch in git. It is the branch upon which future development occurs, and from which future releases shall be cut.
When we cut a release candidate, we:
create a new numbered git branch from master, and
cut a release candidate version whose name aligns with the new numbered git branch.
For example, when we cut the release candidate version 16.0.0-rc.1, we created a git branch
16.x.x. We also freeze the release candidate, and stop adding features to it. This allows us to continue development on
master, which may include both breaking changes that must not be backported, and bug fixes and feature additions that may be backported but only after the release candidate becomes final.
When opening a pull request, the contributor must open it against
master. If the pull request is a feature or a bugfix, and if the release manager deems it useful to the latest version's branch, they may ask the contributor to backport it to that branch.
This is the current actively developed branch in git, meaning that it may receive new features and bug fixes. Its version is currently at 16.0.0-rc.1 as a release candidate. It will become the stable version upon the final release of version 16.0.0.
At the moment of this writing,
15.x.xis the current stable branch in git. Upon the final release of version 16.0.0, the
15.x.xbranch line will become legacy.
Translation contributing policy#
Due to the nature of
16.x.x branches, some developments that may land in
master may not be backported to
16.x.x. This means that many translations that may come with those developments will be useless in the
16.x.x branch and thus porting them to
16.x.x makes no sense.
So when contributing translations, please create PRs directly from branches created from
16.x.x and point your PRs to that exact branch instead of
Create a pull request#
You must sign the Plone Contributor Agreement to contribute code and documentation to any Plone project. This means that we can NOT accept pull requests from you until you do this.
All pull requests must include a
towncrier news item.
This is a file that is placed in the root of the repository directory at
Its 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
If the feature includes a breaking change, you must include instructions for how to upgrade in the upgrade guide.
All text that can be shown in a browser must be translatable. Please mark all such strings as translatable as defined in the i18n guide.
All pull requests must pass tests, documentation builds, and other code quality checks. Contributors are strongly encouraged to run these checks locally before creating a pull request. These checks are enforced automatically on every pull request, so you might as well save time and frustration by doing these checks locally first.
If after reading this you become hesitant, don't worry. You can always create a pull request, mark it as "Draft", and improve the above points later, requesting help from the community.
Welcome to the Plone community, and thank you for contributing!