From abf357c979adae7c5fcf9bf26aa317ba3c725ba2 Mon Sep 17 00:00:00 2001 From: Kemal Akkoyun Date: Tue, 19 Nov 2024 18:10:35 +0100 Subject: [PATCH 1/2] docs: Add RELEASE.md for the release process docs: update README for version compatibility Signed-off-by: Kemal Akkoyun --- README.md | 29 +++------- RELEASE.md | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+), 23 deletions(-) create mode 100644 RELEASE.md diff --git a/README.md b/README.md index 8168facc7..ca19eb826 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,12 @@ This is the [Go](http://golang.org) client library for instrumenting application code, and one for creating clients that talk to the Prometheus HTTP API. -**This library requires Go1.21 or later.** -> The library mandates the use of Go1.21 or subsequent versions. While it has demonstrated functionality with versions as old as Go 1.17, our commitment remains to offer support and rectifications for only the most recent three major releases. +## Version Compatibility + +This library supports the three most recent major releases of Go. While it may function with older versions, we only provide fixes and support for the currently supported Go releases. + +> [!NOTE] +> See our [Release Process](RELEASE.md#supported-go-versions) for details on compatibility and support policies. ## Important note about releases and stability @@ -68,24 +72,3 @@ See the [contributing guidelines](CONTRIBUTING.md) and the [Community section](http://prometheus.io/community/) of the homepage. `client_golang` community is also present on the CNCF Slack `#prometheus-client_golang`. - -### For Maintainers: Release Process - -To cut a minor version: - -1. Create a new branch `release-.` on top of the `main` commit you want to cut the version from and push it. -2. Create a new branch on top of the release branch, e.g. `/cut-..`, -3. Change the `VERSION` file. -4. Update `CHANGELOG` (only user-impacting changes to mention). -5. Create PR, and get it reviewed. -6. Once merged, create a release with the `release-.` tag on GitHub with the `` title. -7. Announce on the prometheus-announce mailing list, slack and Twitter. -8. Merge the release branch back to the `main` using the "merge without squashing" approach (!). - -> NOTE: In case of merge conflicts, you can checkout the release branch in a new branch, e.g. `/resolve-conflicts`, fix the merge problems there, and then do a PR into main from the new branch. In that way, you still get all the commits in the release branch back into `main`, but leave the release branch alone. - -To cut the patch version: - -1. Create a branch on top of the release branch you want to use. -2. Cherry-pick the fixes from the `main` branch (or add new commits) to fix critical bugs for that patch release. -3. Follow steps 3-8 as above. diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 000000000..63d55758c --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,152 @@ +# Release + +The Prometheus Go client library follows a release process similar to the [Prometheus server](https://github.com/prometheus/prometheus/blob/main/RELEASE.md). + +## Branch Management + +We use [Semantic Versioning](https://semver.org/). + +- Maintain separate `release-.` branches +- Branch protection enabled automatically for `release-*` branches +- Bug fixes go to latest release branch, then merge to main +- Features and changes go to main branch +- Older release branches maintained on best-effort basis + +## Pre-Release Preparations + +1. Review main branch state: + - Expedite critical bug fixes + - Hold back risky changes + - Update dependencies via Dependabot PRs + - Check for security alerts + +## Cutting a Minor Release + +1. Create release branch: + + ```bash + git checkout -b release-. main + git push origin release-. + ``` + +2. Create feature branch: + + ```bash + git checkout -b /cut-..0 release-. + ``` + +3. Update version and documentation: + - Update `VERSION` file + - Update `CHANGELOG.md` (user-impacting changes) + - Order: [SECURITY], [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX] + - For RCs, append `-rc.0` + +4. Create PR and get review + +5. After merge, create tags: + + ```bash + tag="v$(< VERSION)" + git tag -s "${tag}" -m "${tag}" + git push origin "${tag}" + ``` + +6. For Release Candidates: + - Create PR against prometheus/prometheus using RC version + - Create PR against kubernetes/kubernetes using RC version + - Make sure the CI is green for the PRs + - Allow 1-2 days for downstream testing + - Fix any issues found before final release + - Use `-rc.1`, `-rc.2` etc. for additional fixes + +7. For Final Release: + - Wait for CI completion + - Verify artifacts published + - Click "Publish release" + - For RCs, ensure "pre-release" box is checked + +8. Announce release: + - + - Slack + - x.com/BlueSky + +9. Merge release branch to main: + + ```bash + git checkout main + git merge --no-ff release-. + ``` + +## Cutting a Patch Release + +1. Create branch from release branch: + + ```bash + git checkout -b /cut-.. release-. + ``` + +2. Apply fixes: + - Cherry-pick from main: `git cherry-pick ` + - Or add new fix commits + +3. Follow steps 3-9 from minor release process + +## Handling Merge Conflicts + +If conflicts occur merging to main: + +1. Create branch: `/resolve-conflicts` +2. Fix conflicts there +3. PR into main +4. Leave release branch unchanged + +## Note on Versioning + +Go modules require strict semver. Because we don't commit to avoid breaking changes between minor releases, we use major version zero releases for libraries. + +## Compatibility Guarantees + +### Supported Go Versions + +- Support provided only for the three most recent major Go releases +- While the library may work with older versions, no fixes or support provided +- Each release documents the minimum required Go version + +### API Stability + +The Prometheus Go client library aims to maintain backward compatibility within minor versions, similar to [Go 1 compatibility promises](https://golang.org/doc/go1compat). However, as indicated by the major version zero (v0): + +- API signatures may change between minor versions +- Types may be modified or relocated +- Default behaviors might be altered +- Feature removal/deprecation can occur with minor version bump + +### Compatibility Testing + +Before each release: + +1. **Internal Testing**: + - Full test suite must pass + - Integration tests with latest Prometheus server + - Benchmark comparisons with previous version + +2. **External Validation**: + - Testing with prometheus/prometheus master branch + - Testing with kubernetes/kubernetes master branch + - Breaking changes must be documented in CHANGELOG.md + +### Version Policy + +- Bug fixes increment patch version (e.g., v0.9.1) +- New features increment minor version (e.g., v0.10.0) +- Breaking changes increment minor version with clear documentation +- Major version remains at 0 to indicate potential instability + +### Deprecation Policy + +1. Features may be deprecated in any minor release +2. Deprecated features: + - Will be documented in CHANGELOG.md + - Will emit warnings when used (when possible) + - May be removed in next minor version + - Must have migration path documented From ed52a8965265c90a0c4fa2bac0f8474bbf403c18 Mon Sep 17 00:00:00 2001 From: Kemal Akkoyun Date: Mon, 20 Jan 2025 15:39:23 +0100 Subject: [PATCH 2/2] Address review comments Signed-off-by: Kemal Akkoyun --- RELEASE.md | 59 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 63d55758c..ebeccc01a 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,6 +1,6 @@ # Release -The Prometheus Go client library follows a release process similar to the [Prometheus server](https://github.com/prometheus/prometheus/blob/main/RELEASE.md). +The Prometheus Go client library does not follow a strict release schedule. Releases are made based on necessity and the current state of the project. ## Branch Management @@ -8,16 +8,16 @@ We use [Semantic Versioning](https://semver.org/). - Maintain separate `release-.` branches - Branch protection enabled automatically for `release-*` branches -- Bug fixes go to latest release branch, then merge to main +- Bug fixes go to the latest release branch, then merge to main - Features and changes go to main branch -- Older release branches maintained on best-effort basis +- Non-latest minor release branches are maintained (e.g. bug and security fixes) on the best-effort basis ## Pre-Release Preparations 1. Review main branch state: - Expedite critical bug fixes - - Hold back risky changes - - Update dependencies via Dependabot PRs + - Don't rush on risky changes, consider them for the next release if not ready + - Update dependencies via Dependabot PRs or manually if needed - Check for security alerts ## Cutting a Minor Release @@ -29,7 +29,7 @@ We use [Semantic Versioning](https://semver.org/). git push origin release-. ``` -2. Create feature branch: +2. Create a new branch on top of `release-.`: ```bash git checkout -b /cut-..0 release-. @@ -38,6 +38,7 @@ We use [Semantic Versioning](https://semver.org/). 3. Update version and documentation: - Update `VERSION` file - Update `CHANGELOG.md` (user-impacting changes) + - Each release documents the minimum required Go version - Order: [SECURITY], [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX] - For RCs, append `-rc.0` @@ -52,18 +53,17 @@ We use [Semantic Versioning](https://semver.org/). ``` 6. For Release Candidates: - - Create PR against prometheus/prometheus using RC version - - Create PR against kubernetes/kubernetes using RC version + - Create PR against [prometheus/prometheus](https://github.com/prometheus/prometheus) using RC version + - Create PR against [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) using RC version - Make sure the CI is green for the PRs - Allow 1-2 days for downstream testing - Fix any issues found before final release - Use `-rc.1`, `-rc.2` etc. for additional fixes + - For RCs, ensure "pre-release" box is checked 7. For Final Release: - Wait for CI completion - - Verify artifacts published - - Click "Publish release" - - For RCs, ensure "pre-release" box is checked + - Click "Publish release"! 8. Announce release: - @@ -86,8 +86,8 @@ We use [Semantic Versioning](https://semver.org/). ``` 2. Apply fixes: - - Cherry-pick from main: `git cherry-pick ` - - Or add new fix commits + - Commit the required fixes; avoid refactoring or otherwise risky changes (preferred) + - Cherry-pick from main if fix was already merged there: `git cherry-pick ` 3. Follow steps 3-9 from minor release process @@ -102,21 +102,30 @@ If conflicts occur merging to main: ## Note on Versioning -Go modules require strict semver. Because we don't commit to avoid breaking changes between minor releases, we use major version zero releases for libraries. - ## Compatibility Guarantees ### Supported Go Versions - Support provided only for the three most recent major Go releases -- While the library may work with older versions, no fixes or support provided +- While the library may work with older Go versions, support and fixes are best-effort for those. - Each release documents the minimum required Go version ### API Stability -The Prometheus Go client library aims to maintain backward compatibility within minor versions, similar to [Go 1 compatibility promises](https://golang.org/doc/go1compat). However, as indicated by the major version zero (v0): +The Prometheus Go client library aims to maintain backward compatibility within minor versions, similar to [Go 1 compatibility promises](https://golang.org/doc/go1compat): -- API signatures may change between minor versions + +## Minor Version Changes +- API signatures are `stable` within a **minor** version +- No breaking changes are introduced +- Methods may be added, but not removed + - Arguments may NOT be removed or added (unless varargs) + - Return types may NOT be changed +- Types may be modified or relocated +- Default behaviors might be altered (unfortunately, this has happened in the past) + +## Major Version Changes +- API signatures may change between **major** versions - Types may be modified or relocated - Default behaviors might be altered - Feature removal/deprecation can occur with minor version bump @@ -128,11 +137,15 @@ Before each release: 1. **Internal Testing**: - Full test suite must pass - Integration tests with latest Prometheus server - - Benchmark comparisons with previous version + - (optional) Benchmark comparisons with previous version + > There is no facility for running benchmarks in CI, so this is best-effort. 2. **External Validation**: - - Testing with prometheus/prometheus master branch - - Testing with kubernetes/kubernetes master branch + +Test against bigger users, especially looking for broken tests or builds. This will give us awareness of a potential accidental breaking changes, or if there were intentional ones, the potential damage radius of them. + + - Testing with [prometheus/prometheus](https://github.com/prometheus/prometheus) `main` branch + - Testing with [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) `main` branch - Breaking changes must be documented in CHANGELOG.md ### Version Policy @@ -140,7 +153,6 @@ Before each release: - Bug fixes increment patch version (e.g., v0.9.1) - New features increment minor version (e.g., v0.10.0) - Breaking changes increment minor version with clear documentation -- Major version remains at 0 to indicate potential instability ### Deprecation Policy @@ -148,5 +160,4 @@ Before each release: 2. Deprecated features: - Will be documented in CHANGELOG.md - Will emit warnings when used (when possible) - - May be removed in next minor version - - Must have migration path documented +