Skip to content

Commit e82058b

Browse files
belyaev-devbelyaev-dev
committed
docs: add release guide
1 parent 59c0ab7 commit e82058b

4 files changed

Lines changed: 137 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,7 @@ The CI upload examples under [examples/ci/](examples/ci/) are meant for downstre
225225
- [docs/architecture.md](docs/architecture.md) — runtime topology, request/data flow, storage layout, and observability surfaces
226226
- [docs/configuration.md](docs/configuration.md) — full `TESTIMONY_*` configuration reference
227227
- [docs/github-repository.md](docs/github-repository.md) — repository-level GitHub CI, release, and metadata baseline
228+
- [docs/release-guide.md](docs/release-guide.md) — current manual release process and future automation target
228229
- [CONTRIBUTING.md](CONTRIBUTING.md) — contributor workflow, verification commands, and PR expectations
229230
- [examples/ci/](examples/ci/) — GitHub Actions and GitLab CI upload examples
230231
- [LICENSE](LICENSE) — Apache-2.0 license

‎docs/github-repository.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Once those are stable, the next GitHub automation step should be a tag-based rel
4646
2. publishes the container image to GHCR
4747
3. attaches release notes and checksums to a GitHub Release
4848

49-
Until then, CI is mandatory; release automation is intentionally deferred.
49+
Until then, CI is mandatory; release automation is intentionally deferred. The current manual release path is documented in [docs/release-guide.md](release-guide.md).
5050

5151
## Suggested GitHub repository metadata
5252

‎docs/release-guide.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Release guide
2+
3+
This repository does **not** have tag-driven release automation yet.
4+
5+
Until a dedicated release workflow exists, releases should stay explicit and manual so the tag, notes, and distribution story do not drift away from the repository reality.
6+
7+
## Current release policy
8+
9+
- CI is required on pull requests and on `main`.
10+
- Release automation is intentionally deferred.
11+
- A release should only be cut from `main` after the verification surface below passes.
12+
- GitHub Releases, tags, and any future container publication should follow one documented version for the repository.
13+
14+
## What counts as release-ready
15+
16+
Before creating a version tag, run the repository-owned verification commands from a clean checkout:
17+
18+
```bash
19+
go test ./... -p 1
20+
bash scripts/verify-docs-and-ci.sh
21+
bash scripts/verify-helm-chart.sh
22+
bash scripts/verify-compose-e2e.sh
23+
```
24+
25+
A release is not ready if any of these fail.
26+
27+
## Versioning and tagging
28+
29+
Until the project adopts a different rule, use semantic version tags:
30+
31+
- `v0.1.0`
32+
- `v0.2.0`
33+
- `v1.0.0`
34+
35+
Guidance:
36+
37+
- bump **patch** for fixes and non-breaking packaging/doc corrections
38+
- bump **minor** for backward-compatible features
39+
- bump **major** for breaking API, config, or deployment changes
40+
41+
Create annotated tags, not lightweight tags.
42+
43+
## Manual release flow
44+
45+
### 1. Confirm `main` is the exact release commit
46+
47+
Make sure the release commit is already merged to `main` and that local `main` matches the remote.
48+
49+
```bash
50+
git checkout main
51+
git pull --ff-only origin main
52+
```
53+
54+
### 2. Run the release verification suite
55+
56+
```bash
57+
go test ./... -p 1
58+
bash scripts/verify-docs-and-ci.sh
59+
bash scripts/verify-helm-chart.sh
60+
bash scripts/verify-compose-e2e.sh
61+
```
62+
63+
### 3. Create the annotated tag
64+
65+
Replace `vX.Y.Z` with the version you are releasing.
66+
67+
```bash
68+
git tag -a vX.Y.Z -m "vX.Y.Z"
69+
```
70+
71+
### 4. Push the tag
72+
73+
```bash
74+
git push origin vX.Y.Z
75+
```
76+
77+
### 5. Create the GitHub Release entry
78+
79+
Create a GitHub Release from the pushed tag and include:
80+
81+
- a short summary of what changed
82+
- notable operator-facing changes
83+
- breaking changes or migration notes, if any
84+
- verification commands used for the release
85+
86+
Until automation exists, this step is manual.
87+
88+
## Release notes template
89+
90+
Use this structure for the GitHub Release body:
91+
92+
```markdown
93+
## Summary
94+
- <one-line release summary>
95+
96+
## What changed
97+
- <change 1>
98+
- <change 2>
99+
100+
## Operator impact
101+
- <deployment/config/runtime note>
102+
103+
## Verification
104+
- `go test ./... -p 1`
105+
- `bash scripts/verify-docs-and-ci.sh`
106+
- `bash scripts/verify-helm-chart.sh`
107+
- `bash scripts/verify-compose-e2e.sh`
108+
109+
## Breaking changes
110+
- None.
111+
```
112+
113+
## Future automation target
114+
115+
When repository metadata, versioning expectations, and distribution targets are stable, replace the manual path above with a tag-triggered release workflow that:
116+
117+
1. re-runs the release verification gates
118+
2. builds the release binary
119+
3. publishes the container image to GHCR, if that remains the chosen distribution path
120+
4. creates the GitHub Release with generated notes plus checksums/assets
121+
122+
Until then, keep the release path simple, observable, and manual.

‎scripts/verify-docs-and-ci.sh‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ CI_README_FILE="$ROOT_DIR/examples/ci/README.md"
1010
GITHUB_CI_FILE="$ROOT_DIR/examples/ci/github-actions-upload.yml"
1111
GITLAB_CI_FILE="$ROOT_DIR/examples/ci/gitlab-ci-upload.yml"
1212
GITHUB_REPOSITORY_GUIDE_FILE="$ROOT_DIR/docs/github-repository.md"
13+
RELEASE_GUIDE_FILE="$ROOT_DIR/docs/release-guide.md"
1314
GITHUB_WORKFLOW_CI_FILE="$ROOT_DIR/.github/workflows/ci.yml"
1415
GITHUB_WORKFLOW_COMPOSE_FILE="$ROOT_DIR/.github/workflows/compose-smoke.yml"
1516

@@ -51,6 +52,7 @@ assert_repo_has_no_placeholders() {
5152
"$ARCHITECTURE_FILE" \
5253
"$CONFIG_FILE" \
5354
"$GITHUB_REPOSITORY_GUIDE_FILE" \
55+
"$RELEASE_GUIDE_FILE" \
5456
"$ROOT_DIR/examples/ci" \
5557
"$ROOT_DIR/.github/workflows"; then
5658
echo 'found TODO/TBD placeholder text in docs or CI examples' >&2
@@ -80,6 +82,7 @@ main() {
8082
assert_non_empty_file "$GITHUB_CI_FILE"
8183
assert_non_empty_file "$GITLAB_CI_FILE"
8284
assert_non_empty_file "$GITHUB_REPOSITORY_GUIDE_FILE"
85+
assert_non_empty_file "$RELEASE_GUIDE_FILE"
8386
assert_non_empty_file "$GITHUB_WORKFLOW_CI_FILE"
8487
assert_non_empty_file "$GITHUB_WORKFLOW_COMPOSE_FILE"
8588

@@ -99,6 +102,7 @@ main() {
99102
assert_file_contains "$README_FILE" '[docs/configuration.md](docs/configuration.md)' 'README should link to the configuration guide'
100103
assert_file_contains "$README_FILE" '## GitHub repository baseline' 'README should explain the repository-level GitHub baseline'
101104
assert_file_contains "$README_FILE" '[docs/github-repository.md](docs/github-repository.md)' 'README should link to the GitHub repository guide'
105+
assert_file_contains "$README_FILE" '[docs/release-guide.md](docs/release-guide.md)' 'README should link to the release guide'
102106
assert_file_contains "$README_FILE" '[CONTRIBUTING.md](CONTRIBUTING.md)' 'README should link to CONTRIBUTING.md'
103107
assert_file_contains "$README_FILE" '[examples/ci/](examples/ci/)' 'README should link to the CI examples directory'
104108

@@ -127,6 +131,15 @@ main() {
127131
assert_file_contains "$GITHUB_REPOSITORY_GUIDE_FILE" '.github/workflows/compose-smoke.yml' 'GitHub repository guide should reference the Compose smoke workflow'
128132
assert_file_contains "$GITHUB_REPOSITORY_GUIDE_FILE" 'Do **not** add a full release workflow yet.' 'GitHub repository guide should document the deferred release stance'
129133
assert_file_contains "$GITHUB_REPOSITORY_GUIDE_FILE" 'Single-binary service for publishing Allure reports without turning your CI runner into a report host.' 'GitHub repository guide should include the proposed repository description'
134+
assert_file_contains "$GITHUB_REPOSITORY_GUIDE_FILE" '[docs/release-guide.md](release-guide.md)' 'GitHub repository guide should link to the release guide'
135+
136+
log "checking release guide"
137+
assert_file_contains "$RELEASE_GUIDE_FILE" '## Current release policy' 'Release guide should explain the current release policy'
138+
assert_file_contains "$RELEASE_GUIDE_FILE" 'go test ./... -p 1' 'Release guide should require the Go test suite'
139+
assert_file_contains "$RELEASE_GUIDE_FILE" 'bash scripts/verify-docs-and-ci.sh' 'Release guide should require docs verification'
140+
assert_file_contains "$RELEASE_GUIDE_FILE" 'bash scripts/verify-helm-chart.sh' 'Release guide should require Helm verification'
141+
assert_file_contains "$RELEASE_GUIDE_FILE" 'bash scripts/verify-compose-e2e.sh' 'Release guide should require Compose verification'
142+
assert_file_contains "$RELEASE_GUIDE_FILE" 'git tag -a vX.Y.Z -m "vX.Y.Z"' 'Release guide should document annotated tag creation'
130143

131144
log "parsing CI example and workflow YAML"
132145
parse_ci_yaml

0 commit comments

Comments
 (0)