release

name	release
description	Automate spek release — update CHANGELOGs, bump version, and push tag to trigger CI/CD publish. Use when the user wants to release a new version.
license	MIT
compatibility	Requires npm, git.
metadata	{"author":"spek","version":"1.3"}

Automate the spek release process — update CHANGELOGs, bump version, create tag, and push to trigger CI/CD.

Input: Optionally specify a version bump type (patch, minor, major) or an explicit version (e.g., 0.3.0). If omitted, ask.

Steps

1. Determine version bump

   If the user provided a bump type or version, use it. Otherwise, use AskUserQuestion to ask:

   Options: patch, minor, major

   Show the current version from root package.json and what each option would result in.

2. Gather changelog content

   Look at archived changes since the last release to identify what's new:

   • Check openspec/changes/archive/ for changes archived after the last release
   • Check recent git commits for context
   • Draft changelog bullet points summarizing user-facing changes

   Show the draft and ask the user to confirm or edit.

3. Update CHANGELOGs

   Update ALL THREE changelog files:

   • CHANGELOG.md (root) — the superset; write it first and filter down from it
   • packages/vscode/CHANGELOG.md
   • packages/intellij/CHANGELOG.md

   Add a new version section at the top. They share one version history, but each channel's file drops the entries that don't apply to it — a Web-only change does not appear in the vscode / intellij files.

   Check whether each entry actually reaches each channel before copying it across. IntelliJ in particular reimplements the core scanning logic in Kotlin, so a fix landing in @spekjs/core reaches Web and VS Code but not IntelliJ unless packages/intellij/ was touched too:

   git diff --name-only v<last-version>..HEAD | grep intellij
   

   A channel with nothing to report still gets a section — npm version bumps and publishes it at the new version either way, and a version with no notes reads as an oversight. Say what didn't apply and why (see 1.7.0 and 1.8.1).

4. Credit external contributors in BOTH READMEs

   A credit has to land in four separate files — two CHANGELOGs, two READMEs — and nothing checks that they agree. v1.8.1 shipped with the credit missing from the CHANGELOG entry and from both READMEs; each was found and patched separately, after the tag.

   Find who contributed since the last release:

   git log v<last-version>..HEAD --format='%an <%ae>' | sort -u
   

   Any author other than the maintainer is an external contribution — confirm the handle with gh pr view <n> --json author (the commit's email is often a users.noreply.github.com alias, not the handle).

   For each one, add the credit to both files:

   • README.md — under ## Contributors
   • README.zh-TW.md — under ## 貢獻者

   Follow the shape already in each file: - [@handle](https://github.com/handle) (Name) with one sub-bullet per contribution, appending a sub-bullet if the handle is already listed. Match each file's own typography — README.zh-TW.md uses full-width parentheses（）and —— dashes.

   The same credit belongs in the CHANGELOG entry (step 3) and the GitHub Release notes (step 11). Word it as a Thanks to [@handle](https://github.com/handle) (Name) clause, matching the existing entries.

5. Update plugin.xml change-notes

   Update packages/intellij/src/main/resources/META-INF/plugin.xml — replace the <change-notes> block with the new version's changelog content in HTML format:

   <change-notes><![CDATA[
       <p><b><version></b></p>
       <ul>
           <li>...</li>
       </ul>
   ]]></change-notes>
   

   Only include the latest version's changes (not cumulative history).

6. Commit changelog updates

   git add CHANGELOG.md packages/vscode/CHANGELOG.md packages/intellij/CHANGELOG.md packages/intellij/src/main/resources/META-INF/plugin.xml
   git commit -m "Update CHANGELOG for v<version>"
   

   If step 4 touched the READMEs, commit them too — before npm version, so the credit is inside the release rather than trailing the tag:

   git add README.md README.zh-TW.md
   git commit -m "docs(readme): credit @<handle> for <what>"
   

7. Rebuild demo page

   Rebuild docs/demo.html and badges so they reflect the latest code and openspec content:

   npm run build:demo
   npm run build:badges
   

   Stage the updated files:

   git add docs/demo.html docs/badges/
   git commit -m "Rebuild demo for v<version>"
   

8. Run npm version

   npm version <type-or-version> --no-git-tag-version
   

   Wait — the version lifecycle script in package.json auto-syncs to packages/vscode/package.json and packages/intellij/gradle.properties.

   Actually, use the standard flow which auto-commits and tags:

   npm version <type-or-version>
   

   This will:

   • Bump root package.json version
   • Run version script (syncs packages/vscode/package.json + packages/intellij/gradle.properties + git add)
   • Create git commit with version
   • Create v<version> git tag

9. Push to trigger CI/CD

   Ask the user for confirmation before pushing:

   "Ready to push v to origin? This will trigger the CI/CD pipelines to publish to VS Code Marketplace and JetBrains Marketplace."

   git push --follow-tags
   

10. Update v1 major version tag

After push, update the v1 floating tag to point to the new release commit:

git tag -fa v1 -m "Update v1 tag to v<version>"
git push origin v1 --force

This follows the GitHub Action versioning convention — users referencing spekhq/spek@v1 will automatically get the latest release.

11. Create GitHub Release

    Create a GitHub Release with Marketplace publishing:

    gh release create v<version> --title "v<version>" --notes "<changelog content>"
    

    The release will be published to the GitHub Actions Marketplace (action.yml with branding is auto-detected by GitHub).

12. Show summary

Display:

• New version number
• Changelog content
• Git tag created
• CI/CD status: "Pushed. GitHub Actions will publish to VS Code Marketplace and JetBrains Marketplace."
• GitHub Release: "Release created. Action published to GitHub Actions Marketplace."
• Remind: "Monitor the workflows at: https://github.com///actions"

Guardrails

• ALWAYS update all three CHANGELOGs (root + vscode + intellij). They share one version history but are NOT identical — each drops entries irrelevant to its channel (see CLAUDE.md). A channel with nothing to report still gets a section saying so, because npm version publishes it at the new version regardless.
• A credit for an external contribution goes in FOUR places — root CHANGELOG, the channel's CHANGELOG, README.md, README.zh-TW.md — plus the GitHub Release notes. Nothing verifies they agree; a missing one is only ever caught by a human reading the file.
• ALWAYS confirm with user before git push
• If there are uncommitted changes, warn and ask to stash or commit first
• If the working tree is dirty after changelog update, stage only changelog files
• Do NOT push without explicit user confirmation