RELEASING.md

Releasing

To ease the release process, we use the utility release-it which helps with the process, and towncrier for creating and maintaining change logs.

Release requirements

To start a release, you must fulfill the following requirements:

• Have permission to push to main branch
• Have permission on the @plone organization on npm.
• Have an environment variable GITHUB_TOKEN with a GitHub personal token with permissions to write to the Volto Release page on GitHub.
• Install pipx in your system.

To request these permissions, on GitHub tag @plone/release-team, or in Discord post to the release-team channel.

Permission to push to main branch

The release process involves pushing directly to the main branch. Volto's main branch is protected, so the releaser needs to have permission for pushing to it. At the moment of this writing, members of the GitHub group @plone/volto-team have permission to push to main.

Permission to release Volto to npm registry

We push Volto's releases to the npm registry. The releaser has to have permissions for pushing a release in the @plone organization on npm. Only the current Owners of this organization can grant permissions to the releaser.

Have a GitHub personal token with permissions to write the Volto's Releases

The release-it library takes care of creating and pushing a GitHub Release for each release. It requires you to get a GitHub personal token with permission to write to the Volto's Releases. This can be acquired in your GitHub profile page. When making a release, export the environment variable GITHUB_TOKEN in your shell session.

export GITHUB_TOKEN="my_looooong_github_token"

See release-it documentation of GitHub releases and GitHub documentation About releases.

Install pipx in your system

The release process calls towncrier. It is a Python library that uses the Python utility pipx. This utility allows you to call and execute Python modules without installing them as a prerequisite in your system. It works similar to the NodeJS npx utility.

Install {term}pipx for your active Python, and ensure it is on your $PATH. Carefully read the console output for further instructions, if needed.

python3 -m pip install pipx
pipx ensurepath

Running the release process

These are the commands to make a Volto release:

yarn release

A dry-release command for testing the output is also available:

yarn dry-release

An alpha release can be cut using:

yarn release-alpha