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: hatchling (Python)
• Package manager: uv
• Version source: pyproject.toml [project] version
• Changelog format: Keep a Changelog
• Commit style: Conventional Commits (feat:, fix:, chore:, etc.)
• 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 pyproject.toml:

grep '^version = ' pyproject.toml

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:

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 part after the prefix.

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.

pyproject.toml — Update version = "X.Y.Z" in the [project] section.

server.json — Update all three version references:

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

MCP manifest files and README — These files use git+https://github.com/The-OpenROAD-Project/openroad-mcp without a version pin. Update every occurrence to pin to the release tag, which prevents supply chain attacks by ensuring users install a known, reviewed commit:

Change:

"git+https://github.com/The-OpenROAD-Project/openroad-mcp"

To:

"git+https://github.com/The-OpenROAD-Project/[email protected]"

Use a single perl pass that handles all three URL patterns in the README:

• JSON/TOML quoted: "git+https://[email protected]"
• YAML unquoted list item: - git+https://[email protected] (end of line)
• Bare (first-time pin): "git+https://...openroad-mcp"

perl -i -pe 's!git\+https://github\.com/The-OpenROAD-Project/openroad-mcp(?:\@v[\d.]+)?(?="|$)!git+https://github.com/The-OpenROAD-Project/openroad-mcp\@vX.Y.Z!g' README.md

The ! delimiter avoids clashing with the | inside the lookahead (?="|$). The lookahead matches either a closing quote (JSON/TOML) or end of line (YAML), so all config formats are covered.

After updating, verify all pinned URLs show the new tag:

grep "The-OpenROAD-Project/openroad-mcp@" README.md

Every line should show @vX.Y.Z. Also confirm no bare URLs remain:

grep 'The-OpenROAD-Project/openroad-mcp"' README.md

That should return no output.

Side note for users: If you always want the latest version and prefer not to pin, omit the @vX.Y.Z suffix and use the bare URL: git+https://github.com/The-OpenROAD-Project/openroad-mcp. This trades supply chain safety for convenience — acceptable for local/dev setups, not recommended for shared or production environments.

uv.lock — Regenerate by running uv lock. Do NOT hand-edit this file.

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

ROADMAP.md — Find the "Version Milestones" table and add a new row for this release. Move any now-completed items from future milestones into this release's description.

Step 5: Run tests

Run the test suite to verify nothing is broken:

python -m pytest --tb=short -q

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 ROADMAP.md pyproject.toml server.json uv.lock README.md

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](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. The auto-tag.yml workflow uses it to push the release tag as openroad-ci, satisfying the MCP Registry org-membership check.

• Always use uv lock to regenerate the lockfile rather than editing it manually
• 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 by running:

  grep -r "OLD_VERSION" --include="*.toml" --include="*.json" --include="*.lock" --include="*.md"

(replace OLD_VERSION with the actual previous version, e.g. 0\.5\.2) before committing, to catch any missed references

• Also verify the README git URLs were updated:

  grep "openroad-mcp@" README.md

All occurrences should show the new @vX.Y.Z tag

• If server.json doesn't exist, skip it (some repos may not have it)
• If ROADMAP.md doesn't exist or has no version table, skip it