Automated Release Skill

This skill performs the complete end-to-end release process for omni-dev, from version bump to verified publication. docs/RELEASE.md is the canonical description; keep the two in sync.

Ground Rules

• main is protected and merges through a merge queue that rebases. Release preparation goes through a pull request. Never git push origin main, never gh pr merge --admin.
• Commit hashes change on merge. Create tags only after the merge, on the rebased commits found by subject on origin/main. Never tag a local commit.
• Two artefacts, two commits, two tags. The crate (vX.Y.Z, Cargo.toml, CHANGELOG.md) and the VS Code extension (vscode-vA.B.C, editors/vscode/package.json, editors/vscode/CHANGELOG.md) are versioned independently. A release normally cuts both; skip one only if it has nothing new since its last tag.

Execution Steps

Phase 1: Preparation

1. Verify Clean State

   git status --porcelain

   Abort if working directory is not clean.
2. Get Current Versions Read them from origin/main, not the local checkout, which may be behind:

   git fetch origin main
   git show origin/main:Cargo.toml | grep -m1 '^version = ' | sed 's/version = "\(.*\)"/\1/'
   git show origin/main:editors/vscode/package.json | jq -r .version

3. Get the Last Release Tag per Artefact A bare git describe --tags returns whichever tag is nearest, which may be the other artefact's, and v* also matches vscode-v*:

   git describe --tags --abbrev=0 --match 'v*' --exclude 'vscode-*' origin/main   # crate
   git describe --tags --abbrev=0 --match 'vscode-v*' origin/main                 # extension

4. Analyze Changes Since Last Release

   git log --oneline vPREV..origin/main
   git log --oneline vscode-vPREV..origin/main -- editors/vscode

5. Determine Version Bump (for each artefact that ships)
   • MAJOR: Breaking changes (removed APIs, changed signatures)
   • MINOR: New features (new commands, flags, integrations)
   • PATCH: Bug fixes, docs, refactoring
6. Cut a Release Branch from the current origin/main (a separate worktree is fine):

   git switch -c release/vX.Y.Z origin/main

Phase 2: Documentation & Changelog Review

7. Check if Docs Need Updates Review documentation for accuracy against new features:

   • docs/RELEASE.md - Release process still accurate?
   • README.md - Features and examples up to date?
   • CLAUDE.md - AI guidance still relevant?
   • .claude/skills/ - Skills reflect current workflows?

   Update any docs that are outdated before proceeding.

8. Assemble CHANGELOG.md (crate) from the fragments in changelog.d/ (#2213; see changelog.d/README.md)
   • Reconcile the fragments against git log --oneline vPREV..origin/main: a commit with a user-visible effect and no fragment (a wrong Changelog: none trailer) gets one now.
   • Preview, then write the section:

     python3 scripts/changelog.py collect --component crate --version X.Y.Z --dry-run
     python3 scripts/changelog.py collect --component crate --version X.Y.Z

     It adds ## [X.Y.Z] - <today> under an empty ## [Unreleased] (sections Added, Changed, Deprecated, Removed, Fixed, Security, CI/CD, Documentation; entries by issue number), updates the compare links at the bottom, and deletes the consumed fragments. The first release after #2213 also carries the hand-written [Unreleased] text into the section verbatim.
   • Read the rendered section; the release commit is the one place the changelog is edited by hand.
9. Assemble editors/vscode/CHANGELOG.md (extension) from changelog.d/vscode/
   • Both registries render a Changelog tab from it, so every published version needs an entry.
   • Reconcile against git log --oneline vscode-vPREV..origin/main -- editors/vscode and ls changelog.d/vscode/.
   • python3 scripts/changelog.py collect --component vscode --version A.B.C (preview with --dry-run first). This changelog has no compare links.

Phase 3: Version Update

10. Update Cargo.toml
    • Change version = "X.Y.Z" to new version (building in Phase 4 refreshes Cargo.lock)
11. Update the Extension Version (bumps package.json and the two omni-dev entries in package-lock.json, not dependency ranges)

    (cd editors/vscode && npm version A.B.C --no-git-tag-version --ignore-scripts --allow-same-version)
    git diff --stat -- editors/vscode   # expect only package.json and package-lock.json, at most 3 changed lines

    Use a subshell so later steps run from the repository root. --allow-same-version covers a package.json a feature commit already bumped: without it npm stops at Version not changed and the stale lockfile entries are never repaired.

Phase 4: Quality Checks

12. Run Crate Quality Checks

    cargo build --release
    cargo test
    cargo clippy -- -D warnings
    cargo fmt --all -- --check

    Abort if any check fails.
13. Run Extension Checks

    (cd editors/vscode && npm ci && npm run typecheck && npm run build && npm test && npm run package)

    Abort if any check fails.
14. Check the Extension's Publish Tokens The Marketplace and Open VSX are published independently, so an expired token fails the run without keeping the release from the other registry (vscode-v0.9.0, v0.10.0 and v0.11.0 all failed at the Marketplace step with an expired VSCE_PAT). If a token is available in the environment, verify it; never print it and never read credential files to find one:

    VSCE_PAT=<token> npx @vscode/vsce verify-pat rust-works
    OVSX_PAT=<token> npx ovsx verify-pat rust-works

    gh secret list shows only when a secret was set, not whether it works. If a token cannot be verified or fails, tell the user before tagging the extension and carry on with the crate if they agree.

Phase 5: Commit, Pull Request and Merge Queue

15. Commit the Crate Release

    git add -A -- Cargo.toml Cargo.lock CHANGELOG.md changelog.d ':!changelog.d/vscode'
    git commit -m "$(cat <<'EOF'
    chore(release): prepare release vX.Y.Z
    
    - Update version from PREV to X.Y.Z
    - Assemble CHANGELOG.md from the changelog.d fragments
    EOF
    )"

    The subject must keep this exact form: Phase 6 finds the rebased commit by it.
16. Commit the Extension Release

    git add editors/vscode/package.json editors/vscode/package-lock.json editors/vscode/CHANGELOG.md && git add -A -- changelog.d/vscode
    git commit -m "$(cat <<'EOF'
    chore(release): prepare vscode extension release vA.B.C
    
    - Update version from PREV to A.B.C in package.json and package-lock.json
    - Assemble the extension CHANGELOG.md from the changelog.d/vscode fragments
    EOF
    )"

17. Open the Pull Request and Enqueue It

    omni-dev git commit message lint origin/main..HEAD
    git push -u origin release/vX.Y.Z
    gh pr create --title "chore(release): prepare release vX.Y.Z and vscode extension vA.B.C" --body "Release preparation."
    gh pr checks --watch
    gh pr merge <PR>        # enqueues; never --admin

18. Wait for the Merge

    gh pr view <PR> --json state,mergeCommit

    Poll until state is MERGED. If main moved and the branch now conflicts, rebase the branch onto origin/main, resolve it, push and enqueue again. If the queue ejects the entry, fix the failing check on the branch and re-enqueue.

Phase 6: Tag the Rebased Commits

19. Locate the Commits as They Landed on main Phases 6 and 7 each have a crate half and an extension half; do only the halves for the artefacts being released. The dots are escaped because --grep takes a regular expression:

    git fetch origin main
    CRATE=$(git log origin/main --format=%H -1 --grep='^chore(release): prepare release vX\.Y\.Z$')
    EXT=$(git log origin/main --format=%H -1 --grep='^chore(release): prepare vscode extension release vA\.B\.C$')

    Abort if a lookup you need is empty. If a fix had to land after the release commit, tag the fix's hash instead: it carries the correct files, and the subject lookup would return the original commit.
20. Create Annotated Tags on Those Commits (not on HEAD)

    git tag -a vX.Y.Z -m "Release version X.Y.Z
    
    <summary of key changes>
    " "$CRATE"
    
    git tag -a vscode-vA.B.C -m "VS Code extension A.B.C
    
    <summary of key changes>
    " "$EXT"

21. Verify the Tagged Commits Before Pushing release.yml does not compare the tag with Cargo.toml, so verify locally while a bad tag can still be deleted:

    # On main
    git merge-base --is-ancestor vX.Y.Z origin/main && echo ok
    git merge-base --is-ancestor vscode-vA.B.C origin/main && echo ok
    
    # Versions at the tag: all must read the new version
    git show vX.Y.Z:Cargo.toml | grep -m1 '^version = '
    git show vX.Y.Z:Cargo.lock | grep -A1 '^name = "omni-dev"$'
    git show vscode-vA.B.C:editors/vscode/package.json | jq -r .version
    git show vscode-vA.B.C:editors/vscode/package-lock.json | jq -r '.version, .packages[""].version'
    
    # Nothing left under [Unreleased] at either tag: both must print nothing
    git show vX.Y.Z:CHANGELOG.md | awk '/^## \[Unreleased\]/{f=1;next} /^## \[/{f=0} f && NF'
    git show vscode-vA.B.C:editors/vscode/CHANGELOG.md | awk '/^## \[Unreleased\]/{f=1;next} /^## \[/{f=0} f && NF'

    On any failure, git tag -d <tag>, fix it in a follow-up pull request and start again from Phase 5. Do not push a bad tag.
22. Push the Tags

    git push origin vX.Y.Z vscode-vA.B.C   # only the tags you created

Phase 7: Monitor CI Release

23. Wait for the Release Workflows Poll the GitHub Actions workflows until completion:

    # Get the run ID for the workflow triggered by each tag
    gh run list --workflow=release.yml --branch=vX.Y.Z --limit=1 --json databaseId,status,conclusion
    gh run list --workflow=vscode-extension-release.yml --branch=vscode-vA.B.C --limit=1 --json databaseId,status,conclusion

24. Poll Until Complete Loop with 30-second intervals:

    gh run view <run_id> --json status,conclusion

    • status: "completed" + conclusion: "success" = Success
    • status: "completed" + conclusion: "failure" = Failed (show logs)
    • status: "in_progress" or status: "queued" = Keep polling
25. On Failure: Show Logs

    gh run view <run_id> --log-failed

    For an extension run that failed at a publish step (typically an expired VSCE_PAT), the other registry was still attempted. Tell the user to renew the secret, then re-run on the same tag; --skip-duplicate leaves a registry that already has the version alone:

    gh run rerun <run_id> --failed

Phase 8: Verification

26. Verify GitHub Release

    gh release view vX.Y.Z --json assets --jq '.assets[].name'

    Expect omni-dev-linux.tar.gz, omni-dev-linux-arm64.tar.gz, omni-dev-macos-arm64.tar.gz and omni-dev-windows.zip. A missing asset means a matrix leg failed, and publish-crates is blocked with it. After a transient failure (runner outage, network) gh run rerun <run_id> --failed recovers it, after gh release delete-asset vX.Y.Z <asset-name> if the upload then reports the asset already exists. A defect in the code or the workflow needs a patch release, because a re-run uses the tag's commit. Do not continue without the asset.
27. Verify crates.io Publication

    cargo search omni-dev --limit 1

28. Verify the Released Binary Reports the New Version

    d=$(mktemp -d)
    gh release download vX.Y.Z --pattern 'omni-dev-macos-arm64.tar.gz' --dir "$d"   # pick the host platform's asset
    tar xzf "$d/omni-dev-macos-arm64.tar.gz" -C "$d"
    "$d/omni-dev" --version                        # omni-dev X.Y.Z (<short sha> <date>)
    git rev-parse 'vX.Y.Z^{commit}'                # full SHA; it must start with <short sha>

    The short SHA's length varies with the machine that built the binary, so compare by prefix. Only the host's own asset can be run. Extract each of the others the same way and run file "$d/omni-dev" to confirm the architecture its name claims, notably omni-dev-linux-arm64.tar.gz (ELF 64-bit ... ARM aarch64) against omni-dev-linux.tar.gz (x86-64).
29. Verify the Extension The workflow's publish steps are the evidence: both Publish to VS Code Marketplace and Publish to Open VSX must be green, not skipped. Open VSX can be read back; the Marketplace cannot be relied on, since read APIs lag a publish and vsce show can answer not found for a live extension:

    curl -s https://open-vsx.org/api/rust-works/omni-dev/latest | jq -r .version

30. Report Success Display:
    • New crate and extension versions
    • GitHub release URL
    • crates.io URL
    • Registry status for the extension
    • Changelog summary

Phase 9: Manual Glama Listing Update

31. Prompt the User to Update Glama The Glama MCP listing pins its Docker build to a specific commit SHA and only rebuilds when that SHA is bumped. This step is a web-UI action that cannot be automated from here.

    Display to the user:

    • The short release SHA: git rev-parse --short 'vX.Y.Z^{commit}' (the ^{commit} matters: the tag is annotated, so the bare tag name returns the tag object's hash, not a commit)
    • The admin URL: https://glama.ai/mcp/servers/rust-works/omni-dev/admin/dockerfile
    • A pointer to the procedure: docs/glama-listing.md

    Do not block on this — it's an out-of-band manual step the human performs after the automated release lands.

Error Handling

Polling Configuration

• Initial delay: 10 seconds (allow workflow to start)
• Poll interval: 30 seconds
• Timeout: 15 minutes
• Max polls: 30

CI Workflows Triggered

Pushing a v* tag triggers (the !vscode-* exclusion keeps the extension's tags out of both):

Pushing a vscode-v* tag triggers:

Important Notes

• Do NOT manually run gh release create - CI handles this automatically
• The release workflow creates the GitHub release from the tag
• Cross-platform binaries (Linux, macOS, Windows) are built and attached
• crates.io publication uses CARGO_REGISTRY_TOKEN secret
• Extension publication uses the VSCE_PAT and OVSX_PAT secrets; each registry is skipped if its token is unset
• The coverage action (action-works/patchcov-action) installs patchcov independently of omni-dev releases. Changes to coverage behavior require a published patchcov version; an omni-dev release does not unblock them

Commands Reference

# Check workflow status
gh run list --workflow=release.yml --limit=5
gh run list --workflow=vscode-extension-release.yml --limit=5

# Watch workflow in real-time
gh run watch <run_id>

# View workflow logs
gh run view <run_id> --log

# View failed job logs only
gh run view <run_id> --log-failed

# Re-run only the failed jobs on the same tag
gh run rerun <run_id> --failed

# Verify release
gh release view vX.Y.Z

# Check crates.io
cargo search omni-dev --limit 1

Failed Release Recovery

If the release has already been published, keep its tag and commit as a record of the published version. Correct the problem on main through a pull request, then prepare a new patch release following docs/RELEASE.md. Do not blindly revert the branch tip: another commit may have landed since, and a direct push to main is rejected. A registry will not take the same version twice, so the extension is fixed forward the same way.

If the crate was published and must no longer be selected by Cargo, yank that version:

cargo yank --version X.Y.Z

If the GitHub release itself must go:

gh release delete vX.Y.Z --yes

Delete a tag only when its workflows failed before anything reached a registry, and then only to push the corrected one:

git tag -d vX.Y.Z
git push --delete origin vX.Y.Z