SKILL.md
Git 版本管理自动化规范
触发条件
- Generate conventional commit messages
- Manage semantic versioning
- Create Git tags
- Generate changelogs
- Generate release notes
- Automate version release workflows
Part 1: Commit Message 规范
1.1 格式
<type>(<scope>): <subject>
<body>
<footer>
1.2 Type 类型
| Type |
说明 |
示例 |
feat |
新功能 |
feat(user): 添加用户登录功能 |
fix |
Bug 修复 |
fix(auth): 修复 Token 过期验证问题 |
docs |
文档更新 |
docs(readme): 更新安装说明 |
style |
代码格式（不影响功能） |
style: 格式化代码缩进 |
refactor |
重构（非新功能、非 Bug 修复） |
refactor(user): 重构用户服务层 |
perf |
性能优化 |
perf(query): 优化分页查询性能 |
test |
测试相关 |
test(user): 添加用户服务单元测试 |
chore |
构建/工具相关 |
chore: 更新依赖版本 |
ci |
CI/CD 相关 |
ci: 添加 GitHub Actions 工作流 |
build |
构建系统相关 |
build: 升级 webpack 配置 |
revert |
回滚提交 |
revert: 回滚用户登录功能 |
1.3 Scope 范围
| Scope |
说明 |
auth |
认证授权 |
user / role / menu / dept / dict / notice |
业务模块 |
log / file / api |
日志/文件/接口 |
db / config / deps |
数据库/配置/依赖 |
1.4 自动生成流程
- 分析变更：
git diff --cached --stat && git diff --cached --name-status
- 识别类型：新增文件 →
feat，修改配置 → chore，删除文件 → refactor
- 生成 Message 示例：
feat(user): 添加用户头像上传功能
- 支持 JPG/PNG 格式
- 限制文件大小 2MB
- 自动压缩图片
Part 2: 语义化版本规范
2.1 版本格式
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
| 部分 |
说明 |
更新时机 |
| MAJOR |
主版本号 |
不兼容的 API 变更 |
| MINOR |
次版本号 |
向后兼容的功能新增 |
| PATCH |
修订号 |
向后兼容的问题修复 |
| PRERELEASE |
预发布标识 |
alpha, beta, rc |
2.2 版本递增规则
| Commit Type |
版本递增 |
feat |
MINOR +1, PATCH = 0 |
fix |
PATCH +1 |
feat! 或 BREAKING CHANGE |
MAJOR +1, MINOR = 0, PATCH = 0 |
docs / style / refactor / test / chore |
不递增 |
2.3 预发布版本
| 阶段 |
版本示例 |
说明 |
| Alpha |
1.0.0-alpha.1 |
内部测试 |
| Beta |
1.0.0-beta.1 |
公开测试 |
| Release Candidate |
1.0.0-rc.1 |
候选发布 |
| Release |
1.0.0 |
正式发布 |
2.4 版本文件同步
| 项目类型 |
版本文件 |
更新方式 |
| Node.js |
package.json |
修改 version 字段 |
| Java Maven |
pom.xml |
修改 <version> 标签 |
| Python |
pyproject.toml |
修改 version 字段 |
| Go |
可选或跳过 |
— |
Part 3: Git Tag 规范
3.1 命名格式
| 类型 |
格式 |
示例 |
| 正式版本 |
v{VERSION} |
v1.0.0 |
| 预发布版本 |
v{VERSION}-{PRERELEASE}.{N} |
v1.0.0-beta.1 |
3.2 创建带注释 Tag
git tag -a v1.0.0 -m "Release v1.0.0
Features:
- 用户登录功能
- 角色权限管理
Fixes:
- 修复 Token 过期问题"
3.3 常用命令
git tag -l # 列出所有 Tag
git tag -l "v1.*" # 匹配 Tag
git show v1.0.0 # 查看 Tag 详情
git tag -d v1.0.0 # 删除本地 Tag
git push origin --delete v1.0.0 # 删除远程 Tag
git push origin v1.0.0 # 推送单个 Tag
git push origin --tags # 推送所有 Tag
Part 4: Changelog 规范
4.1 格式模板
基于 Keep a Changelog：
# Changelog
## [Unreleased]
### Added / Changed / Deprecated / Removed / Fixed / Security
## [1.0.0] - 2024-01-15
### Added
- 用户登录功能
- 角色权限管理
### Fixed
- 修复 Token 过期验证问题 (#123)
### Security
- 升级 JWT 库修复安全漏洞
4.2 变更分类
| 分类 |
说明 |
| Added |
新增功能 |
| Changed |
功能变更 |
| Deprecated |
即将废弃 |
| Removed |
已移除 |
| Fixed |
Bug 修复 |
| Security |
安全相关 |
4.3 自动生成
git log v0.9.0..v1.0.0 --pretty=format:"%s" | grep "^feat" | sed 's/feat/### Added/'
git log v0.9.0..v1.0.0 --pretty=format:"%s" | grep "^fix" | sed 's/fix/### Fixed/'
Part 5: Release Notes 规范
# Release v1.0.0
## 🎉 新功能
### 用户管理
- **用户登录** - 支持 JWT 和 Redis Token 两种认证模式
- **角色权限** - 基于 RBAC 的细粒度权限控制
## 🐛 Bug 修复
- 修复 Token 过期后前端未正确跳转登录页的问题 (#123)
## 💥 重大变更
- API 路径统一调整为 `/api/v1/` 前缀
## 📦 依赖更新
- 升级 Spring Boot 至 3.2.0
## 完整变更日志
查看 [CHANGELOG.md](./CHANGELOG.md) 获取完整变更记录。
Part 6: 自动化工作流
6.1 标准发布流程
1. git status — 检查工作区状态
2. git checkout main && git pull — 确保在主分支
3. git add . && git commit -m "..." — 提交变更
4. git push origin main — 推送
5. 确定版本号 → 更新版本文件 — version bump
6. git add . && git commit -m "chore: release vX.X.X"
7. git tag -a vX.X.X -m "Release vX.X.X"
8. git push origin vX.X.X — 推送 Tag
9. git push origin main — 推送版本更新提交
⚠️ 注意顺序：先提交代码 → 创建 Tag → 更新版本文件 → 提交版本更新 → 推送
6.2 版本发布检查清单
Part 7: Windows PowerShell 兼容性
| Bash |
PowerShell |
说明 |
cmd1 && cmd2 |
cmd1; cmd2 或分开执行 |
PowerShell 不支持 && |
head -5 |
Select-Object -First 5 |
无 head |
grep |
Select-String 或 findstr |
无 grep |
sed |
-replace |
无 sed |
# Windows 示例
git add .
git commit -m "feat: 新功能"
git push
# 查看最近 5 个 Tag
git tag -l "v*" --sort=-v:refname | Select-Object -First 5
Part 8: 常见问题
推送被拒绝
# Rebase（推荐，保持历史线性）
git pull --rebase origin master
git push origin master
Rebase 后提交丢失
git reflog -10 # 查找丢失的提交
git cherry-pick <commit-hash> # 恢复
git push origin master
Tag 创建在错误提交上
git tag -d v1.0.0 # 删本地
git push origin --delete v1.0.0 # 删远程
git tag -a v1.0.0 <correct-hash> -m "Release v1.0.0"
git push origin v1.0.0
Part 9: 常见反模式
| 反模式 |
正确做法 |
git add -A && git commit -m "update" |
分步暂存，写有意义 Message |
git push --force 到 main/master |
用 --force-with-lease 或禁止 |
Tag 无 -a 无 message |
git tag -a v1.0.0 -m "Release v1.0.0" |
commit message fix bug 无 scope/详情 |
fix(auth): 修复 Token 过期后无限循环刷新 |
| 版本号跳跃不递增 |
feat → MINOR+1, fix → PATCH+1 |
| 不更新 CHANGELOG 就发版 |
Changelog 与 Tag 同步更新 |
