SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillskmcp-dev-release-semver

kmcp-dev-release-semver

Agents & models

View repository

Updated 10-15 22:40

About this skill

Version bump and release (kairos-mcp)

Repository: kairos-mcp. Skill index: .agents/skills/README.md. Tag automation: .github/workflows/release-tag-on-version-bump.yml (see .github/workflows/README.md). Build/test after merge: kmcp-dev-build-test.

Releases work with or without stepping through every narrative below.

  • Minimal path: npm version <type> --no-git-tag-version or npm run release:<type>, then npm run version:sync-skills when you did not use a release:* script → branch, commit, push, open PR yourself.
  • Full skill path: judgment on semver → confirmation → scripted branch + PR + explicit “no local tag” reminder.

1. Choose next version type (evidence first)

Inspect commits since the latest stable tag (or all commits when none):

STABLE_TAG=$(git tag --sort=-v:refname | rg '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1)
[ -n "$STABLE_TAG" ] && git log "${STABLE_TAG}..HEAD" --oneline || git log --oneline

Deliver before any bump:

  1. Verified facts — commit categories, API/MCP schema surface changes, release-note signals.
  2. Inference — why patch, minor, or major (or prerelease).
  3. Uncertainty — what would change the call.
Signal Type npm target
BREAKING CHANGE / feat!: / fix!: major release:major
feat: (backward-compatible) minor release:minor
fix: / docs: / chore: / refactor: / ci: / test: patch release:patch / release:bug
Prerelease ask rc / beta / pre release:rc / release:beta / release:pre

Pre-release vs beta — these are not interchangeable:

User says Script Suffix When to use
"pre release" release:pre -pre.N General pre-release on main (e.g. feature preview, early access)
"beta" release:beta -beta.N Beta on non-main branches only (see §5); requires merged PR to trigger auto-tag
"RC" release:rc -rc.N Release candidate, close to stable

Never substitute beta when the user says "pre release". They are distinct flavors in this project's semver scheme.

“Next RC” without level → recommend level first; prefer minor when new capability ships, major when contract likely breaks; ask only if still ambiguous.

Never present a bump as fact without commit evidence.

2. User confirmation

One-line format:

Recommended: <patch|minor|major> because <impact>.

Confirm semver level and prerelease flavor if any. After confirmation, run §3 without re-asking.

3. Automated steps (post-confirmation)

From repo root, in order.

3.1 Sync main

git fetch origin main
git checkout main
git pull origin main

3.2 Release branch + npm target

git checkout -b release/next
npm run release:<type>

<type>: major | minor | patch | bug | rc | pre | beta.

VERSION=$(node -p "require('./package.json').version")
git branch -m release/next "release/$VERSION"

3.3 Commit, push, PR

git add package.json package-lock.json src/embed-docs/mem/ skills/
git commit -m "release: $VERSION"
git push -u origin "release/$VERSION"
gh pr create --base main --head "release/$VERSION" \
  --title "release: $VERSION" \
  --body "Version bump to $VERSION."

Present the PR URL clearly. Optional:

gh pr view --json url -q .url

Do not create or push refs/tags/v*. Tags are created after merge when Integration succeeds; pre-push blocks manual tags.

4. What version:sync-skills does

Implementation: scripts/build-sync-skill-versions.mjs (also prebuild).

  1. src/embed-docs/mem/*.md — frontmatter version: ← package.json (including prerelease).
  2. skills/<top-level>/SKILL.md (immediate children of skills/) — metadata version: and optional references/KAIROS.md frontmatter, using the greater of package.json version and latest stable vX.Y.Z tag (see script for edge cases).

Scope: Only skills/<name>/ direct children; skills/.system/... is not auto-updated unless the script is extended.

Check: npm run version:check-skills (also pre-commit when relevant paths staged).

5. Beta release on a non-main branch

The auto-release workflow (release-tag-on-version-bump.yml) has three trigger paths:

Trigger When Branches
workflow_run Integration/Integration Simple succeed main, ci/**
pull_request (closed) release/*beta* PR merged any target branch
workflow_dispatch Manual trigger any ref (beta only)

Non-main branches only allow beta versions (version must contain -beta.).

5.1 Automatic path: PR merge triggers release

When a release/*beta* branch PR is merged into any branch (e.g. next/v4.8), the workflow fires automatically via the pull_request trigger. No manual steps needed.

The workflow:

  1. Verifies the PR was merged (not just closed).
  2. Verifies the head branch matches release/*beta*.
  3. Checks out the target branch, creates and pushes the tag.
  4. Dispatches the Release workflow.

5.2 Create the version bump PR targeting the non-main branch

# From the target branch (e.g. next/v4.8)
git checkout next/v4.8
git pull origin next/v4.8
git checkout -b release/<version>       # e.g. release/4.8.0-beta.1
npm run release:beta                     # bumps to next -beta.N
VERSION=$(node -p "require('./package.json').version")
git branch -m release/beta "release/$VERSION"
git add package.json package-lock.json src/embed-docs/mem/ skills/
git commit -m "release: $VERSION"
git push -u origin "release/$VERSION"
gh pr create --base next/v4.8 --head "release/$VERSION" \
  --title "release: $VERSION" \
  --body "Version bump to $VERSION."

After merge, the release workflow triggers automatically.

5.3 Fallback: manual workflow_dispatch

If the automatic trigger fails or you need to re-release from a branch without a new PR:

gh workflow run release-tag-on-version-bump.yml \
  --ref <branch> -f ref=<branch>
# Example:
gh workflow run release-tag-on-version-bump.yml \
  --ref next/v4.8 -f ref=next/v4.8

5.4 Verify

# Check the tag workflow run
gh run list --workflow=release-tag-on-version-bump.yml --limit 3
# Check the release workflow run
gh run list --workflow=release.yml --limit 3
# Verify the release
gh release view v<version>

Do not create or push refs/tags/v* locally. Tags are created by the workflow; pre-push hooks block manual tags.

6. Edge cases

  • Dirty tree — stash or commit unrelated work first.
  • Existing release/* — confirm reuse vs delete with the user.
  • Prerelease → stable — often npm run release:patch from an -rc line (npm semantics apply).
  • version:check-skills fails — git fetch --tags; npm run version:sync-skills; re-stage skills/, src/embed-docs/mem/, version files; re-run check.
  • New skill under skills/<dir>/ — ensure version: metadata line exists where the script expects.

Related