docs: add central and caller release flow guide - #289
Conversation
github-actions
Bot
added
the
documentation
Explain the platform release process from end to end for product and engineering readers, including central vs caller workflows and what triggers each step. Signed-off-by: Kyle Vorster <kyle.vorster69@gmail.com>
ec03827 to
b5591ac
Compare
|
Warning Review limit reached
Next review available in: 56 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds a release-management guide documenting the central workflow and thin caller workflow model, its workflow building blocks, release triggers, end-to-end phases, responsibilities, FAQs, glossary, and related documentation. ChangesRelease Flow Documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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 |
Signed-off-by: Kyle Vorster <kyle.vorster69@gmail.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 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 `@Technical/Release-Management/Central-and-Caller-Release-Flow.md`:
- Around line 399-406: Update the “Related technical docs” section to link
directly to the referenced workflow-docs documentation and the historical
Github-Release.md and Jenkins-Release-Builds.md files, using exact repository
paths or URLs so readers can open each document without navigating from
repository roots.
- Around line 275-279: Clarify the “Dependency tip” to distinguish preparation
from execution: dependent release PRs may be prepared before shared libraries
are published, but the libraries’ release PRs must be merged and the libraries
published before dependent release PRs are merged.
- Around line 208-216: Update the “Create GitHub release/tag” step in the
release-flow table and the corresponding Phase 6 section to specify the exact
workflow name, how it is invoked, all required inputs, and the verification gate
confirming every required package and rule-image merge has completed. State that
this gate must pass before the release/tag workflow runs, while preserving the
existing “finally” sequencing.
- Around line 13-20: Clarify the central workflow repository contract throughout
the release-flow guide, especially the introductory model and the sections
around the Phase 1 setup and repository references. Explicitly identify whether
tazama-lf/workflows or frmscoe/workflows is authoritative, describe how changes
are mirrored, and state which repository or tag must be used before release
setup so callers cannot select inconsistent workflow versions.
- Around line 238-240: Update the central workflow release steps to reference a
full commit SHA instead of a mutable tag such as `@v1`, ensuring product
repositories consume an immutable known-good revision. Apply the same change to
the later “stable workflows tag” guidance, or explicitly require tags to be
immutable if tag-based releases remain supported.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 6b7ca93d-5bd1-4e73-ba71-b6edc00f7b49
📒 Files selected for processing (1)
Technical/Release-Management/Central-and-Caller-Release-Flow.md
| The new model works like this: | ||
|
|
||
| 1. **One central place** holds the full release instructions (`workflows` repo). | ||
| 2. Each product repository gets a **thin caller workflow** that invokes that shared instruction. | ||
| 3. Release helpers open **pull requests** for humans to review. | ||
| 4. After those PRs are merged, packages, Docker images, and GitHub releases are created automatically where needed. | ||
|
|
||
| **Important:** Putting new workflows into the central `workflows` repo does **not** release products by itself. It only installs the shared instructions. The actual release wave comes later. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Make the central repository and mirror contract explicit.
The guide says there is “one central place,” but later names both tazama-lf/workflows and frmscoe/workflows, with the latter described as a mirror. Phase 1 does not state which repository is authoritative, how changes are mirrored, or whether both references must be tagged before release setup. Clarify this contract to prevent repositories from using inconsistent workflow versions.
Also applies to: 53-59, 236-243
🤖 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 `@Technical/Release-Management/Central-and-Caller-Release-Flow.md` around lines
13 - 20, Clarify the central workflow repository contract throughout the
release-flow guide, especially the introductory model and the sections around
the Phase 1 setup and repository references. Explicitly identify whether
tazama-lf/workflows or frmscoe/workflows is authoritative, describe how changes
are mirrored, and state which repository or tag must be used before release
setup so callers cannot select inconsistent workflow versions.
| | Step | What starts it | What you see | Human action needed? | | ||
| |------|----------------|--------------|----------------------| | ||
| | Prepare package release | Release automation / manual "run release train" from `dev` | PR `release: vX.Y.Z` | Yes - review and approve | | ||
| | Prepare non-code release | Release automation / manual "run dev-to-main" from `dev` | PR to merge `dev` -> `main` | Yes - review and approve | | ||
| | Publish npm package | Merge of release PR (package files changed on `main`) | Package appears in GitHub Packages | Usually no | | ||
| | Build stable rule Docker image | Push/merge to `main` in a rule repo | Image tags `:X.Y.Z` and `:latest` | Usually no | | ||
| | Build RC rule Docker image | Push to `dev` in a rule repo | Image tags RC version and `:rc` | Usually no | | ||
| | Create GitHub release/tag | Release automation / manual "run release" from `main` | GitHub Release `vX.Y.Z` | Usually no after start | | ||
| | Sync day-to-day CI to rule repos | Changes merged to `dev` in `frmscoe/workflows` | Sync PRs in rule repos | Yes - merge sync PRs | |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift
Specify the exact trigger and preconditions for the final release/tag step.
The table only says “release automation / manual run release from main,” while Phase 6 says the step runs “finally.” Document the workflow name, invocation method, required inputs, and the gate proving that all required package and image merges completed; otherwise operators may create the platform tag before the release wave is complete.
Also applies to: 296-310
🤖 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 `@Technical/Release-Management/Central-and-Caller-Release-Flow.md` around lines
208 - 216, Update the “Create GitHub release/tag” step in the release-flow table
and the corresponding Phase 6 section to specify the exact workflow name, how it
is invoked, all required inputs, and the verification gate confirming every
required package and rule-image merge has completed. State that this gate must
pass before the release/tag workflow runs, while preserving the existing
“finally” sequencing.
| 1. Update the shared workflows in the central `workflows` repository. | ||
| 2. Review and merge that PR into the workflows `dev` branch. | ||
| 3. Tag a stable reference (for example `@v1`) so product repos use a known-good workflow version. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file='Technical/Release-Management/Central-and-Caller-Release-Flow.md'
echo '--- Around lines 220-260 ---'
sed -n '220,260p' "$file"
echo
echo '--- Around lines 338-360 ---'
sed -n '338,360p' "$file"
echo
echo '--- Search for `@v1` / commit SHA / pinned reference mentions ---'
rg -n '`@v1`|commit SHA|SHA|pinned reference|immutable|mutable tag|tag a stable reference' Technical/Release-Management -SRepository: tazama-lf/docs
Length of output: 3573
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file='Technical/Release-Management/Central-and-Caller-Release-Flow.md'
nl -ba "$file" | sed -n '232,244p'
echo '---'
nl -ba "$file" | sed -n '344,354p'
echo '--- hits ---'
rg -n '`@v1`|commit SHA|pinned reference|immutable|stable reference|tag' "$file" -n -SRepository: tazama-lf/docs
Length of output: 192
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file='Technical/Release-Management/Central-and-Caller-Release-Flow.md'
echo '--- Around lines 88-96 ---'
sed -n '88,96p' "$file"
echo
echo '--- Around lines 344-352 ---'
sed -n '344,352p' "$file"
echo
echo '--- All mentions of workflows tag / stable reference / pin callers ---'
rg -n 'stable reference|stable workflows tag|Pin callers|`@v1`|known-good workflow version|pin' "$file" -SRepository: tazama-lf/docs
Length of output: 1406
Use a full commit SHA instead of @v1. Tags can move, so product repos may pick up workflow changes without a caller PR. If tag-based releases are required, make the tag immutable and say so explicitly. Same applies to the later “stable workflows tag” note.
🤖 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 `@Technical/Release-Management/Central-and-Caller-Release-Flow.md` around lines
238 - 240, Update the central workflow release steps to reference a full commit
SHA instead of a mutable tag such as `@v1`, ensuring product repositories consume
an immutable known-good revision. Apply the same change to the later “stable
workflows tag” guidance, or explicitly require tags to be immutable if tag-based
releases remain supported.
| Dependency tip: | ||
|
|
||
| - Publish shared libraries first. | ||
| - Only then release things that depend on those libraries. | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify dependency ordering at merge and publish time.
Phase 3 prepares release PRs before publishing occurs, so “only then release things that depend on those libraries” is ambiguous. State that dependent release PRs may be prepared early, but libraries must be merged and published before dependent PRs are merged.
🤖 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 `@Technical/Release-Management/Central-and-Caller-Release-Flow.md` around lines
275 - 279, Clarify the “Dependency tip” to distinguish preparation from
execution: dependent release PRs may be prepared before shared libraries are
published, but the libraries’ release PRs must be merged and the libraries
published before dependent release PRs are merged.
| ## Related technical docs | ||
|
|
||
| If you need deeper workflow file details, see the `workflow-docs` folder in each org's `workflows` repository: | ||
|
|
||
| - [`tazama-lf/workflows`](https://github.com/tazama-lf/workflows) | ||
| - [`frmscoe/workflows`](https://github.com/frmscoe/workflows) | ||
|
|
||
| Older historical release notes for GitHub/Jenkins still live in this folder (`Github-Release.md`, `Jenkins-Release-Builds.md`). This page describes the newer central/caller platform release model. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Link the referenced technical documents directly.
This section directs readers to the workflow-docs folder and historical release files but only links repository roots. Add direct links or exact paths so readers can reach the referenced documentation without guessing.
🤖 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 `@Technical/Release-Management/Central-and-Caller-Release-Flow.md` around lines
399 - 406, Update the “Related technical docs” section to link directly to the
referenced workflow-docs documentation and the historical Github-Release.md and
Jenkins-Release-Builds.md files, using exact repository paths or URLs so readers
can open each document without navigating from repository roots.
1 participant
Summary
Summary by CodeRabbit