docs/release_process.md
The schedule for the upcoming v0.24 release is:
release/0.24.x.This document describes the bpftrace release process.
We choose to follow semantic versioning. Note that this doesn't matter much for major version < 1 but will matter a lot for >= 1.0.0 releases.
See https://semver.org/.
bpftrace is released twice a year. Since our biggest dependency, which also tends to break things, is LLVM, we align with the LLVM release schedule. In particular, a minor bpftrace release should happen two weeks after a major LLVM release.
If patch releases are necessary, there should be at least one week between two successive releases to improve predictability for consumers of bpftrace releases and reduce work for bpftrace packagers.
In addition, four weeks before the bpftrace release, we create a stabilized release branch, which will only receive bug fixes affecting the release itself. The branch will also serve as a target for future (post-release) bug fixes that should get into that minor release (by creating a new "patch" release).
Overview of the release cadence is as follows:
| Task | Approximate date | Details |
|---|---|---|
| release branch created | 2 weeks before the LLVM release | Creating a release branch |
| LLVM release | usually second Tuesday of Mar/Sep | LLVM release schedule |
| bpftrace release | 2 weeks after the LLVM release | Tagging a release |
| patch releases | weekly cadence after the release as necessary | Tagging a release |
Once the release dates are clarified (approximately 6 weeks before the release), do the following steps to track the release in a public manner:
A release branch should be created four weeks before the planned bpftrace release. From that moment, only relevant bug fixes should be backported to the branch.
The purpose of this release branch is to give sufficient time to test features in the upcoming bpftrace release without blocking the development on the master branch.
When creating a branch for a release v0.Y.0, the following steps should be performed:
## Unreleased header with ## [0.Y.0] TBD and creating a new "Unreleased"
section with all the subsection headers below it.bpftrace_VERSION_MINOR in CMakeLists.txt to
Y.v0.Y-rc0.nix flake update nixpkgs
flake.lock changes to the repo. At this time, the -rc2
or -rc3 version of LLVM should be available.There should be one release branch per "major release" (we are currently
pre-1.0, "major" refers to semver minor version). The name should follow the
format release/<major>.<minor>.x.
Example branch names:
* release/0.21.x
* release/1.0.x
* release/1.1.x
Any change relevant for both the master and the release branch (such as Nixpkgs or LLVM update) should be done in the master branch first and backported to the release branch afterwards. In the rare case when the master-first approach is not possible (e.g. a feature present exclusively on master blocks the LLVM update), the changes can be done in the release branch first and forward-ported to master afterwards.
For backporting changes from one branch to another, use
git cherry-pick -s -x <sha1>
and do not squash the commits when merging the PR. This will retain a clear connection between the original and the backported commit.
You must do the following steps to formally release a version.
In the release branch:
TBD with
the current date in the corresponding header.vX.Y.Z format. The tag description should
be the same as what was added in the CHANGELOG.md with the addition of a "Release
Highlights" section at the top (example).scripts/create-assets.sh from
bpftrace root dir and attach the generated archives to the release.Once the release is out:
## Unreleased header with ## [X.Y.Z] TODAY'S DATE or adding this header
if one doesn't exist.bpftrace_VERSION_PATCH in CMakeLists.txt to
Z.