AgentSkillsCN

versioning

在发布、标记或版本升级时使用此功能。定义SemVer规则，并确保package.json/pyproject.toml与Git标签保持同步。

SKILL.md
--- frontmatter
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)

BumpWhenExamples
MAJORBreaking changesAPI removed, incompatible changes, major rewrites
MINORNew features (backward compatible)New endpoint, new option, new capability
PATCHBug fixes (backward compatible)Fix crash, fix typo, fix edge case

Decision Tree

code
Is 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

bash
# 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

MistakeCorrect
Bumping MAJOR for new featureMINOR (if backward compatible)
Bumping PATCH for new optionMINOR (it's new functionality)
Forgetting to tagAlways tag after version bump
Tag without version updateUpdate manifest first, then tag
Inconsistent tag formatAlways use v prefix: v1.2.0

Quick Reference

bash
# 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