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.

Report an issue or make 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.

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.

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

main

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 main, 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 main, 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, you must open it against main, unless it involves translations. See Branch policy for translations for details.

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 you to backport it to that branch.

17.x.x

17.x.x is the current stable and actively developed branch in git. Upon the final release of version 18.0.0, the 17.x.x branch line will be no longer supported. Any new feature will be merged into the main branch, and only backported to and released in older versions, if the Volto Team approves it.

16.x.x

This version of Volto has the same maintenance and support schedule as Plone 6.0. It receives bug fixes and security updates. Any new feature will be merged into the main branch, and only backported to and released in older versions, if the Volto Team approves it.

15.x.x

15.x.x and older branches are no longer supported. If you need a bug fix or security update to any of them, please submit a pull request, and the Volto Team will review it to determine whether it's suitable to merge.

Install Volto for development#

For developing Volto, follow Develop Volto core.

Translations#

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.

Branch policy for translations#

Due to the nature of main and numbered released branches, some developments that may land in main may not be backported to these branches. This means that many translations that may come with those developments will be useless in the released branches, thus backporting them makes no sense.

When contributing translations, please create a branch from the numbered released branch, and point your pull request to that branch, instead of main.

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 @github_username.

See also

For details see Change log entry.

Document breaking changes#

If the feature includes a breaking change, you must include instructions for how to upgrade in the upgrade guide.

Code quality#

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.

Specifically:

Developer guidelines#

Final advice#

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.

Contents