Version Bump & Release Workflow

Version Bump & Release Workflow

IMPORTANT: You must first plan and write detailed release notes before starting the version bump workflow

Category: design Source: thedotmack/claude-mem

Version Bump & Release Workflow

What Is This?

The "Version Bump & Release Workflow" skill provides a structured and automated process for managing semantic versioning and release cycles for Claude Code plugins. This workflow is designed to increment versions across all relevant configuration files (package.json, .claude-plugin/marketplace.json, and plugin/.claude-plugin/plugin.json), verify the integrity of the build, commit all changes, create annotated Git tags, push updates to the remote repository, and generate GitHub releases. The process ensures consistency and traceability across plugin releases while enforcing strict versioning and changelog practices.

Why Use It?

Managing versioning and release cycles in software projects, especially when multiple configuration files and build artifacts are involved, can be error-prone and tedious. Manual version bumps risk inconsistencies, missing files, or incomplete releases. This skill addresses these issues by providing a clear, repeatable workflow that guarantees:

  • Semantic versioning compliance: Ensures every release is classified correctly as PATCH, MINOR, or MAJOR.
  • Synchronization: All version strings are updated uniformly across necessary files.
  • Release traceability: Annotated tags and detailed release notes help track what has changed in each release.
  • Artifact integrity: The workflow verifies that all build artifacts are generated and included in the commit.
  • Automation: Reduces manual steps, minimizing the risk of forgetting critical actions.

For teams or individual developers working on Claude Code plugins, adopting this workflow eliminates ambiguity and enforces best practices, resulting in higher quality and more reliable releases.

How to Use It

The workflow consists of several ordered steps, each enforcing discipline and completeness in the release process. The following details the entire process, including code commands and expected checks.

1. Plan and Write Release Notes

Before initiating the workflow, write detailed release notes describing every change, improvement, or fix included in the release. This step is mandatory and forms the basis of the GitHub release description.

2. Preparation

  • Analyze the change type: Decide if the update qualifies as a PATCH (for bug fixes), MINOR (for backward-compatible feature additions), or MAJOR (for breaking changes).

  • Identify repository details: Use the command below to confirm the remote repository:

    git remote -v

  • Check required files: Ensure the following files exist in your repository:

    • package.json
    • .claude-plugin/marketplace.json
    • plugin/.claude-plugin/plugin.json

3. Increment Version Numbers

Update the version string in all configuration files. For example, to update from 1.0.0 to 1.1.0:

// package.json
{
  "version": "1.1.0"
}

Repeat this version update in marketplace.json and plugin.json.

4. Verify Version Consistency

To confirm all files reflect the new version, use grep:

grep '"version": "1.1.0"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json

This command should return a line for each file, verifying consistency.

5. Build Artifacts

Generate fresh build artifacts to ensure your release includes the latest compiled output:

npm run build

Resolve any errors before proceeding.

6. Stage and Commit All Changes

Ensure every change, including build artifacts, is staged and committed. Use:

git add -A
git commit -m "chore: bump version to 1.1.0"

7. Tag the Release

Create an annotated Git tag for traceability:

git tag -a v1.1.0 -m "Version 1.1.0"

8. Push to Remote

Push both the main branch and the new tag to the remote repository:

git push origin main
git push origin v1.1.0

9. Create a GitHub Release

Initiate a new release using the tagged version and include your detailed release notes:

gh release create v1.1.0 --title "Version 1.1.0" --notes "Paste your release notes here"

10. Final Verification

Ensure nothing is left uncommitted or unpushed:

git status

Your working directory should be clean.

When to Use It

Apply this workflow every time you prepare to release a new version of your Claude Code plugin, regardless of the scale of changes. It is suitable for:

  • Routine maintenance releases (PATCH)
  • Feature additions (MINOR)
  • Major refactors or breaking changes (MAJOR)

Never skip steps or leave artifacts uncommitted. This process ensures every release is complete, consistent, and easily auditable.

Important Notes

  • Release notes are mandatory: Begin by drafting comprehensive release notes before starting the workflow.
  • Commit everything: Build artifacts and all configuration changes must be included in the commit.
  • No uncommitted changes: At the end of the workflow, use git status to confirm a clean working directory.
  • Do not skip verification: Always double-check version numbers and build outputs.
  • Tag and release: Annotated tags and GitHub releases are required for proper traceability.

By following this workflow, teams can maintain high standards of quality and reliability for all plugin releases, minimize errors, and provide clear documentation for every update. This skill is a critical component of any disciplined plugin development lifecycle.