Release process
Audience: whoever is cutting the next tag.
How to run the cut: load the cross-agent skill
.claude/skills/release/SKILL.md(Claude Code / Cursor:/release <version>). The wrapper lives at.claude/commands/release.md, which both harnesses load. This document is the canonical checklist order; the skill is the operational walkthrough and must stay aligned with it.
llmwiki uses semantic versioning. vMAJOR.MINOR.PATCH (e.g. v2.4.0) is the only supported release tag format — there are no prerelease tags, and both release.yml and docker-publish.yml fail fast on a tag that does not match. Every tag is a full GitHub Release.
Minor bumps (X.Y.0) ship when a coherent feature batch lands. Patch bumps (X.Y.Z) ship when a fix cannot wait for the next minor.
Pre-flight
- [ ]
mainis green — recent CI onmainpassed (gh run list --branch main --limit 5) - [ ]
ruff check llmwiki tests scripts - [ ]
python3 -m pytest tests/ -qon a clean checkout (local pass beats CI-only pass) - [ ] No open
priority:criticalbugs (gh issue list --label priority:critical --state open) - [ ] If a leftover gitignored
wiki/exists at the repo root, warn / move it aside before relying on demo self-containment checks — do not delete user data without asking - [ ] Optional when the site changed:
python3 -m llmwiki buildand a quick local click-through for new warnings or broken nav - [ ] Demo corpus before the cut (#225) — default ON: refresh locally and commit before tagging unless the human explicitly opts out this session. Silence means refresh; do not treat “optional” as the default. Incomplete / rate-limited synth is a hard stop — lint/build green and “proceed with delivery” do not waive it; only an explicit opt-out (
skip demo refresh,version-only,ship with unfinished synth) does. Opting out of this committed full regen is separate from the every-six-days Pages-only session freshness job (.github/workflows/demo-session-freshness.yml), which never writes git and never runs synth. - Order: the demo refresh is the last content change before the cut — merge every feature and docs PR first. The session regen records its
--todayindemo/.demo-sessions-date; the demo gate defaults to that date and refuses a different one, so a cut that crosses midnight keeps one release day. - Sessions (no LLM):
python3 scripts/generate_demo_sessions.py --dry-run, then regenerate with a release-day--today(not the frozen2026-08-10anchor). Writes are in-place by slug: raw filenames stick;--todaymovesdate/started/endedinside frontmatter. A source page's name carries the session date, so a real write ends with the offlinemigrate source-page-pathspass overdemo/— re-dated pages move to their new names and links follow; without it the session re-synth skips every re-dated source as already claimed under another name. The same run re-applies#197planted search seeds and rewritestests/fixtures/demo_search_terms.json— do not hand-edit those seeds intodemo/raw/sessions/. - Re-synth: update wiki for changed session filenames and for any docs refresh plan — prefer session sources that moved plus path-scoped
synth --docs-only/refresh_demo.py, not a blind full-vault re-synth of unchanged pages. When the human will run synth (token budget), stop after session regen +refresh_demo.py --dry-runand wait for them; do not spend synthesis tokens without that go-ahead. - Product docs drift:
python3 scripts/refresh_demo.py --dry-run, then a real refresh when the plan is non-empty (needs a synthesis backend; see REFRESH_DEMO.md; use--forcewhendemo/.demo-source-revis missing). The script fails (and does not advance the pin) when plan-added raw docs still lack wiki pages. - Interrupted docs refresh:
python3 scripts/refresh_demo.py --resume(requiresdemo/.demo-refresh-pending, written when remove/add started) synthesizes only the plan-added docs still missing a page (one run), then lints and advances the pin. Never re-run the refresh itself — its removes already ran. Start long synth runs detached with a log outside any session scratchpad so a session exit does not kill them. - Completeness (local):
python3 scripts/refresh_demo.py --verify-slugs <slug>,…for every slug this cut’s plan added must exit 0; regenerated non-headless sessions need matchingdemo/wiki/sources/pages. Do not require clearing the historical vault-wide docs backlog. - Demo-content tests after a refresh:
tests/test_search_acceptance.py::test_mrr_and_rank1_match_baselinecompares againsttests/fixtures/demo_search_baseline.jsonexactly. When a refresh moves it, find out why before re-recording — a drop usually means two pages now share a title (a duplicate raw doc, #298, or a stale page), which is a demo defect to fix, not a new baseline. Re-record only once the change is explained and intended. - Mechanical demo gate (#240): after synth + completeness, run
python3 scripts/release_demo_gate.py(--todaydefaults todemo/.demo-sessions-date). The script first refuses a stale demo — product docs changed sincedemo/.demo-source-rev, or a non-headless session without a source page — then regeneratesdemo/usage/viagenerate_demo_usage.py, builds to/tmp/demo-site(or--out), prints a concretefile://…/index.htmlfor review, runs the demo-content tests (case-fold paths, search baseline, #248, demo integrity, privacy), andllmwiki lint --vault demofailing on errors and warnings. Non-zero exit = hard stop — do not present tag push. Prefer--dry-runfirst when checking the plan. Version-only cuts may pass--skip-usageand--allow-stale-demo. - Local review pause (#240): open the printed
file://URL (Home Timeline, Analytics MCP window, session dates, candidates). Wait for explicit human OK before committing refresheddemo/or the version bump / tag push gate. Lint/gate exit 0 alone is not visual OK. - After visual OK: commit refreshed
demo/before the tag: sessions + wiki (+.demo-source-revwhen written) +demo/usage/+demo/llmwiki-state.json/demo/llmwiki-state.jsso Home Pipeline pending counts stay honest (#255). Spot-check newest session dates underdemo/raw/sessions/. - Human gate before push must state demo synth as
complete,explicitly opted out, orblocked, and (when refresh was ON) that local demo review was OK (do not present a tag push when synth is blocked or review was skipped) - Tag
pages.ymlbuilds and version-asserts the committeddemo/vault (sessions + docs + synth + usage as cut). Between releases,demo-session-freshness.ymlmay redate sessions on a runner frommainand republish Pages only — no git write, no synth/LLM, no docs/usage regen (#213 / #225 / #240)
Bump version
The package version in llmwiki/__init__.py and pyproject.toml must match (test_pyproject_version_matches_package).
- [ ] Update
__version__ = "X.Y.Z"inllmwiki/__init__.py - [ ] Update
version = "X.Y.Z"inpyproject.toml - [ ] Update the version badge in
README.md(keep current badge color/URL style) - [ ] Update the tests badge in
README.mdonly if the passing count changed - [ ] Run
python3 -m llmwiki --versionand confirm it prints the new version - [ ] Confirm version + Theme with the human before committing — send
python3 scripts/release_contents.py's output (Breaking first, then Added / Changed / Fixed / Removed, and what semver implies) with the semver and the repo-precedent version as two choices
Update CHANGELOG and UPGRADING
- [ ] Move every entry from
## [Unreleased]into a new## [X.Y.Z] — YYYY-MM-DDsection - [ ] Re-create an empty
## [Unreleased]scaffold above the new section - [ ] Group entries by
### Added/### Changed/### Fixed/### Removed - [ ] Add a one-line Theme at the top of the release section
- [ ] Rename/compact
docs/UPGRADING.mdheadings that still say Unreleased / in-progress for this cut - [ ] Spot-check every
#Nagainst merged PRs/issues - [ ] Remember
tests/changelog_notes.shipping_section_text— acceptance tests search Unreleased (when non-empty) and all versioned sections; emptying Unreleased is fine as long as shipping bullets remain under the new version section. Do not narrow that helper.
Commit + tag (local only)
git add llmwiki/__init__.py pyproject.toml README.md CHANGELOG.md docs/UPGRADING.md
git commit -m "release(vX.Y.Z): bump version + CHANGELOG"
git tag vX.Y.Z
- [ ] Do not push yet — human gate next
- [ ] Do not force-push
main - [ ] Do not amend the release commit after tagging
Human gate, then push
Direct push of the release commit to main is the maintainer path for a cut (distinct from normal PR flow). Still requires an explicit OK in the session.
- [ ] Show
git show/ version / Theme; wait for explicit approval - [ ] Only then:
git push origin mainandgit push origin vX.Y.Z(or both in one push)
GitHub Release + PyPI (automation)
Pushing the v*.*.* tag triggers .github/workflows/release.yml, which:
- Builds sdist + wheel
- Signs artifacts with Sigstore
- Creates (or updates) the GitHub Release with notes + artifacts — this is the happy path; do not run a second
gh release createunless automation is broken - Publishes to PyPI via OIDC only when repository variable
PYPI_PUBLISHINGistrue(otherwise the publish job is skipped; the GitHub Release still ships) - Runs a post-publish
smokejob that installsllm-wiki-plus==X.Y.Zfrom real PyPI and assertsllmwiki --versionmatches the tag — it also fails the run outright whenpublishwas skipped, so a gate-off tag can't pass quietly
- [ ] Confirm the workflow:
gh run list --workflow=release.yml --limit=3(watch the run for this tag) - [ ] Open the GitHub Release for this repo and confirm title, notes, and assets
- [ ] Confirm the
smokejob went green — it is the check that the tag actually reached users aspip install llm-wiki-plus==X.Y.Z.PYPI_PUBLISHINGis enabled on this repo, so a skippedpublishis no longer normal: it means releases were turned off and the tag shipped nothing to PyPI, whichsmokenow fails on rather than skipping alongside it (seedocs/deploy/pypi-publishing.md) - [ ] Watch CI on the release commit SHA on
main
Manual fallback (only if release.yml is broken):
gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes
Verify Pages deploy (expected, not optional)
The same tag push that triggers release.yml also triggers .github/workflows/pages.yml (#213). The demo site is part of what a release ships — treat a failed or missing Pages run the way you'd treat a failed PyPI upload, not as cosmetic. Skipping this check is how the live demo ended up four releases stale.
- [ ] Confirm the run exists and went green:
gh run list --workflow=pages.yml --limit=3 - [ ] Confirm its post-deploy assert passed — the deploy job fetches
manifest.jsonfrom the live URL and fails when the served version isn't the tagged__version__, so a green run means the site really serves this release - [ ] Spot-check the live demo shows the new version and, unless demo refresh was explicitly skipped, that session dates match what you committed (version-only green is not a content refresh — #225)
- [ ] If the deploy failed, fix
mainfirst and re-run the workflow from Actions → Deploy demo site to GitHub Pages → Run workflow; do not hotfix by rewriting the tag
Two publishers share one GitHub Pages site (#225; see docs/uptime.md and docs/deploy/github-pages.md):
- Release / tag
pages.yml: publishes the committed full demo (sessions + docs + synth + usage). Post-deploy assert: livemanifest.jsonversion matches that tag’s__version__. - Schedule
demo-session-freshness.yml: cron0 4 */6 * *(+workflow_dispatch); checks outmain; offlinegenerate_demo_sessions.py --today(UTC); build + deploy Pages; no git write; no synth/LLM; no docs or usage regen. Post-deploy assert usesmain’s__version__(may be ahead of the last tag until the next cut).
Committed session/docs/usage corpus freshness for the next tag is still the pre-tag maintainer step above (scripts/release_demo_gate.py, #240).
Announce (optional)
- [ ] Post with a link to the GitHub Release page
- [ ] Pin an issue-digest discussion for milestone releases when useful
Rollback
If a release is broken, do not delete the tag. Do:
- Cut a patch release (
vX.Y.Z+1) that reverts the bad change - Mark the broken release superseded in the GitHub Release notes
- Never delete tags — downstream packages may pin to them
- Never force-push
mainto rewrite the cut
Pitfalls (from recent cuts)
| Pitfall | What to do |
|---|---|
Leftover root wiki/ |
Warn / move aside with approval; breaks demo self-containment style checks |
| Shipping without regenerating demo sessions | Default is refresh + commit; skip only on an explicit human opt-out (#225). Tag Pages assert does not rewrite session dates; between-release calendar freshness is the Pages-only schedule from main |
| Emptying Unreleased | Keep shipping bullets under the new version section; rely on shipping_section_text scanning versioned sections |
| Double-creating the GitHub Release | Trust release.yml after the tag push |
| Inventing a tag shape | vMAJOR.MINOR.PATCH only — a suffixed tag is rejected by release.yml and docker-publish.yml |
| Pushing without approval | Human gate is mandatory; no unattended publish |