Skip to content

Commit 56a2431

Browse files
kakkoyunkakkoyun
authored
docs: Add RELEASE.md for the release process (#1690)
* docs: Add RELEASE.md for the release process docs: update README for version compatibility Signed-off-by: Kemal Akkoyun <[email protected]> * Address review comments Signed-off-by: Kemal Akkoyun <[email protected]> --------- Signed-off-by: Kemal Akkoyun <[email protected]>
1 parent cbd9526 commit 56a2431

File tree

2 files changed

+169
-23
lines changed

2 files changed

+169
-23
lines changed

‎README.md

+6-23
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,12 @@ This is the [Go](http://golang.org) client library for
1111
instrumenting application code, and one for creating clients that talk to the
1212
Prometheus HTTP API.
1313

14-
**This library requires Go1.21 or later.**
15-
> 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.
14+
## Version Compatibility
15+
16+
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.
17+
18+
> [!NOTE]
19+
> See our [Release Process](RELEASE.md#supported-go-versions) for details on compatibility and support policies.
1620
1721
## Important note about releases and stability
1822

@@ -69,24 +73,3 @@ See the [contributing guidelines](CONTRIBUTING.md) and the
6973
[Community section](http://prometheus.io/community/) of the homepage.
7074

7175
`client_golang` community is also present on the CNCF Slack `#prometheus-client_golang`.
72-
73-
### For Maintainers: Release Process
74-
75-
To cut a minor version:
76-
77-
1. Create a new branch `release-<major>.<minor>` on top of the `main` commit you want to cut the version from and push it.
78-
2. Create a new branch on top of the release branch, e.g. `<yourname>/cut-<major>.<minor>.<patch>`,
79-
3. Change the `VERSION` file.
80-
4. Update `CHANGELOG` (only user-impacting changes to mention).
81-
5. Create PR, and get it reviewed.
82-
6. Once merged, create a release with the `release-<major>.<minor>` tag on GitHub with the `<version>` title.
83-
7. Announce on the prometheus-announce mailing list, slack and Twitter.
84-
8. Merge the release branch back to the `main` using the "merge without squashing" approach (!).
85-
86-
> 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.
87-
88-
To cut the patch version:
89-
90-
1. Create a branch on top of the release branch you want to use.
91-
2. Cherry-pick the fixes from the `main` branch (or add new commits) to fix critical bugs for that patch release.
92-
3. Follow steps 3-8 as above.

‎RELEASE.md

+163
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Release
2+
3+
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.
4+
5+
## Branch Management
6+
7+
We use [Semantic Versioning](https://semver.org/).
8+
9+
- Maintain separate `release-<major>.<minor>` branches
10+
- Branch protection enabled automatically for `release-*` branches
11+
- Bug fixes go to the latest release branch, then merge to main
12+
- Features and changes go to main branch
13+
- Non-latest minor release branches are maintained (e.g. bug and security fixes) on the best-effort basis
14+
15+
## Pre-Release Preparations
16+
17+
1. Review main branch state:
18+
- Expedite critical bug fixes
19+
- Don't rush on risky changes, consider them for the next release if not ready
20+
- Update dependencies via Dependabot PRs or manually if needed
21+
- Check for security alerts
22+
23+
## Cutting a Minor Release
24+
25+
1. Create release branch:
26+
27+
```bash
28+
git checkout -b release-<major>.<minor> main
29+
git push origin release-<major>.<minor>
30+
```
31+
32+
2. Create a new branch on top of `release-<major>.<minor>`:
33+
34+
```bash
35+
git checkout -b <yourname>/cut-<major>.<minor>.0 release-<major>.<minor>
36+
```
37+
38+
3. Update version and documentation:
39+
- Update `VERSION` file
40+
- Update `CHANGELOG.md` (user-impacting changes)
41+
- Each release documents the minimum required Go version
42+
- Order: [SECURITY], [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX]
43+
- For RCs, append `-rc.0`
44+
45+
4. Create PR and get review
46+
47+
5. After merge, create tags:
48+
49+
```bash
50+
tag="v$(< VERSION)"
51+
git tag -s "${tag}" -m "${tag}"
52+
git push origin "${tag}"
53+
```
54+
55+
6. For Release Candidates:
56+
- Create PR against [prometheus/prometheus](https://github.com/prometheus/prometheus) using RC version
57+
- Create PR against [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) using RC version
58+
- Make sure the CI is green for the PRs
59+
- Allow 1-2 days for downstream testing
60+
- Fix any issues found before final release
61+
- Use `-rc.1`, `-rc.2` etc. for additional fixes
62+
- For RCs, ensure "pre-release" box is checked
63+
64+
7. For Final Release:
65+
- Wait for CI completion
66+
- Click "Publish release"!
67+
68+
8. Announce release:
69+
- <[email protected]>
70+
- Slack
71+
- x.com/BlueSky
72+
73+
9. Merge release branch to main:
74+
75+
```bash
76+
git checkout main
77+
git merge --no-ff release-<major>.<minor>
78+
```
79+
80+
## Cutting a Patch Release
81+
82+
1. Create branch from release branch:
83+
84+
```bash
85+
git checkout -b <yourname>/cut-<major>.<minor>.<patch> release-<major>.<minor>
86+
```
87+
88+
2. Apply fixes:
89+
- Commit the required fixes; avoid refactoring or otherwise risky changes (preferred)
90+
- Cherry-pick from main if fix was already merged there: `git cherry-pick <commit>`
91+
92+
3. Follow steps 3-9 from minor release process
93+
94+
## Handling Merge Conflicts
95+
96+
If conflicts occur merging to main:
97+
98+
1. Create branch: `<yourname>/resolve-conflicts`
99+
2. Fix conflicts there
100+
3. PR into main
101+
4. Leave release branch unchanged
102+
103+
## Note on Versioning
104+
105+
## Compatibility Guarantees
106+
107+
### Supported Go Versions
108+
109+
- Support provided only for the three most recent major Go releases
110+
- While the library may work with older Go versions, support and fixes are best-effort for those.
111+
- Each release documents the minimum required Go version
112+
113+
### API Stability
114+
115+
The Prometheus Go client library aims to maintain backward compatibility within minor versions, similar to [Go 1 compatibility promises](https://golang.org/doc/go1compat):
116+
117+
118+
## Minor Version Changes
119+
- API signatures are `stable` within a **minor** version
120+
- No breaking changes are introduced
121+
- Methods may be added, but not removed
122+
- Arguments may NOT be removed or added (unless varargs)
123+
- Return types may NOT be changed
124+
- Types may be modified or relocated
125+
- Default behaviors might be altered (unfortunately, this has happened in the past)
126+
127+
## Major Version Changes
128+
- API signatures may change between **major** versions
129+
- Types may be modified or relocated
130+
- Default behaviors might be altered
131+
- Feature removal/deprecation can occur with minor version bump
132+
133+
### Compatibility Testing
134+
135+
Before each release:
136+
137+
1. **Internal Testing**:
138+
- Full test suite must pass
139+
- Integration tests with latest Prometheus server
140+
- (optional) Benchmark comparisons with previous version
141+
> There is no facility for running benchmarks in CI, so this is best-effort.
142+
143+
2. **External Validation**:
144+
145+
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.
146+
147+
- Testing with [prometheus/prometheus](https://github.com/prometheus/prometheus) `main` branch
148+
- Testing with [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) `main` branch
149+
- Breaking changes must be documented in CHANGELOG.md
150+
151+
### Version Policy
152+
153+
- Bug fixes increment patch version (e.g., v0.9.1)
154+
- New features increment minor version (e.g., v0.10.0)
155+
- Breaking changes increment minor version with clear documentation
156+
157+
### Deprecation Policy
158+
159+
1. Features may be deprecated in any minor release
160+
2. Deprecated features:
161+
- Will be documented in CHANGELOG.md
162+
- Will emit warnings when used (when possible)
163+

0 commit comments

Comments
 (0)