From 31f0678cdf1bfd82bb7b7270e30cdd29d999d6cb Mon Sep 17 00:00:00 2001 From: machine424 Date: Wed, 25 Mar 2026 18:00:17 +0100 Subject: [PATCH 1/2] release: automate CHANGELOG.md generation and improve release notes process MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds `scripts/generate_release_notes.sh` to produce a structured CHANGELOG.md starting point using the Kubernetes release-notes tool. It handles both minor and patch releases. `RELEASE.md` is updated to reference the script and drop the manual instructions. Version examples are updated from 2.x to 3.x. The `check_release_notes` CI workflow is extended to also run on `release-*` branches in order for the script to catch commits added to the release note , and the PR template wording is tightened. Signed-off-by: machine424 --- .github/PULL_REQUEST_TEMPLATE.md | 19 ++++-- .github/workflows/check_release_notes.yml | 3 +- RELEASE.md | 33 +++++---- scripts/generate_release_notes.sh | 83 +++++++++++++++++++++++ 4 files changed, 115 insertions(+), 23 deletions(-) create mode 100755 scripts/generate_release_notes.sh diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7873822f26..58641d17d8 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -22,14 +22,19 @@ Usage: `Fixes #`, or `Fixes (paste link of issue)`. More at https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword --> -#### Does this PR introduce a user-facing change? +#### Release notes for end users (**ALL** commits must be considered). +*Reviewers should verify clarity and quality.* + ```release-notes diff --git a/.github/workflows/check_release_notes.yml b/.github/workflows/check_release_notes.yml index cfc4264602..6934c1c472 100644 --- a/.github/workflows/check_release_notes.yml +++ b/.github/workflows/check_release_notes.yml @@ -1,8 +1,7 @@ name: 'Check release notes' on: pull_request: - branches: - - main + branches: [main, 'release-*'] types: - opened - reopened diff --git a/RELEASE.md b/RELEASE.md index 5c29b0a522..c271170afe 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -44,7 +44,7 @@ These instructions are currently valid for the Prometheus server, i.e. the [prom We use [Semantic Versioning](https://semver.org/). -We maintain a separate branch for each minor release, named `release-.`, e.g. `release-1.1`, `release-2.0`. +We maintain a separate branch for each minor release, named `release-.`, e.g. `release-2.1`, `release-3.0`. Note that branch protection kicks in automatically for any branches whose name starts with `release-`. Never use names starting with `release-` for branches that are not release branches. @@ -107,26 +107,31 @@ though this may be done at convenient times (e.g. by the UI maintainers) that ar ### 1. Prepare your release -At the start of a new major or minor release cycle create the corresponding release branch based on the main branch. For example if we're releasing `2.17.0` and the previous stable release is `2.16.0` we need to create a `release-2.17` branch. Note that all releases are handled in protected release branches, see the above `Branch management and versioning` section. Release candidates and patch releases for any given major or minor release happen in the same `release-.` branch. Do not create `release-` for patch or release candidate releases. +At the start of a new major or minor release cycle create the corresponding release branch based on the main branch. For example if we're releasing `3.7.0` and the previous stable release is `3.6.0` we need to create a `release-3.7` branch. Note that all releases are handled in protected release branches, see the [Branch management and versioning strategy](#branch-management-and-versioning-strategy) section. Release candidates and patch releases for any given major or minor release happen in the same `release-.` branch. Do not create `release-` for patch or release candidate releases. Changes for a patch release or release candidate should be merged into the previously mentioned release branch via pull request. -Bump the version in the `VERSION` file and update `CHANGELOG.md`. Do this in a proper PR pointing to the release branch as this gives others the opportunity to chime in on the release in general and on the addition to the changelog in particular. For a release candidate, append something like `-rc.0` to the version (with the corresponding changes to the tag name, the release name etc.). +Bump the version in the `VERSION` file and update `CHANGELOG.md`. Do this in a proper PR pointing to the release branch as this gives others the opportunity to chime in on the release in general and on the addition to `CHANGELOG.md` in particular. For a release candidate, append something like `-rc.0` to the version (with the corresponding changes to the tag name, the release name etc.). -When updating the `CHANGELOG.md` look at all PRs included in the release since the last release and verify if they need a changelog entry. Most PRs will have their changelog entries specified in the `release-notes` blocks within their PR descriptions. +Use [`scripts/generate_release_notes.sh`](scripts/generate_release_notes.sh) to produce a starting point for the `CHANGELOG.md` entries. It requires the [`release-notes`](https://github.com/kubernetes/release/tree/master/cmd/release-notes) tool and a `GITHUB_TOKEN` with read access to the repository: -Note that `CHANGELOG.md` should only document changes relevant to users of Prometheus, including external API changes, performance improvements, and new features. Do not document changes of internal interfaces, code refactorings and clean-ups, changes to the build process, etc. People interested in these are asked to refer to the git history. +Minor release (any RC or final, e.g. `v3.11.0-rc.0`, `v3.11.0-rc.1`, `v3.11.0`): -For release candidates still update `CHANGELOG.md`, but when you cut the final release later, merge all the changes from the pre-releases into the one final update. +```bash +GITHUB_TOKEN= scripts/generate_release_notes.sh 3.Y_SET_ME.0 +``` -Entries in the `CHANGELOG.md` are meant to be in this order: +Patch release (e.g. `v3.11.2`): -* `[SECURITY]` - A bugfix that specifically fixes a security issue. -* `[CHANGE]` -* `[FEATURE]` -* `[ENHANCEMENT]` -* `[PERF]` -* `[BUGFIX]` +```bash +GITHUB_TOKEN= scripts/generate_release_notes.sh 3.Y_SET_ME.Z_SET_ME +``` + +Review the output carefully before adding it to `CHANGELOG.md`: + +- Remove entries already present in a previous release's Changelog. Duplicates can appear for fixes merged to the previous release branch. +- `CHANGELOG.md` should only document changes relevant to users of Prometheus, including external API changes, performance improvements, and new features. Do not document changes of internal interfaces, code refactorings and clean-ups, changes to the build process, etc. People interested in these are asked to refer to the git history. +- For release candidates, continue updating `CHANGELOG.md`. When you cut the final release, consolidate all changes from the pre-releases into a single final entry. Then bump the UI module version: @@ -180,7 +185,7 @@ git push origin "${tag}" ### 4. Wrapping up -For release candidate versions (`v2.16.0-rc.0`), run the benchmark for 3 days using the `/prombench vX.Y.Z` command, `vX.Y.Z` being the latest stable patch release's tag of the previous minor release series, such as `v2.15.2`. +For release candidate versions (`v3.6.0-rc.0`), run the benchmark for 3 days using the `/prombench vX.Y.Z` command, `vX.Y.Z` being the latest stable patch release's tag of the previous minor release series, such as `v3.5.2`. If the release has happened in the latest release branch, merge the changes into main. diff --git a/scripts/generate_release_notes.sh b/scripts/generate_release_notes.sh new file mode 100755 index 0000000000..2ded5e8a52 --- /dev/null +++ b/scripts/generate_release_notes.sh @@ -0,0 +1,83 @@ +#!/usr/bin/env bash + +set -u -o pipefail + +if ! [[ "$0" =~ scripts/generate_release_notes.sh ]]; then + echo "must be run from repository root" + exit 1 +fi + +if [[ $# -ne 1 ]]; then + echo "usage: scripts/generate_release_notes.sh " + echo "examples:" + echo " scripts/generate_release_notes.sh 3.11.0" + echo " scripts/generate_release_notes.sh 3.11.0-rc.0" + echo " scripts/generate_release_notes.sh 3.11.0-rc.1" + echo " scripts/generate_release_notes.sh 3.11.1" + exit 1 +fi + +version="${1#v}" +IFS='.' read -r major minor patch_rest <<< "${version}" +# Strip any pre-release suffix (e.g. "0-rc.0" -> "0"). +patch="${patch_rest%%-*}" + +if [[ -z "${GITHUB_TOKEN:-}" ]]; then + echo "GITHUB_TOKEN is not set" + exit 1 +fi +if ! command -v release-notes >/dev/null 2>&1; then + echo "release-notes not found. Install: go install k8s.io/release/cmd/release-notes@v0.20.1" + exit 1 +fi + +TMPL='{{- $version := .CurrentRevision -}} +{{- if not $version}}{{- $version = "X.Y.Z" -}}{{end -}} +## {{$version}} / YYYY-MM-DD +{{/* Sort the sections */}} +{{- range .Notes}}{{range $note := .NoteEntries}}{{if eq (slice $note 0 10) "[SECURITY]"}}- {{$note}} +{{end}}{{end}}{{end -}} +{{- range .Notes}}{{range $note := .NoteEntries}}{{if eq (slice $note 0 8) "[CHANGE]"}}- {{$note}} +{{end}}{{end}}{{end -}} +{{- range .Notes}}{{range $note := .NoteEntries}}{{if eq (slice $note 0 9) "[FEATURE]"}}- {{$note}} +{{end}}{{end}}{{end -}} +{{- range .Notes}}{{range $note := .NoteEntries}}{{if eq (slice $note 0 13) "[ENHANCEMENT]"}}- {{$note}} +{{end}}{{end}}{{end -}} +{{- range .Notes}}{{range $note := .NoteEntries}}{{if eq (slice $note 0 6) "[PERF]"}}- {{$note}} +{{end}}{{end}}{{end -}} +{{- range .Notes}}{{range $note := .NoteEntries}}{{if eq (slice $note 0 8) "[BUGFIX]"}}- {{$note}} +{{end}}{{end}}{{end}} +.' + +release_branch="release-${major}.${minor}" + +if [[ "${patch}" == "0" ]]; then + # Minor release (any RC or final): cover the full cycle from the previous minor's branch-cut point. + prev_minor=$(( minor - 1 )) + start_sha="$(git log -1 --format='%P' "v${major}.${prev_minor}.0-rc.0" | awk '{print $1}')" + end_rev="${release_branch}" + echo "Generating release notes for version=${version} major=${major} minor=${minor} patch=${patch} start_sha=${start_sha} end_rev=${end_rev}" + release-notes generate \ + --start-sha="${start_sha}" \ + --end-rev="${end_rev}" \ + --branch="${release_branch}" \ + --org prometheus --repo prometheus \ + --required-author="" --dependencies=false \ + --go-template="go-template:inline:${TMPL}" \ + --output=/dev/stdout +else + # Patch release: cover commits since the previous patch tag. + prev_patch=$(( patch - 1 )) + start_rev="v${major}.${minor}.${prev_patch}" + end_rev="${release_branch}" + echo "Generating release notes for version=${version} major=${major} minor=${minor} patch=${patch} start_rev=${start_rev} end_rev=${end_rev}" + release-notes generate \ + --start-rev="${start_rev}" \ + --end-rev="${end_rev}" \ + --branch="${release_branch}" \ + --org prometheus --repo prometheus \ + --required-author="" --dependencies=false \ + --go-template="go-template:inline:${TMPL}" \ + --skip-first-commit \ + --output=/dev/stdout +fi From bf730369bda0e596aa4d155d110ff2498c5773d2 Mon Sep 17 00:00:00 2001 From: machine424 Date: Thu, 26 Mar 2026 12:28:56 +0100 Subject: [PATCH 2/2] adjust and simplify Signed-off-by: machine424 --- RELEASE.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index c271170afe..37193610a4 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -115,13 +115,7 @@ Bump the version in the `VERSION` file and update `CHANGELOG.md`. Do this in a p Use [`scripts/generate_release_notes.sh`](scripts/generate_release_notes.sh) to produce a starting point for the `CHANGELOG.md` entries. It requires the [`release-notes`](https://github.com/kubernetes/release/tree/master/cmd/release-notes) tool and a `GITHUB_TOKEN` with read access to the repository: -Minor release (any RC or final, e.g. `v3.11.0-rc.0`, `v3.11.0-rc.1`, `v3.11.0`): - -```bash -GITHUB_TOKEN= scripts/generate_release_notes.sh 3.Y_SET_ME.0 -``` - -Patch release (e.g. `v3.11.2`): +Run it for the target release version (RC, final, or patch; for example `v3.11.0-rc.0`, `v3.11.0`, or `v3.11.1`): ```bash GITHUB_TOKEN= scripts/generate_release_notes.sh 3.Y_SET_ME.Z_SET_ME @@ -131,7 +125,6 @@ Review the output carefully before adding it to `CHANGELOG.md`: - Remove entries already present in a previous release's Changelog. Duplicates can appear for fixes merged to the previous release branch. - `CHANGELOG.md` should only document changes relevant to users of Prometheus, including external API changes, performance improvements, and new features. Do not document changes of internal interfaces, code refactorings and clean-ups, changes to the build process, etc. People interested in these are asked to refer to the git history. -- For release candidates, continue updating `CHANGELOG.md`. When you cut the final release, consolidate all changes from the pre-releases into a single final entry. Then bump the UI module version: