Skip to content

guide: update documentation on release branches #2435

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 25, 2025
Merged

guide: update documentation on release branches #2435

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 22 additions & 19 deletions Guide/src/dev_guide/contrib/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
# Release Management

Occasionally, the OpenVMM project will declare upcoming release milestones. We
stabilize the code base in a `release/YYMM` branch, typically named for the
YYMM when the branch was forked. We expect a high quality bar for all code that
goes in to the OpenVMM main branch, we ask developers to hold these
`release/YYMM` to the highest quality standards. The OpenVMM maintainers will
gradually slow the rate of churn into these branches as we get closer to a
close date.
stabilize the code base in a `release/<MAJOR>.<MINOR>.<YYMM>` branch, typically
named for the YYMM when the branch was forked. Future references to the release
number will be shortened to `<RELEASE>` in this doc. We expect a high quality
bar for all code that goes into the OpenVMM main branch, and we ask developers
to hold these release branches to the highest quality standards. The OpenVMM
maintainers will gradually slow the rate of churn into these branches as we get
closer to a close date.

> **Note:** Some older release branches use the format `release/<YYMM>` without
> the major and minor version numbers (e.g., `release/2411`, `release/2505`).

This process should not impact your typical workflow; all new work should go
into the `main` branch. But, to ease the cherry-picks, we may ask that you hold
Expand All @@ -26,35 +30,33 @@ Releases naturally fall into several phases:
|-------------------|-------------------------------------------------------------------------|
| Active Development| Regular development phase where new features and fixes are added. |
| Stabilization | Phase focused on stabilizing the release by fixing bugs. |
| Ask Mode | Changes are scrutinized and only critical fixes are allowed. No new features are accepted. This is the last phase before a release is closed. |
| Servicing | Only essential fixes are made to support the release. a.k.a. maintenance mode |
| Out of service | A previous release, which is no longer receiving updates. |
| Ask Mode | Only critical fixes are allowed; changes are scrutinized. No new features. This is the last phase before a release is closed. |
| Servicing | Only essential fixes are made to support the release (a.k.a. maintenance mode). |
| Out of service | A previous release which is no longer receiving updates. |

### Release branch process

We track the state of candidates for a given release by tagging the PRs with the following labels:

* `backport_YYMM`: This PR (to `main`) is a candidate to be included in the
`YYMM` release.
* N.B.: A maintainer will _remove_ this tag if the fix is not accepted into
the release.
* `backported_YYMM`: This PR (to `main`) has been cherry-picked to the `YYMM`
release.
* `backport_<RELEASE>`: This PR (to `main`) is a candidate to be included in the release.
* N.B.: A maintainer will _remove_ this tag if the fix is not accepted into the release.
* `backported_<RELEASE>`: This PR (to `main`) has been cherry-picked to the release branch.

#### Seeking Approval for Backport

To seek approval to include a change in a release branch, follow these steps:

* Tag your PR to `main` PR with the `backport_YYMM` label.
* Cherry-pick the change to the appropriate `release/YYMM` branch in your fork
and stage a PR to that same branch in the main repository.
1. Tag your PR to `main` with the `backport_<RELEASE>` label.
2. Wait for the PR to be merged to `main`.
3. Cherry-pick the change to the appropriate release branch in your fork and
stage a PR to that same branch in the main repository.

Please reach out to the maintainers before staging that PR if you have any
doubts.

#### Backport PR Best Practices

When creating a backport PR to a `release/YYMM` branch:
When creating a backport PR to a release branch:

* **Clean cherry-picks are strongly preferred.** A clean cherry-pick minimizes
reviewer effort and reduces the risk of introducing regressions.
Expand All @@ -69,6 +71,7 @@ When creating a backport PR to a `release/YYMM` branch:
|--------|-------|-------|
| release/2411 | Out of service | |
| release/2505 | Servicing | Supports runtime servicing from release/2411. |
| release/1.7.2511 | Stabilization | Supports runtime servicing from release/2411 and release/2505. |
| _tbd, in main_ | Active Development | Supports runtime servicing from release/2411 and release/2505. |

## Taking a Dependency on a Release
Expand Down