git-conventions

Git 约定技能

本技能全面介绍 Git 约定、工作流最佳实践和标准化提交格式，帮助保持仓库历史记录整洁易读。

适用场景

在以下情况下启用此技能：

• 按照标准编写提交消息
• 建立团队 Git 工作流
• 设置分支命名约定
• 实施 Conventional Commits
• 创建变更日志自动化流程
• 在代码审查中检查 Git 规范
• 帮助团队成员熟悉 Git 实践

Conventional Commits

格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

提交类型

主要类型：

• feat：为用户提供新功能
• fix：修复用户遇到的错误
• docs：仅修改文档
• style：代码风格修改（格式调整、遗漏分号等）
• refactor：既不修复错误，也不添加功能的代码修改
• perf：性能改进
• test：添加或修正测试
• build：修改构建系统或依赖项
• ci：修改 CI 配置文件和脚本
• chore：其他不修改 src 或 test 文件的变更
• revert：撤销之前的提交

示例

简单提交：

feat: add user authentication

Implement JWT-based authentication system with refresh tokens.
Includes middleware for protected routes.

Closes #123

破坏性变更：

feat!: redesign API response format

BREAKING CHANGE: API now returns data in camelCase instead of snake_case.
Migration guide available in docs/migration-v2.md.

Refs: #456

包含作用域：

fix(auth): resolve token expiration edge case

Token validation now properly handles timezone offsets.
Adds retry logic for expired tokens within 5-minute grace period.

包含多个段落：

refactor(database): optimize query performance

- Add indexes on frequently queried columns
- Implement connection pooling
- Cache common queries with Redis
- Reduce N+1 queries in user associations

Performance improved by 60% in production testing.

Reviewed-by: Jane Doe <[email protected]>
Refs: #789

提交消息规则

1. 主题行：

   • 使用祈使语气（用 “add”，不要用 “added” 或 “adds”）
   • 首字母不要大写
   • 末尾不要加句号
   • 最多 50 个字符（软性限制）
   • 与正文之间空一行

2. 正文：

   • 每行不超过 72 个字符
   • 说明做了什么以及为什么，而非如何实现
   • 有多项内容时使用项目符号
   • 引用问题和 PR

3. 页脚：

   • 破坏性变更以 “BREAKING CHANGE:” 开头
   • 引用问题：“Closes #123”、“Fixes #456”、“Refs #789”
   • 联合作者：“Co-authored-by: Name ”

分支命名约定

格式模式

<type>/<issue-number>-<short-description>

分支类型

常见前缀：

• feature/ 或 feat/ - 新功能
• fix/ 或 bugfix/ - 修复错误
• hotfix/ - 紧急生产修复
• release/ - 准备发布
• docs/ - 更新文档
• refactor/ - 重构代码
• test/ - 添加或修复测试
• chore/ - 维护任务
• experimental/ 或 spike/ - 概念验证

示例

# Feature branches
feature/123-user-authentication
feat/456-add-payment-gateway
feature/oauth-integration

# Bug fix branches
fix/789-resolve-memory-leak
bugfix/login-redirect-loop
fix/456-null-pointer-exception

# Hotfix branches
hotfix/critical-security-patch
hotfix/production-database-issue

# Release branches
release/v1.2.0
release/2024-Q1

# Documentation branches
docs/api-reference-update
docs/123-add-contributing-guide

# Refactor branches
refactor/database-layer
refactor/456-simplify-auth-flow

# Experimental branches
experimental/graphql-api
spike/performance-optimization

分支命名规则

1. 使用连字符分隔单词（不要使用下划线）
2. 仅使用小写字母（避免大写字母）
3. 保持简短且描述清晰（最多 50 个字符）
4. 适用时包含问题编号
5. 避免特殊字符，仅使用连字符和正斜杠
6. 末尾不要加斜杠
7. 在团队内保持一致

受保护分支策略

主分支

main/master：

• 可用于生产环境的代码
• 始终可部署
• 设置必要的审查保护
• 不直接提交
• 仅从发布或热修复分支合并

develop：

• 用于集成功能的分支
• 用于预生产测试
• 通过 CI 检查进行保护
• 作为功能分支的合并目标

staging：

• 预生产环境
• QA 测试分支
• 与生产环境镜像同步，并包含新功能

保护规则

# Example GitHub branch protection
main:
  require_pull_request_reviews:
    required_approving_review_count: 2
    dismiss_stale_reviews: true
    require_code_owner_reviews: true

  require_status_checks:
    strict: true
    contexts:
      - continuous-integration
      - code-quality
      - security-scan

  enforce_admins: true
  require_linear_history: true
  allow_force_pushes: false
  allow_deletions: false

语义化版本控制

版本格式

MAJOR.MINOR.PATCH[-prerelease][+build]

示例：

• 1.0.0 - 初始版本
• 1.2.3 - 包含补丁的次要更新
• 2.0.0-alpha.1 - Alpha 预发布版本
• 1.5.0-rc.2+20240321 - 包含构建元数据的候选发布版本

版本递增规则

MAJOR (X.0.0)：

• 破坏性变更
• API 不兼容
• 重大重新设计
• 移除已弃用的功能

MINOR (x.Y.0)：

• 新功能（向后兼容）
• 弃用的功能（仍可使用）
• 大幅内部变更

PATCH (x.y.Z)：

• 修复错误
• 安全补丁
• 性能改进
• 文档更新

版本 Git 标签

# Create annotated tag
git tag -a v1.2.3 -m "Release version 1.2.3

- Add user authentication
- Fix memory leak in cache
- Improve API performance"

# Push tags to remote
git push origin v1.2.3

# Push all tags
git push --tags

# Create pre-release tag
git tag -a v2.0.0-beta.1 -m "Beta release for v2.0.0"

# Delete tag
git tag -d v1.2.3
git push origin :refs/tags/v1.2.3

工作流模式

Git Flow

分支结构：

• main - 生产版本发布
• develop - 下一版本的开发
• feature/* - 新功能
• release/* - 准备发布
• hotfix/* - 紧急修复

功能工作流：

# Start feature
git checkout develop
git pull origin develop
git checkout -b feature/123-new-feature

# Work on feature
git add .
git commit -m "feat: implement user authentication"

# Finish feature
git checkout develop
git pull origin develop
git merge --no-ff feature/123-new-feature
git push origin develop
git branch -d feature/123-new-feature

发布工作流：

# Start release
git checkout develop
git checkout -b release/v1.2.0

# Prepare release (bump version, update changelog)
git commit -m "chore: prepare release v1.2.0"

# Merge to main
git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"

# Merge back to develop
git checkout develop
git merge --no-ff release/v1.2.0

# Cleanup
git branch -d release/v1.2.0

热修复工作流：

# Start hotfix from main
git checkout main
git checkout -b hotfix/critical-bug

# Fix and commit
git commit -m "fix: resolve critical security vulnerability"

# Merge to main
git checkout main
git merge --no-ff hotfix/critical-bug
git tag -a v1.2.1 -m "Hotfix v1.2.1"

# Merge to develop
git checkout develop
git merge --no-ff hotfix/critical-bug

# Cleanup
git branch -d hotfix/critical-bug

GitHub Flow

简化工作流：

• main - 始终可部署
• feature/* - 所有更改都在功能分支中进行

工作流：

# Create feature branch
git checkout -b feature/add-logging
git push -u origin feature/add-logging

# Make changes and commit
git commit -m "feat: add structured logging"
git push origin feature/add-logging

# Open pull request on GitHub
# After review and CI passes, merge to main
# Deploy from main

Trunk-Based Development

单一主分支：

• 生命周期较短的功能分支（< 2 天）
• 频繁合并到 main
• 使用功能标志处理未完成的功能
• 持续集成

工作流：

# Create short-lived branch
git checkout -b update-api-docs
git push -u origin update-api-docs

# Make small, incremental changes
git commit -m "docs: update API endpoint documentation"
git push origin update-api-docs

# Immediately create PR and merge (same day)
# Main branch always deployable with feature flags

Pull Request 规范

PR 标题格式

使用 Conventional Commits 格式：

feat(auth): add OAuth2 provider support
fix(api): resolve rate limiting edge case
docs: update installation guide

PR 描述模板

## Summary
Brief description of changes and motivation.

## Changes
- Bullet list of specific changes
- Reference architecture decisions
- Note any breaking changes

## Testing
- Unit tests added/updated
- Integration tests passed
- Manual testing performed

## Screenshots (if applicable)
[Add screenshots for UI changes]

## Related Issues
Closes #123
Refs #456

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Changelog updated
- [ ] Breaking changes documented
- [ ] Code reviewed by team

评审指南

评审者检查清单：

• 代码遵循风格指南
• 提交消息遵循规范
• 测试全面
• 文档已更新
• 不存在安全漏洞
• 已考虑性能因素
• 破坏性更改理由充分

变更日志管理

Keep a Changelog 格式

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- User authentication with JWT tokens
- API rate limiting middleware

### Changed
- Updated database schema for better performance

### Deprecated
- Old authentication endpoint (use /api/v2/auth instead)

### Removed
- Legacy XML API support

### Fixed
- Memory leak in cache implementation
- Race condition in concurrent requests

### Security
- Patch for SQL injection vulnerability

## [1.2.0] - 2024-03-15

### Added
- Real-time notifications system
- User profile customization

### Fixed
- Login redirect loop issue
- Session timeout handling

## [1.1.0] - 2024-02-01

### Added
- Search functionality
- Export to CSV feature

### Changed
- Improved UI responsiveness

自动生成变更日志

使用以下工具：

• conventional-changelog - 根据提交生成变更日志
• release-please - 自动发布并生成变更日志
• semantic-release - 完全自动化的版本管理

最佳实践

1. 经常提交： 小而专注的提交更容易评审和撤销
2. 编写清晰的消息： 未来的你会感谢现在的你
3. 每次提交只处理一项内容： 每次提交都应针对一项逻辑上的更改
4. 提交前测试： 提交前确保代码正常运行
5. 关联问题： 将提交关联到问题跟踪系统
6. 自行评审更改： 提交前使用 git diff --staged
7. 保持历史记录整洁： 对功能分支进行变基，以保持线性历史记录
8. 为提交签名： 使用 GPG 签名验证提交
9. 正确使用 .gitignore： 切勿提交敏感文件或生成的文件
10. 记录规范： 在仓库文档中记录团队规范

团队工作流示例

小型团队（2-5 位开发者）

# Simplified workflow
- Direct commits to main (with PR reviews)
- Feature branches for major changes
- Tags for releases
- Linear history preferred

中型团队（5-20 位开发者）

# Git Flow variant
- Protected main and develop branches
- Feature branches required
- Release branches for versions
- Hotfix workflow for emergencies
- Squash merge for clean history

大型团队（20 位以上开发者）

# Trunk-based with feature flags
- Protected main branch
- Very short-lived feature branches
- Feature flags for incomplete work
- Automated testing and deployment
- Multiple daily integrations

资源

更多指南和模板可在 assets/ 目录中找到：

• templates/ - 提交消息和 PR 模板
• examples/ - 真实工作流示例
• tools/ - Git 钩子和自动化脚本

references/ 目录中提供：

• Conventional Commits 规范
• Semantic Versioning 文档
• Git Flow 和 GitHub Flow 指南
• Keep a Changelog 标准