git

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/tool-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, configuration changes → 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 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 the version field
Java Maven	pom.xml	Modify the <version> tag
Python	pyproject.toml	Modify the 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 reviewed
• CHANGELOG.md updated
• Version number updated
• Tag 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: Frequently Asked Questions

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 Practice
git add -A && git commit -m "update"	Stage step by step, write meaningful messages
git push --force to main/master	Use --force-with-lease or prohibit
Tag without -a without message	git tag -a v1.0.0 -m "Release v1.0.0"
commit message fix bug without scope/details	fix(auth): 修复 Token 过期后无限循环刷新
Skipping version numbers without incrementing	feat → MINOR+1, fix → PATCH+1
Releasing without updating CHANGELOG	Update Changelog and Tag in sync