---

name: versioning description: Use when releasing, tagging, or bumping versions. Defines semver rules and keeps package.json/pyproject.toml synced with git tags.

Versioning

Semantic versioning rules and workflow for consistent releases.

Semver Rules

Format: MAJOR.MINOR.PATCH (e.g., 1.4.2)

Decision Tree

CopyIs it a breaking change?
├── Yes → MAJOR
└── No → Does it add new functionality?
    ├── Yes → MINOR
    └── No → PATCH

What Counts as Breaking?

MAJOR (breaking):

• Removing a public function/endpoint
• Changing function signature (required params)
• Changing return type
• Renaming exports
• Dropping support for runtime/dependency

MINOR (feature):

• Adding new function/endpoint
• Adding optional parameter
• New configuration option
• Performance improvement with no API change

PATCH (fix):

• Bug fix
• Documentation fix
• Internal refactor (no API change)
• Dependency update (non-breaking)

Version Sync Workflow

Keep these in sync:

1. package.json version (JS/TS projects)
2. pyproject.toml version (Python projects)
3. Git tag

Release Workflow

Copy# 1. Update version in manifest
# package.json: "version": "1.2.0"
# OR pyproject.toml: version = "1.2.0"

# 2. Commit the version bump
git add package.json  # or pyproject.toml
git commit -m "chore: bump version to 1.2.0"

# 3. Tag the commit
git tag -a v1.2.0 -m "Release 1.2.0: [brief description]"

# 4. Push with tags
git push && git push --tags

Pre-release Versions

For work-in-progress releases:

• 1.2.0-alpha.1 - Early testing
• 1.2.0-beta.1 - Feature complete, testing
• 1.2.0-rc.1 - Release candidate

Common Mistakes

Quick Reference

Copy# Check current version
node -p "require('./package.json').version"
# or
grep version pyproject.toml

# List tags
git tag -l

# See what changed since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline