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.

If an issue does not already exist for your item, then you can create a new issue or feature request in Volto. When in doubt, create one in the CMFPlone 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.

Branch policy#

The Volto team enforces the following branch policy when developers contribute to its core.

Releases of general packages (@plone/generator-volto, @plone/scripts, and so on) are cut from the master branch.

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.

canary

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 master branch. 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.

legacy

A version that it is unsupported and receives no bug fixes. It has no branch name in git.

master

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:

  1. create a new numbered git branch from master, and

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

16.x.x

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.

15.x.x

At the moment of this writing, 15.x.x is the current stable branch in git. Upon the final release of version 16.0.0, the 15.x.x branch line will become legacy.

Translation contributing policy#

Due to the nature of master and 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 master.

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 /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

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.

Code Quality#

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.

Specifically:

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!