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 同步更新 |
