Skip to content

Commit abf357c

Browse files
kakkoyunkakkoyun
committed
docs: Add RELEASE.md for the release process
docs: update README for version compatibility Signed-off-by: Kemal Akkoyun <[email protected]>
1 parent 291b0b0 commit abf357c

File tree

2 files changed

+158
-23
lines changed

2 files changed

+158
-23
lines changed

‎README.md‎

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

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

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

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

‎RELEASE.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Release
2+
3+
The Prometheus Go client library follows a release process similar to the [Prometheus server](https://github.com/prometheus/prometheus/blob/main/RELEASE.md).
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 latest release branch, then merge to main
12+
- Features and changes go to main branch
13+
- Older release branches maintained on best-effort basis
14+
15+
## Pre-Release Preparations
16+
17+
1. Review main branch state:
18+
- Expedite critical bug fixes
19+
- Hold back risky changes
20+
- Update dependencies via Dependabot PRs
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 feature branch:
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+
- Order: [SECURITY], [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX]
42+
- For RCs, append `-rc.0`
43+
44+
4. Create PR and get review
45+
46+
5. After merge, create tags:
47+
48+
```bash
49+
tag="v$(< VERSION)"
50+
git tag -s "${tag}" -m "${tag}"
51+
git push origin "${tag}"
52+
```
53+
54+
6. For Release Candidates:
55+
- Create PR against prometheus/prometheus using RC version
56+
- Create PR against kubernetes/kubernetes using RC version
57+
- Make sure the CI is green for the PRs
58+
- Allow 1-2 days for downstream testing
59+
- Fix any issues found before final release
60+
- Use `-rc.1`, `-rc.2` etc. for additional fixes
61+
62+
7. For Final Release:
63+
- Wait for CI completion
64+
- Verify artifacts published
65+
- Click "Publish release"
66+
- For RCs, ensure "pre-release" box is checked
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+
- Cherry-pick from main: `git cherry-pick <commit>`
90+
- Or add new fix commits
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+
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.
106+
107+
## Compatibility Guarantees
108+
109+
### Supported Go Versions
110+
111+
- Support provided only for the three most recent major Go releases
112+
- While the library may work with older versions, no fixes or support provided
113+
- Each release documents the minimum required Go version
114+
115+
### API Stability
116+
117+
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):
118+
119+
- API signatures may change between minor versions
120+
- Types may be modified or relocated
121+
- Default behaviors might be altered
122+
- Feature removal/deprecation can occur with minor version bump
123+
124+
### Compatibility Testing
125+
126+
Before each release:
127+
128+
1. **Internal Testing**:
129+
- Full test suite must pass
130+
- Integration tests with latest Prometheus server
131+
- Benchmark comparisons with previous version
132+
133+
2. **External Validation**:
134+
- Testing with prometheus/prometheus master branch
135+
- Testing with kubernetes/kubernetes master branch
136+
- Breaking changes must be documented in CHANGELOG.md
137+
138+
### Version Policy
139+
140+
- Bug fixes increment patch version (e.g., v0.9.1)
141+
- New features increment minor version (e.g., v0.10.0)
142+
- Breaking changes increment minor version with clear documentation
143+
- Major version remains at 0 to indicate potential instability
144+
145+
### Deprecation Policy
146+
147+
1. Features may be deprecated in any minor release
148+
2. Deprecated features:
149+
- Will be documented in CHANGELOG.md
150+
- Will emit warnings when used (when possible)
151+
- May be removed in next minor version
152+
- Must have migration path documented

0 commit comments

Comments
 (0)