Contributing to Volto
Contributing to Volto#
First read Contributing to Plone. Volto follows those guidelines with a few specific variations, as described in this chapter.
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.
Sign and return the Plone Contributor Agreement#
The Volto Team reviews pull requests only from people with a GitHub account who have signed and returned the Plone Contributor Agreement, and subsequently been assigned to a Plone Team in GitHub.
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
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.
Change log entry#
Volto requires that you include a change log entry or news item with your contribution.
Your attribution must be in the format of
For details see Change log entry.
Documenting your changes#
If the feature includes a breaking change, you must include instructions for how to upgrade in the upgrade guide.
All pull requests must pass tests, documentation builds, and other code quality checks. These checks are enforced automatically on every pull request, so you might as well save time and frustration by doing these checks locally first.
When referring to installation and configuration of Plone's backend, this part of the Volto documentation may have obsolete content. The most current information for installing and configuring Plone is in Install. Please report any issues in the Volto issue tracker.
If you become hesitant after reading the foregoing, don't worry. You can always create a pull request, mark it as "Draft", and improve these points later while requesting help from the community.