Skip to content

docs: describe the charm release and promotion process - #345

Draft
cbartz wants to merge 2 commits into
mainfrom
docs/release-process
Draft

docs: describe the charm release and promotion process#345
cbartz wants to merge 2 commits into
mainfrom
docs/release-process

Conversation

@cbartz

@cbartz cbartz commented Aug 31, 2026

Copy link
Copy Markdown
Collaborator

What this PR does

Adds docs/explanation/charm-release-and-promotion.md, an explanation page covering how the
GitHub runner charms move through latest/edgelatest/candidatelatest/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-stable environment setup, and the manual
hotfix and rollback paths.

Also links it from docs/explanation/index.rst (which had no toctree) and adds a changelog
entry.

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

  • Changes comply with the project's coding standards and guidelines (see CONTRIBUTING.md and STYLE.md)
  • CONTRIBUTING.md has been updated upon changes to the contribution/development process (e.g. changes to the way tests are run)
  • Technical author has been assigned to review the PR in case of documentation changes (usually *.md files)
  • I updated docs/changelog.md with user-relevant changes
  • I used AI to assist with preparing this PR
  • I added or updated tests as needed (unit and integration)
  • If integration test modules are used: I updated the workflow configuration
  • If this PR involves a Grafana dashboard: I added a screenshot of the dashboard
  • If this PR involves Terraform: terraform fmt passes and tflint reports no errors
  • If this PR involves Rockcraft: I updated the version
  • If this PR adds/removes a charm, or changes a charm's base class, conventions, tooling, or repo structure: I updated the relevant AGENTS.md
  • If this PR changes .copilot-collections.yaml or .github/instructions/: I re-checked whether the AGENTS.md "12-factor divergences" guidance still matches the upstream copilot-collections guidance

The 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-spellcheck at error level, which is
    what CI runs) → 0 errors, 0 warnings, 0 suggestions in 16 files. No new entries in
    docs/.custom_wordlist.txt were needed.
  • make -C docs htmlbuild succeeded, with no orphan-page or toctree warnings, so the
    new page is genuinely reachable from the tree rather than merely present.
  • The Mermaid diagram uses sphinxcontrib.mermaid, which is already in docs/conf.py and
    docs/requirements.txt and already used by docs/reference/architecture.

Review focus

  • This PR should merge last in the series. It describes promote_edge_to_candidate.yaml
    and 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, the
    page documents workflows that do not exist yet.
  • The rollback caveat is the part most worth checking. Pointing latest/candidate back at
    an 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.
  • The charmhub-stable setup section describes a step nobody has performed yet. The
    environment does not exist, and until it does the stable approval gate is silently a no-op.
  • The description of what each gate's reviewer is responsible for should be checked against
    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.

@cbartz
cbartz force-pushed the docs/release-process branch from bcc8044 to a8a56e2 Compare September 1, 2026 13:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant