git-version

Git Version Management Automation Specification

Trigger Conditions

• Generate conventional commit messages
• Manage semantic versioning
• Create Git tags
• Generate changelogs
• Generate release notes
• Automate version release workflows

---

Part 1: Commit Message Specification

1.1 Format

<type>(<scope>): <subject>

1.2 Type

Type	Description	Example
feat	New Feature	feat(user): 添加用户登录功能
fix	Bug Fix	fix(auth): 修复 Token 过期验证问题
docs	Documentation Update	docs(readme): 更新安装说明
style	Code Formatting (does not affect functionality)	style: 格式化代码缩进
refactor	Refactoring (not a new feature, not a bug fix)	refactor(user): 重构用户服务层
perf	Performance Optimization	perf(query): 优化分页查询性能
test	Test-related	test(user): 添加用户服务单元测试
chore	Build/Tooling-related	chore: 更新依赖版本
ci	CI/CD-related	ci: 添加 GitHub Actions 工作流
build	Build System-related	build: 升级 webpack 配置
revert	Revert Commit	revert: 回滚用户登录功能

1.3 Scope

Scope	Description
auth	Authentication and Authorization
user / role / menu / dept / dict / notice	Business Module
log / file / api	Logs/Files/Interfaces
db / config / deps	Database/Configuration/Dependencies

1.4 Automatic Generation Process

1. Analyze changes:git diff --cached --stat && git diff --cached --name-status
2. Identify type: new files → feat, modified configuration → chore, deleted files → refactor
3. Generate Message example:

feat(user): 添加用户头像上传功能

- 支持 JPG/PNG 格式
- 限制文件大小 2MB
- 自动压缩图片

---

Part 2: Semantic Versioning Specification

2.1 Version Format

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Part	Description	Update Timing
MAJOR	Major Version Number	Incompatible API changes
MINOR	Minor Version Number	Backward-compatible feature additions
PATCH	Patch Version Number	Backward-compatible bug fixes
PRERELEASE	Pre-release Identifier	alpha, beta, rc

2.2 Version Increment Rules

Commit Type	Version Increment
feat	MINOR +1, PATCH = 0
fix	PATCH +1
feat! or BREAKING CHANGE	MAJOR +1, MINOR = 0, PATCH = 0
docs / style / refactor / test / chore	No Increment

2.3 Pre-release Versions

Stage	Version Example	Description
Alpha	1.0.0-alpha.1	Internal Testing
Beta	1.0.0-beta.1	Public Testing
Release Candidate	1.0.0-rc.1	Release Candidate
Release	1.0.0	Official Release

2.4 Version File Synchronization

Project Type	Version File	Update Method
Node.js	package.json	Modify version field
Java Maven	pom.xml	Modify <version> tag
Python	pyproject.toml	Modify version field
Go	Optional or skipped	—

---

Part 3: Git Tag Specification

3.1 Naming Format

Type	Format	Example
Official Version	v{VERSION}	v1.0.0
Pre-release Version	v{VERSION}-{PRERELEASE}.{N}	v1.0.0-beta.1

3.2 Creating Annotated Tags

git tag -a v1.0.0 -m "Release v1.0.0

Features:
- 用户登录功能
- 角色权限管理

Fixes:
- 修复 Token 过期问题"

3.3 Common Commands

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 Specification

4.1 Format Template

Based on 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 Change Categories

Category	Description
Added	Added Features
Changed	Changed Features
Deprecated	Deprecated
Removed	Removed
Fixed	Bug Fixes
Security	Security-related

4.3 Automatic Generation

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 Specification

# 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: Automated Workflow

6.1 Standard Release Process

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         — 推送版本更新提交

⚠️ Note the order: commit code first → create Tag → update version file → commit version update → push

6.2 Version Release Checklist

• All tests passed
• Code has been reviewed
• CHANGELOG.md has been updated
• Version number has been updated
• Tag has been created and pushed

---

Part 7: Windows PowerShell Compatibility

Bash	PowerShell	Note
cmd1 && cmd2	cmd1; cmd2 or execute separately	PowerShell does not support &&
head -5	Select-Object -First 5	no head
grep	Select-String or findstr	no grep
sed	-replace	no 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: Common Issues

Push rejected

# Rebase（推荐，保持历史线性）
git pull --rebase origin master
git push origin master

Commits lost after rebase

git reflog -10                      # 查找丢失的提交
git cherry-pick <commit-hash>       # 恢复
git push origin master

Tag created on the wrong commit

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: Common Anti-Patterns

Anti-Pattern	Correct Approach
git add -A && git commit -m "update"	Stage in steps, write meaningful messages
git push --force to main/master	Use --force-with-lease or prohibit
Tag without -a no message	git tag -a v1.0.0 -m "Release v1.0.0"
commit message fix bug no scope/details	fix(auth): 修复 Token 过期后无限循环刷新
Version number jumps without incrementing	feat → MINOR+1, fix → PATCH+1
Release without updating CHANGELOG	Changelog and Tag updated in sync