hankunpeng Semantic Version Recommender Skill
This skill analyzes code changes, public API contracts, and commit histories to intelligently determine and recommend the next Semantic Version (SemVer 2.0.0) for a project or release artifact.
When to Use This Skill
- Determining next version: User asks what version number to release next based on recent changes or git commits.
- Breaking change detection: User wants to know if their recent code diff contains breaking changes (requiring a
MAJORbump). - Release preparation & script linkage: When preparing to run build/release scripts (e.g.
node build.js -v <version>or updatingpackage.json). - Reviewing PRs / Diff impact: Assessing whether an incoming PR represents a feature (
MINOR), bugfix/refactor (PATCH), or breaking change (MAJOR).
SemVer Decision Matrix
Follow SemVer 2.0.0 (MAJOR.MINOR.PATCH):
| Type | When to Bump | Concrete Examples |
|---|---|---|
MAJOR (x.0.0) |
Incompatible / Breaking Changes | • Renaming or deleting exported functions/classes/types.• Changing required function parameters or return types.• Changing default config/behavior that breaks existing consumers.• Dropping support for a runtime/platform version.• Conventional commit with ! or BREAKING CHANGE:. |
MINOR (0.x.0) |
Backward-Compatible New Features | • Adding new public functions, classes, options, or endpoints.• Deprecating existing functionality (without removing it).• Adding optional parameters to existing functions.• Substantial performance improvements introducing new capabilities.• Conventional commit feat(...). |
PATCH (0.0.x) |
Backward-Compatible Bug Fixes & Chores | • Internal bug fixes without API changes.• Internal refactoring, style fixes, performance tuning.• Updating internal build tools, CI scripts, or documentation.• Upgrading internal dependencies (non-breaking).• Conventional commit fix(...), refactor(...), chore(...). |
Special Note on Pre-1.0.0 (
0.y.z): During initial rapid development (0.x.y),0.xis often treated with flexible breaking changes. If current version is< 1.0.0, breaking changes may bumpMINOR(0.1.0->0.2.0), and new features bumpPATCH(0.1.0->0.1.1), unless the project explicitly enforces 1.0.0+ rules. Note this context in your recommendation.
Workflow Steps
Step 1: Gather Context & Current Version
- Detect Current Version:
- Check
package.json(versionfield). - Check HTML title / metadata (e.g.
<title>... v1.0.0</title>). - Check latest Git tag (
git describe --tags --abbrev=0). - Or ask the user if none is found (fallback default
1.0.0).
- Check
- Inspect Changes:
- Run helper script:
node scripts/semver-analyzer.js --staged(or--working,--commits <range>). - Inspect
git diffon modified public interfaces, exports, and function signatures.
- Run helper script:
Step 2: Analyze API & Behavioral Impact
Categorize all changes into three buckets:
- Breaking Changes: Are any callers broken?
- Features: Are there new capabilities available?
- Fixes & Internal: Are changes purely internal/corrective?
Step 3: Compute Next Version & Output Recommendation
Always structure the output using this standard format:
### 🏷️ 推荐版本号: `vX.Y.Z` (当前: `vA.B.C` ➔ 升级类型: `MAJOR / MINOR / PATCH`)
#### 📋 变更影响分析与依据 (Rationale)
* 💥 **破坏性变更 (Breaking Changes)**:
- [无 / 列出被移除、修改签名或改变默认行为的 API]
* ✨ **新增特性 (Features)**:
- [无 / 列出新增的导出、方法、配置项或向下兼容扩展]
* 🐛 **修复与优化 (Fixes & Chores)**:
- [列出 bug 修复、内部重构、构建脚本或文档更新]
#### 🚀 建议后续操作 (Next Actions)
- **构建打包 (如适用)**: `node build.js [input.html] -o [output-vX.Y.Z.html] -v X.Y.Z`
- **版本标记 (如适用)**: `git tag -a vX.Y.Z -m "release: vX.Y.Z"`
Helper Script Reference
The skill bundles scripts/semver-analyzer.js for rapid local inspection:
# Analyze all uncommitted changes
node scripts/semver-analyzer.js
# Analyze staged changes and extract current version from HTML file
node scripts/semver-analyzer.js --staged --file app.html
# Analyze commit log between tags or range
node scripts/semver-analyzer.js --commits v1.0.0..HEAD --json