Repository navigation
docs(release): expand release.md into release-engineer playbook - #2732
Conversation
Adds operational sections under the existing process-design walkthrough: CI phase-by-phase behavior, backport bot mechanics + cherry-pick triage, monotonic-counter migration trap, changelog failure modes + verification, three release-time war stories, pre-release verification checklist, force-retagging discussion + RFC link, bundle-PR splitting strategy. Mermaid diagrams and numbered RC/regular/patch walkthroughs are kept verbatim. Example versions normalized to simple semver-style (v1.2.0, v1.2.1, release-1.2) consistent across the doc. Assisted-By: Claude <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
github-actions
Bot
added
area/release
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the project's release documentation by transforming the existing release workflow document into a robust operational playbook. By centralizing CI workflow explanations, backporting procedures, and historical incident data, the update provides release engineers with the necessary context and tools to manage releases more reliably and effectively. Highlights
New Features🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on Gemini (@gemini-code-assist) comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
📝 WalkthroughWalkthroughThis PR updates ChangesRelease Process Documentation Refresh
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates docs/release.md to provide a comprehensive release workflow guide, detailing CI phases, automated patch tags, backports, changelogs, and pre-release verification checklists. The review feedback identifies several issues in the documented shell commands and scripts: a grep command needs to filter out external repository references to prevent validation errors, a kubectl apply command is missing -f - to read from standard input, a git push -f command should explicitly specify the remote and tag to avoid force-pushing the current branch, and a curl command should include the -L flag to follow redirects during URL liveness checks.
| git diff --name-only $PREV..$NEW -- 'images/*/Dockerfile' | ||
|
|
||
| # C. Every cited #NNNN exists and is a merged PR (not an issue) | ||
| grep -oE '#[0-9]+' docs/changelogs/$NEW.md | sort -u | sed 's/#//' | xargs -P 20 -I{} sh -c ' |
There was a problem hiding this comment.
The grep -oE '#[0-9]+' command extracts all PR/issue numbers from the changelog. However, this also matches external repository references like cozystack/website#456, extracting #456 and incorrectly querying it against the main cozystack/cozystack repository. This leads to false positives or validation errors during the release check.
Filtering out cozystack/website# references before running grep resolves this issue.
| grep -oE '#[0-9]+' docs/changelogs/$NEW.md | sort -u | sed 's/#//' | xargs -P 20 -I{} sh -c ' | |
| sed 's|cozystack/website#[0-9]*||g' docs/changelogs/$NEW.md | grep -oE '#[0-9]+' | sort -u | sed 's/#//' | xargs -P 20 -I{} sh -c ' |
| - [ ] **Upgrade from previous minor** (`v(X-1).Y.0`) for RC and minor releases. Same assertions. | ||
| - [ ] **At least one tenant with `publishing.ingressName != tenant-root`** and a real Let's Encrypt-staging cert issuance. | ||
| - [ ] **Apply-mutate-reapply** on the kubernetes umbrella HelmRelease (catches second-reconcile bugs). | ||
| - [ ] **For every CRD-source bump** (kubevirt, cert-manager, flux, cilium, kamaji): `helm template | kubectl apply --dry-run=server` against the freshly-installed CRDs. |
There was a problem hiding this comment.
The kubectl apply --dry-run=server command is missing the -f - argument to read the template from standard input (piped from helm template). Without it, the command will fail with an error indicating that no file or directory was specified.
It should be:
helm template | kubectl apply --dry-run=server -f -
|
|
||
| Fires on merge of a PR with the `release` label and head branch matching `release-X.Y.Z[-suffix]`. Three steps: | ||
|
|
||
| 1. **Force-move the tag** to the merge commit (`git tag -f <vX.Y.Z> <github.sha> && git push -f`). Intentional and load-bearing for the digest-bake flow — see [Force-retagging](#force-retagging). |
There was a problem hiding this comment.
The command git push -f without specifying the remote and tag name might fail or force-push the current branch instead of the tag, depending on the user's local git configuration (e.g., push.default).
Specifying the remote and tag explicitly is safer and more robust:
git push origin -f <vX.Y.Z>
|
|
||
| # D. URL liveness | ||
| grep -oE 'https://[^)" ]+' docs/changelogs/$NEW.md | sort -u | xargs -P 10 -I{} sh -c ' | ||
| code=$(curl -s -o /dev/null -w "%{http_code}" {}) |
There was a problem hiding this comment.
The curl command used to check URL liveness does not follow redirects by default. Since some valid URLs (such as cozystack.io paths or external documentation links) may redirect (e.g., from HTTP to HTTPS or due to path normalization), they will return a 3xx status code instead of 200 and be falsely flagged as broken.
Adding the -L (or --location) flag to curl ensures that redirects are followed and only truly broken links are reported.
| code=$(curl -s -o /dev/null -w "%{http_code}" {}) | |
| code=$(curl -sL -o /dev/null -w "%{http_code}" {}) |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/release.md`:
- Line 125: Fix the typo in the branch name shown as `release-1.2,` by removing
the trailing comma so it reads `release-1.2`; update the text where the branch
name appears (the backticked literal `release-1.2,`) to the corrected
`release-1.2` to prevent copy/paste errors during release prep.
- Around line 240-241: Update the release docs to state that the maintenance
branch named release-X.Y is force-updated unconditionally to the tag commit when
it already exists (rather than “if newer”) so the documented behavior matches
the workflow: replace the phrase “force-updated if newer” with language that the
workflow will force-update the existing release-X.Y branch to point to the tag
commit every run, and mention the exact branch name pattern (`release-X.Y`) and
the unconditional force-update to the tag commit to avoid operator confusion
during triage.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: f27052c3-7188-4694-a6d6-20f04df6c981
📒 Files selected for processing (1)
docs/release.md
|
|
||
| 1. The maintainer creates a release branch, `release-0.42,` and cherry-picks patch commits from `main` to `release-0.42`. | ||
| These must be only patches to features that were present in version `v0.42.0`. | ||
| 1. The maintainer creates a release branch, `release-1.2,` and cherry-picks patch commits from `main` to `release-1.2`. |
There was a problem hiding this comment.
Fix branch name typo in patch workflow step.
release-1.2, includes a trailing comma inside the branch name and can cause copy/paste mistakes during release prep.
Suggested edit
-1. The maintainer creates a release branch, `release-1.2,` and cherry-picks patch commits from `main` to `release-1.2`.
+1. The maintainer creates a release branch, `release-1.2`, and cherry-picks patch commits from `main` to `release-1.2`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 1. The maintainer creates a release branch, `release-1.2,` and cherry-picks patch commits from `main` to `release-1.2`. | |
| 1. The maintainer creates a release branch, `release-1.2`, and cherry-picks patch commits from `main` to `release-1.2`. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/release.md` at line 125, Fix the typo in the branch name shown as
`release-1.2,` by removing the trailing comma so it reads `release-1.2`; update
the text where the branch name appears (the backticked literal `release-1.2,`)
to the corrected `release-1.2` to prevent copy/paste errors during release prep.
| 2. **Ensure the maintenance branch `release-X.Y` exists** at the tag commit. Created if missing, force-updated if newer. | ||
| 3. **Publish the draft release.** `make_latest` is computed against published-non-prerelease tags: prereleases stay `false`; tags older than the current max stay `false` (and the current max is force-restored to `latest` if necessary, so an older patch tag cut after a newer minor won't downgrade `latest`). |
There was a problem hiding this comment.
Correct maintenance-branch update semantics to match workflow behavior.
The docs say release-X.Y is force-updated “if newer,” but the workflow force-updates unconditionally to the tag commit when the branch exists. This should be documented precisely to avoid wrong operator assumptions during release triage.
Suggested edit
-2. **Ensure the maintenance branch `release-X.Y` exists** at the tag commit. Created if missing, force-updated if newer.
+2. **Ensure the maintenance branch `release-X.Y` exists** at the tag commit. Created if missing; if it already exists, it is force-updated to the tag commit.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 2. **Ensure the maintenance branch `release-X.Y` exists** at the tag commit. Created if missing, force-updated if newer. | |
| 3. **Publish the draft release.** `make_latest` is computed against published-non-prerelease tags: prereleases stay `false`; tags older than the current max stay `false` (and the current max is force-restored to `latest` if necessary, so an older patch tag cut after a newer minor won't downgrade `latest`). | |
| 2. **Ensure the maintenance branch `release-X.Y` exists** at the tag commit. Created if missing; if it already exists, it is force-updated to the tag commit. | |
| 3. **Publish the draft release.** `make_latest` is computed against published-non-prerelease tags: prereleases stay `false`; tags older than the current max stay `false` (and the current max is force-restored to `latest` if necessary, so an older patch tag cut after a newer minor won't downgrade `latest`). |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/release.md` around lines 240 - 241, Update the release docs to state
that the maintenance branch named release-X.Y is force-updated unconditionally
to the tag commit when it already exists (rather than “if newer”) so the
documented behavior matches the workflow: replace the phrase “force-updated if
newer” with language that the workflow will force-update the existing
release-X.Y branch to point to the tag commit every run, and mention the exact
branch name pattern (`release-X.Y`) and the unconditional force-update to the
tag commit to avoid operator confusion during triage.
Aleksei Sviridkin (lexfrei)
left a comment
Aleksei Sviridkin (lexfrei)
left a comment
There was a problem hiding this comment.
LGTM — large, well-organized expansion of the release doc into an operational playbook; the process description and walkthroughs are accurate. A few embedded copy-paste commands have minor bugs worth fixing, but they are docs-only and do not affect the repo.
Business context: docs/release.md was a process-design doc with no operational runbook; this adds the phase-by-phase CI walk-through, backport mechanics, changelog verification, real release-time regressions, and a pre-release checklist.
Non-blocking follow-ups (snippet hygiene — a release engineer runs these verbatim):
- The CRD checklist item
helm template | kubectl apply --dry-run=serverneeds-f -; without itkubectl applyerrors with "must specify one of -f and -k" instead of reading stdin. - The URL-liveness check
curl -s -o /dev/null -w "%{http_code}"does not pass-L, so any 301/302 redirect (common on docs hosts) reports as non-200 and yields false "broken URL" hits — add-L. - The
#NNNNsweepgrep -oE '#[0-9]+'also matches numbers inside code blocks and URLs in the changelog; harmless (extra refs resolve toISSUE/null), but a tighter match gives a cleaner list. - The branch-name and
git push -fsnippets flagged on the thread are worth the same copy-paste-correctness pass.
2 participants
What this PR does
Expands
docs/release.mdfrom a ~165-line process-design doc into a ~573-line single source covering both the process design (kept verbatim — mermaid diagrams and the RC/regular/patch numbered walkthroughs) and the operational playbook for cutting a release.New sections added under the existing diagrams:
tags.yaml(prepare-release,generate-changelog,update-website-docs),pull-requests-release.yaml(finalize), andupdate-releasenotes.yaml(sync release body).auto-release.yaml's nightly behavior.agents/changelog.mdplus the recurring failure modes that have shipped in real changelogs, with a verification snippet (chart-bump coverage, range-vs-changelog PR sweep, URL liveness, website PR-author check).Example version numbers across the walkthrough switched from the upstream
v0.42.xlegacy placeholders to simple semver-style (v1.2.0,v1.2.1,release-1.2) consistent with semver.org examples and applicable at any point in v1.x.Release note
Summary by CodeRabbit