Release Process

Automatic Release Process

GitHub Release

1. Check for open security PRs from Dependabot or Renovate. Review and merge any applicable security fixes to avoid shipping known vulnerabilities.

2. Create a new branch for the release (e.g., release/vX.Y).

   [!IMPORTANT] The release branch should only contain the major (X) and minor (Y) version, but not the patch level (Z), for example:

   ✅ Correct: release/v1.3

   ⚠️ Incorrect: release/v1.3.0

3. Create the tag for the release (e.g., vX.Y.Z)

4. Push the release branch and tag to the remote. Note that the tag will kick off a release workflow via goreleaser.

5. Create a GitHub label for backports:

   gh label create "backport release/vX.Y" -d "This label will backport a merged PR to the release/vX.Y branch" -c "#0052cc"

The CI will automatically handle the build and then create and publish a new GitHub release. Please do not delete GitHub releases that were once public.

GitHub Release Notes

Once the release is published, you should edit the release notes in GitHub. Use the already generated changelog and summarize it in the main categories:

• Features and enhancements
• (optional) Breaking changes
• Bug fixes
• Documentation updates

Keep the generated changelog as is, after the summary sections.

Make sure each release note has full links to the relevant pull requests.

Website Release Notes

The list of changes from the GitHub release forms the basis of the public-facing release notes. Release notes are added to the public Pyroscope documentation.

GitHub Workflow

The website release notes need to be added to both the release/vX.Y branch and the main branch. The recommended workflow is to:

1. Add the changes with a PR against the main branch
2. Add a backport label and a type/docs label to the PR
3. Address feedback from reviewers and merge the PR

Writing Website Release Notes

The release notes follow the same pattern for each release:

1. Copy the previous release's page (i.e., V1-3.md) to the new release number. Change the version information and page weight in the file's frontmatter.
2. Update the page title (Version X.Y release notes) and add a few sentences about the main updates in the release.
3. Copy over the summary sections from the GitHub release notes. Make sure to use full links to the relevant pull requests.

For help writing release notes, refer to the Writers' Toolkit.

Helm Chart Update

Merge a PR that bumps the chart version and updates the appVersion to the latest release Pyroscope in the main branch (no tagging required), the CI will automatically publish the chart to the helm repository.

Helm Chart Versioning

The Helm chart version and Pyroscope application version are separate and won't always match. The Chart.yaml file contains two distinct version fields:

• version: The Helm chart version
• appVersion: The Pyroscope application version

Versioning Strategy:

• We aim for a best effort match between chart version and Pyroscope version when releasing new Pyroscope versions
• Changes that only affect the Helm chart (templates, values, chart configuration) should be released as patch releases of the chart only, without requiring a new Pyroscope release
• Example: If the current chart is v1.10.2 (with appVersion: v1.10.2), a chart-only fix would bump to v1.10.3 while keeping appVersion: v1.10.2

Backport

A PR to be backported must have the appropriate backport release/vX.Y label(s) AND one of these expected labels: ['type/docs', 'type/bug', 'product-approved', 'type/ci']. Note that these labels must be present before the PR is merged.

Example backport PR

Patch Releases

When a patch release is needed, make PRs containing the necessary changes against the appropriate release/vX.Y branch.

Changes done in patch releases should be documented in the existing website release notes for that version under a new heading with the version number. These documentation changes should be done with a PR against the appropriate release branch and then backported to the main branch.

Before tagging, check for open security PRs from Dependabot or Renovate. Review, merge, and backport any applicable security fixes to the release/vX.Y branch.

Once the release notes are merged, a vX.Y.Z patch release tag must be created and pushed to remote to create a new release.

[!WARNING] If you are releasing a patch version, for an older major/minor version (example: you are releasing v1.15.2, but the current latest release is v1.16.0), you need to make sure the release's actions to publish a :latest docker image tag and a home-brew formula are removed:

This can be done by updating release.yml in the previous release branches to set $IMAGE_PUBLISH_LATEST=false.

Manual Release Process

The release process uses goreleaser and can be configured using the .goreleaser.yaml.

To create a new release first prepare the release using:

make release/prepare

This will build and packages all artifacts without pushing or creating the GitHub release.

Once you're ready you can then tag your release.

git tag v0.1.0

And finally push the release using:

make release

Make sure to have a GitHub Token GITHUB_TOKEN correctly set.

Make sure to create the release notes and CHANGELOG for any manual release.