Cuts a full shiki release (bump to the next version, CHANGELOG, docs site, image/video scripts, CI through GitHub Release, every store, and the marketing site) end-to-end. Use when the user says "publica", "haz el release", "cut a release", "release vX.Y.Z", "bump a X.Y.Z", "sube la version", "deploy", "publish", or invokes /deploy. Encodes the three non-obvious manual fallbacks discovered on the v0.9.1 cut (release.yml not auto-triggering, Homebrew tap 403, screenshots/release-pages jobs skipped) so a release never silently half-publishes.
Cuts a full shiki release (bump to the next version, CHANGELOG, docs site, image/video scripts, CI through GitHub Release, every store, and the marketing site) end-to-end. Use when the user says "publica", "haz el release", "cut a release", "release vX.Y.Z", "bump a X.Y.Z", "sube la version", "deploy", "publish", or invokes /deploy. Encodes the three non-obvious manual fallbacks discovered on the v0.9.1 cut (release.yml not auto-triggering, Homebrew tap 403, screenshots/release-pages jobs skipped) so a release never silently half-publishes.
Shiki release runbook (verified on v0.9.1)
The complete flow for publishing a shiki release, in order. Every command below was exercised for
the v0.9.1 cut. Do the steps in sequence and verify each checkpoint before moving on. The three
fallbacks in Phase 6–8 are part of the real flow, not exceptional edge cases.
Phase 0 — preflight
Working tree clean, on main, up to date: git status --short, git log --oneline -3.
Know the target version (next patch/minor from [workspace.package] version in root
Cargo.toml). Default: next patch (0.9.1 → 0.9.2).
Enumerate what's changed since the last tag:
git log --oneline <last-tag>..main (e.g. git log --oneline v0.9.1..main).
Phase 1 — CHANGELOG
Audit the ## [Unreleased] section against the commits in Phase 0: every user-facing change
needs a bullet, and every bullet should trace to real code. If unsure, run the
docs-coherence skill first — its report flags exactly the missing entries (this caught the
bold/italic slash commands, theme-adaptive syntax colors, preview-scroll fix, and autocrlf
fix missing from the v0.9.1 notes).
Rename ## [Unreleased] to ## [<version>] - <YYYY-MM-DD> (today's date), and re-add an
empty ## [Unreleased] header at the top of the changelog (Keep a Changelog convention).
Phase 2 — version bump
Root Cargo.toml: [workspace.package] version = "X.Y.Z".
Root Cargo.toml: the three [workspace.dependencies]shiki-core/shiki-config/
shiki-tuiversion = "X.Y.Z" (plain sed -i 's/version = "OLD"/version = "NEW"/' Cargo.toml
covers all four in one shot). Cargo.lock picks them up on the next cargo check.
docs/index.html: the hardcoded JSON-LD "softwareVersion": "X.Y.Z" (the nav version pill
and download button are fetched live; this one is not — bump by hand).
Phase 3 — docs site + config prose
If a doc-audit found drift, fix the flagged files. Known hotspot from v0.9.1: the built-in
/-menu command count and list appear in four places and all must stay in sync —
docs/documentation.html (the 19 built-in commands prose + the sample config block),
IDEA.md (same two spots), and shiki-config/src/config.rs (section_comment for
[snippets]). When slash_menu.rs::builtins() changes, update all of them (and the count).
If config.rs gained a [general]/other field, add it to that table's section_comment
block (a fresh shiki config run surfaces exactly which keys the prose omits).
Phase 4 — image/video scripts
If this release's headline features are visual (PREVIEW rendering, new editor UX, new
modals), showcase them:
scripts/screenshots.sh: add a sample note in setup_sample_data + a shot "NN-…" capture
in the wide branch (same title-jump pattern as the existing shots), so the marketing
screenshots don't go stale.
scripts/demo-gif.sh: add a note in setup_sample_data (put it in research/ — the flat,
index-independent notebook — never in personal/ where hardcoded phase indices live) + a new
Phase block before the quit, using a unique fuzzy-search query that matches only that note
(see the "rollup" comment on Phase 20 for why "release day" was wrong).
bash -n both scripts. If local tooling is available (vhs, xterm, xdotool, Xvfb, ffmpeg,
ttyd, a Nerd Font), do a real smoke test: run scripts/demo-gif.sh /tmp/test.gif and a
single-theme screenshot run before committing.
Commit with [PUBLISH] anywhere in the message (this is what auto-tag watches for),
conventional style: chore: cut release for vX.Y.Z [PUBLISH]. Push to main.
Watch Auto Tag on Publish run to completion (it reads the version from Cargo.toml and
pushes the vX.Y.Z tag via RELEASE_TAG_PAT).
Phase 6 — make sure release.yml actually runs ⚠️
The tag push often does not trigger release.yml (confirmed on v0.8.4 and v0.9.1). Check:
gh run list --limit 8
If a Release run appears (event push or workflow_dispatch) within ~1–2 min after
auto-tag finishes, monitor it (gh run watch <id>).
If no Release run appears, dispatch it manually — this is the documented fallback:
gh workflow run release.yml --ref main --field tag=vX.Y.Z. The resolve-tag job makes this
equivalent to a real tag push.
Phase 7 — monitor release.yml
Jobs run in this order (some in parallel): resolve-tag → 4× build → release (creates the
GitHub Release + assets) → publish-crates + update-packaging-manifests (parallel) →
update-screenshots → update-release-pages.
release completes → the GitHub Release with 4 assets + SHA256SUMS.txt exists.
publish-crates → all 4 crates (shiki-core → shiki-config → shiki-tui → shiki-cli)
land on crates.io (verify each: curl -s -H "User-Agent: …" https://crates.io/api/v1/crates/<crate>).
update-packaging-manifests:
Scoop manifests (both bucket/shiki.json and packaging/scoop/shiki.json) updated + committed
to main (they must stay byte-identical — cmp them).
AUR: packaging/aur (shiki-bin) and packaging/aur-src (shiki) PKGBUILDs + .SRCINFO updated,
and pushed to the AUR repos themselves.
Homebrew tap push — see the ⚠️ below.
⚠️ Homebrew tap 403 (expected to fail on v0.9.1-era PAT)
Push Homebrew tap step fails with Permission to sazardev/homebrew-shiki.git denied when
RELEASE_TAG_PAT can't write to the tap repo. This fails the whole job after everything else
in it succeeded. Do the tap push manually:
Verify afterwards that version "X.Y.Z" and both sha256s in the formula match the release's
SHA256SUMS.txt.
Phase 8 — skipped jobs need local runs ⚠️
Because update-screenshots and update-release-pages are needs:-gated on
update-packaging-manifests, when that job fails at the Homebrew step they are skipped, leaving
the site stale. Replicate them locally:
Regenerate everything:
bash scripts/screenshots.sh (needs xterm/ImageMagick/xdotool/Xvfb/pngquant + Nerd Font),
bash scripts/demo-gif.sh (needs vhs/ttyd/ffmpeg), then copy into docs/ exactly like
release.yml does:
git add docs/, commit docs: refresh screenshots, demo gif, release page and OG card for vX.Y.Z, git pull --rebase origin main (the packaging job's own commit may have landed),
push.
crates.io: all four crates max_stable_version == X.Y.Z, none yanked.
AUR: shiki-bin and shiki both X.Y.Z-1 via the AUR RPC; PKGBUILD sha256 for shiki-bin
matches the release's linux tarball, and shiki's sha256 matches the source tarball
(https://github.com/sazardev/shiki/archive/refs/tags/vX.Y.Z.tar.gz).
Homebrew: tap formula version "X.Y.Z" + arm/intel sha256 match release.
Scoop: both manifests version X.Y.Z, hash matches the Windows zip, extract_dir matches the
zip's top-level folder, and the two files are byte-identical.
rm -rf screenshots (gitignored local output) if a local run created it; confirm
git status --short is clean.
Report to the user: version, GitHub Release URL, and the store-by-store verification table,
plus any manual fallback that was needed (Homebrew tap push, workflow_dispatch, local
screenshots run) so they know which CI jobs are still red and why.
