GitHub Version Management

Determine the next version number and update CHANGELOG.md for a release.

Quick Start

1. Get current version from package.json or git tags
2. Determine bump type: patch (fixes/deps), minor (features), major (breaking)
3. Confirm version with user via AskUserQuestion
4. Update CHANGELOG.md with new version section
5. Bump version in package.json
6. Stage changes (don't commit - let caller handle)

Scope

• Determine next semantic version
• Update CHANGELOG.md
• Bump package.json version

Release Philosophy

For npm packages:

• Releases are cheap - release often, especially for security fixes
• Keep releases small and focused
• Multiple PRs can go into one version, but prefer frequent small releases
• Pre-releases available for uncertain features

Phase 1: Determine Current Version

From Package.json

grep '"version"' packages/*/package.json | head -1
# or for root package
grep '"version"' package.json

From Git Tags

git describe --tags --abbrev=0

From CHANGELOG.md

grep -E '## \[[0-9]+\.[0-9]+\.[0-9]+\]' CHANGELOG.md | head -1

Phase 2: Determine Next Version

Based on semver and the type of changes:

Pre-releases

For features you're not fully confident in, use pre-release versions:

1.2.1-preview.1
1.2.1-preview.2
1.2.1-preview.3
...
1.2.1  (final release)

• CHANGELOG is written as if it's the final version (1.2.1)
• Pre-release suffix is only in package.json
• Increment preview number for each iteration

Confirm with User

REQUIRED: Use the AskUserQuestion tool to confirm the version before proceeding.

Example options:

• "1.2.1 (patch)" - Recommended version based on change type
• "1.3.0 (minor)" - Alternative if changes warrant it
• "Other" - User provides custom version

The question should include:

• Current version
• Recommended next version
• Reason for recommendation (security fix, bug fix, new feature, etc.)

Phase 3: Update CHANGELOG.md

Check if CHANGELOG.md Exists

ls CHANGELOG.md

If not present, skip this phase.

@shellicar CHANGELOG Format

All @shellicar repos use Keep a Changelog format:

# Changelog

## [x.y.z] - YYYY-MM-DD

### Section

- Change description

Note on dates: The date is the planned/expected release date. It doesn't need to match the actual release date exactly - it's more about when the changelog entry was written.

Standard Sections

Security Fix Entry

### Security

- Fixed CVE-2026-25547 in @isaacs/brace-expansion

Dependency Update Entry

For dependency updates, mention notable packages specifically rather than just "all dependencies". Notable means:

• Major version bumps (even in devDependencies)
• Packages users might recognize or care about
• Packages that could affect behavior (runtime deps especially)

Good examples:

### Changed

- Updated typescript to 5.8, vitest to 3.0
- Updated all dependencies to latest versions

### Changed

- Updated esbuild to 0.25, tsup to 8.5

Avoid listing every single package - no one cares about 10+ entries of patch updates. Group trivial updates under "Updated all dependencies" or omit if nothing notable.

Rule of thumb: If you wouldn't mention it in a conversation, don't list it separately.

Combined Entry (Security + Deps)

### Security

- Fixed CVE-2026-25547 in @isaacs/brace-expansion

### Changed

- Updated typescript to 5.8
- Updated all dependencies to latest versions

Update Version Links

Add link at bottom of CHANGELOG (maintain alphabetical/version order):

[1.2.1]: https://github.com/shellicar/<repo>/releases/tag/1.2.1

Insert after the most recent version link.

Phase 4: Bump Package.json Version

Use pnpm version to bump the version (avoids needing direct edit access to package.json):

# From the package directory
cd packages/<package-name>
pnpm version patch --no-git-tag-version   # 1.2.1 → 1.2.2
pnpm version minor --no-git-tag-version   # 1.2.1 → 1.3.0
pnpm version major --no-git-tag-version   # 1.2.1 → 2.0.0

# For pre-releases, use explicit version
pnpm version 1.2.1-preview.1 --no-git-tag-version

Use --no-git-tag-version to prevent pnpm from creating a git tag and commit automatically.

Phase 5: Stage Changes

git add CHANGELOG.md
git add packages/*/package.json  # or just package.json

Do NOT commit - let the calling workflow handle commits.

Integration with Other Skills

This skill is independent and composable. It can be called:

• Same PR as changes: maintenance-release → github-version → git-commit → github-pr
• Separate PR: Changes merged first, then github-version → git-commit → github-pr when ready to release

Why Separate PRs?

• Work can be done without committing to a release
• Multiple changes can be batched before releasing
• Functionality and version management are orthogonal concerns
• Useful when "not sure if we plan to release yet"

Typical Callers

• maintenance-release - optionally, after verification passes
• Standalone - when ready to release accumulated changes
• github-pr - may check if version is known for milestone

Notes

• Always confirm version with user before proceeding
• Match existing CHANGELOG format
• Security fixes and dependency updates are patch releases (no functionality change)
• Pre-releases for uncertain features: x.y.z-preview.N
• CHANGELOG date is planned date, not necessarily actual release date
• For npm packages: release early, release often