Release Preparation

This skill automates the full release preparation workflow for the openroad-mcp project. It ensures every file that references the version gets updated consistently.

Project context

• Build system: npm / Node.js 22
• Version source: typescript/package.json .version field
• Changelog format: Keep a Changelog
• GitHub repo: The-OpenROAD-Project/openroad-mcp
• Release gatekeeper: @vvbandeira (org member) — must approve and merge all releases

Workflow

Step 1: Determine versions

Read the current version from typescript/package.json:

jq -r '.version' typescript/package.json

Then ask the user what the new version should be. Suggest the next logical semver bump based on the commits since the last release:

• Patch (0.3.0 → 0.3.1): only fixes and minor changes
• Minor (0.3.0 → 0.4.0): new features added, backwards compatible
• Major (0.3.0 → 1.0.0): breaking changes

Show the suggestion but let the user decide.

Step 2: Collect commits since last release

Get the last release tag:

git tag --sort=-v:refname | head -5

Then list all commits since that tag:

git log <last-tag>..HEAD --oneline

If no tag exists, use the first commit or the last "chore: release" commit:

git log --oneline --grep="chore: release" | head -1

Step 3: Categorize commits into changelog sections

Read each commit message and sort into Keep a Changelog categories. Commits may use conventional prefixes or plain one-liner sentences — both are accepted:

For each commit, format the changelog entry as:

- Description ([#PR](https://github.com/The-OpenROAD-Project/openroad-mcp/pull/PR))

Use the PR number from the commit message if present. For commits without a PR number, just use the description sentence.

Step 4: Update all version references

These files must be updated with the new version. Update ALL of them — missing one breaks the release consistency.

typescript/package.json (+ lockfile) — the canonical version source:

npm version --prefix typescript --no-git-tag-version X.Y.Z

This updates package.json and package-lock.json together. The TypeScript server reads its advertised MCP version from package.json.

server.json — Update all version references:

• Top-level "version": "X.Y.Z"
• npm package "version": "X.Y.Z"
• OCI identifier "identifier": "ghcr.io/The-OpenROAD-Project/openroad-mcp:X.Y.Z"

CHANGELOG.md — Add new section before the previous version's section. Today's date goes in the header. Add the link at the bottom:

[X.Y.Z]: https://github.com/The-OpenROAD-Project/openroad-mcp/releases/tag/vX.Y.Z

Step 5: Run tests

Run the test suite to verify nothing is broken:

cd typescript && npm run test

If tests fail, report the failures to the user before proceeding. Do not commit a broken release.

Step 6: Create the release commit and open a PR

Stage only the release-related files:

git add CHANGELOG.md server.json typescript/package.json typescript/package-lock.json

Commit under the openroad-ci bot identity (public org member — required so the MCP Registry OIDC check passes when the release workflow runs):

git -c user.name="openroad-ci" \
    -c user.email="[email protected]" \
    commit -m "chore: release vX.Y.Z"

Then push to a dedicated release branch and open a PR:

git checkout -b release/vX.Y.Z
git push -u origin release/vX.Y.Z
gh pr create \
  --title "chore: release vX.Y.Z" \
  --body "$(cat <<'EOF'
## Release vX.Y.Z

See [CHANGELOG.md](https://github.com/The-OpenROAD-Project/openroad-mcp/blob/release/vX.Y.Z/CHANGELOG.md) for full details.

/cc @vvbandeira — please review and merge when ready.
EOF
)" \
  --reviewer vvbandeira

NEVER push directly to `main`. The decision to merge and tag belongs exclusively to @vvbandeira. Once the PR is open, report the PR URL to the user and stop — do not merge, squash, or tag.

Tagging is automated. When @vvbandeira squash-merges the release PR, the auto-tag.yml workflow detects the chore: release vX.Y.Z commit message and pushes the tag as openroad-ci using OPENROAD_CI_PAT. This ensures the release workflow actor is a publicly visible org member, satisfying the MCP Registry OIDC check. No manual tagging needed.

Important details

• Never push to `main` directly. Always use a release/vX.Y.Z branch and open a PR.
• @vvbandeira must review and merge — request them as a reviewer on every release PR.
• `OPENROAD_CI_PAT` secret required — this PAT must be stored in the repo settings

with Contents: Read and write scope (and Pull requests write for Prepare Release). The auto-tag.yml / prepare-release.yml workflows use it to push the release branch/tag as openroad-ci, satisfying the MCP Registry org-membership check.

• The CHANGELOG date format is ISO: YYYY-MM-DD
• Version tags use a v prefix: v0.4.0 (but the version in files has no prefix)
• Check for ALL files referencing the old version before committing:

  grep -r "OLD_VERSION" typescript/package.json typescript/package-lock.json server.json CHANGELOG.md

• If server.json doesn't exist, skip it (some repos may not have it)