docs: Add RELEASE.md for the release process

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-<major>.<minor>` 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. `<yourname>/cut-<major>.<minor>.<patch>`,
-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-<major>.<minor>` tag on GitHub with the `<version>` 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. `<yourname>/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.

RELEASE.md

@@ -0,0 +1,163 @@
+# Release
+
+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
+
+We use [Semantic Versioning](https://semver.org/).
+
+- Maintain separate `release-<major>.<minor>` branches
+- Branch protection enabled automatically for `release-*` branches
+- Bug fixes go to the latest release branch, then merge to main
+- Features and changes go to main branch
+- 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
+   - 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
+
+1. Create release branch:
+
+   ```bash
+   git checkout -b release-<major>.<minor> main
+   git push origin release-<major>.<minor>
+   ```
+
+2. Create a new branch on top of `release-<major>.<minor>`:
+
+   ```bash
+   git checkout -b <yourname>/cut-<major>.<minor>.0 release-<major>.<minor>
+   ```
+
+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`
+
+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](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
+   - Click "Publish release"!
+
+8. Announce release:
+   - <[email protected]>
+   - Slack
+   - x.com/BlueSky
+
+9. Merge release branch to main:
+
+   ```bash
+   git checkout main
+   git merge --no-ff release-<major>.<minor>
+   ```
+
+## Cutting a Patch Release
+
+1. Create branch from release branch:
+
+   ```bash
+   git checkout -b <yourname>/cut-<major>.<minor>.<patch> release-<major>.<minor>
+   ```
+
+2. Apply fixes:
+   - Commit the required fixes; avoid refactoring or otherwise risky changes (preferred)
+   - Cherry-pick from main if fix was already merged there: `git cherry-pick <commit>`
+
+3. Follow steps 3-9 from minor release process
+
+## Handling Merge Conflicts
+
+If conflicts occur merging to main:
+
+1. Create branch: `<yourname>/resolve-conflicts`
+2. Fix conflicts there
+3. PR into main
+4. Leave release branch unchanged
+
+## Note on Versioning
+
+## Compatibility Guarantees
+
+### Supported Go Versions
+
+- Support provided only for the three most recent major Go releases
+- 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):
+
+
+## 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
+
+### Compatibility Testing
+
+Before each release:
+
+1. **Internal Testing**:
+   - Full test suite must pass
+   - Integration tests with latest Prometheus server
+   - (optional) Benchmark comparisons with previous version
+   > There is no facility for running benchmarks in CI, so this is best-effort.
+
+2. **External Validation**:
+
+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
+
+- 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
+
+### 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)
+