docs: describe the charm release and promotion process - #345
Draft
cbartz wants to merge 2 commits into
Draft
Conversation
cbartz
force-pushed
the
docs/release-process
branch
from
September 1, 2026 13:11
bcc8044 to
a8a56e2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Adds
docs/explanation/charm-release-and-promotion.md, an explanation page covering how theGitHub runner charms move through
latest/edge→latest/candidate→latest/stable:the channel flow and what each workflow does, the two human gates and what a reviewer is
expected to check at each, the one-off
charmhub-stableenvironment setup, and the manualhotfix and rollback paths.
Also links it from
docs/explanation/index.rst(which had no toctree) and adds a changelogentry.
Why we need it
Part of ISD-5877, and the last PR of that series — it documents what actually shipped. The
promotion automation has two decisions that are deliberately left to a human, and neither is
self-explanatory from the workflow files alone.
Checklist
CONTRIBUTING.mdhas been updated upon changes to the contribution/development process (e.g. changes to the way tests are run)docs/changelog.mdwith user-relevant changesterraform fmtpasses andtflintreports no errorsAGENTS.md.copilot-collections.yamlor.github/instructions/: I re-checked whether theAGENTS.md"12-factor divergences" guidance still matches the upstream copilot-collections guidanceThe technical-author box is ticked as a request rather than a fact — this is a documentation
change and needs one. Everything else is not applicable: documentation only, no code, tests,
Terraform, Rockcraft or tooling changes.
Test plan
make -C docs spellcheck(Vale,Canonical.000-US-spellcheckat error level, which iswhat CI runs) → 0 errors, 0 warnings, 0 suggestions in 16 files. No new entries in
docs/.custom_wordlist.txtwere needed.make -C docs html→ build succeeded, with no orphan-page or toctree warnings, so thenew page is genuinely reachable from the tree rather than merely present.
sphinxcontrib.mermaid, which is already indocs/conf.pyanddocs/requirements.txtand already used bydocs/reference/architecture.Review focus
promote_edge_to_candidate.yamland
promote_candidate_to_stable.yaml, which arrive in feat(ci): add the daily edge-to-candidate promotion workflow #343 and feat(ci): add the weekly candidate-to-stable promotion workflow #344. Merged early, thepage documents workflows that do not exist yet.
latest/candidateback atan older revision without first disabling the daily workflow does not work — the next run
sees edge ahead of candidate and repromotes straight over the rollback. The page leads with
that and gives the ordered sequence.
charmhub-stablesetup section describes a step nobody has performed yet. Theenvironment does not exist, and until it does the stable approval gate is silently a no-op.
how the team actually intends to operate, particularly the stable gate: the page states
plainly that the Charmhub timestamp does not prove production ran the revision and that
confirming it is the reviewer's job.