Git Conventions Skill

Git 约定技能指南

This skill provides comprehensive guidance on git conventions, workflow best practices, and standardized commit formats to maintain clean, readable repository history.

本技能提供Git约定、工作流最佳实践及标准化提交格式的全面指导，以维护清晰、易读的仓库历史。

When to Use

适用场景

Activate this skill when:

Writing commit messages following standards
Establishing team git workflows
Setting up branch naming conventions
Implementing Conventional Commits
Creating changelog automation
Code review for git hygiene
Onboarding team members on git practices

在以下场景中启用本技能：

撰写符合标准的提交消息
建立团队Git工作流
设置分支命名约定
实施Conventional Commits规范
实现变更日志自动化
针对Git规范的代码评审
为团队成员进行Git实践培训

Conventional Commits

Format

格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

提交类型

Primary Types:

feat: New feature for the user
fix: Bug fix for the user
docs: Documentation only changes
style: Code style changes (formatting, missing semi-colons, etc)
refactor: Code change that neither fixes a bug nor adds a feature
perf: Performance improvements
test: Adding or correcting tests
build: Changes to build system or dependencies
ci: Changes to CI configuration files and scripts
chore: Other changes that don't modify src or test files
revert: Reverts a previous commit

主要类型：

feat：为用户新增功能
fix：修复用户侧的Bug
docs：仅修改文档
style：代码样式变更（如格式化、补充分号等）
refactor：既不修复Bug也不新增功能的代码变更
perf：性能优化
test：新增或修正测试用例
build：构建系统或依赖项变更
ci：CI配置文件或脚本变更
chore：其他不修改源码或测试文件的变更
revert：回滚之前的提交

Examples

示例

Simple commit:

bash

feat: add user authentication

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

Closes #123

Breaking change:

bash

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

With scope:

bash

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.

Multiple paragraphs:

bash

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 <jane@example.com>
Refs: #789

简单提交：

bash

feat: add user authentication

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

Closes #123

破坏性变更：

bash

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

带作用域的提交：

bash

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.

多段落提交：

bash

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 <jane@example.com>
Refs: #789

Commit Message Rules

提交消息规则

Subject line:
- Use imperative mood ("add" not "added" or "adds")
- No capitalization of first letter
- No period at the end
- Maximum 50 characters (soft limit)
- Separate from body with blank line
Body:
- Wrap at 72 characters
- Explain what and why, not how
- Use bullet points for multiple items
- Reference issues and PRs
Footer:
- Breaking changes start with "BREAKING CHANGE:"
- Reference issues: "Closes #123", "Fixes #456", "Refs #789"
- Co-authors: "Co-authored-by: Name <email>"

主题行：
- 使用祈使语气（用“add”而非“added”或“adds”）
- 首字母无需大写
- 结尾不加句号
- 最多50个字符（软限制）
- 与正文之间用空行分隔
正文：
- 每行不超过72个字符
- 说明变更内容及原因，而非实现方式
- 多项内容使用项目符号
- 关联相关议题和拉取请求
页脚：
- 破坏性变更以“BREAKING CHANGE:”开头
- 关联议题：“Closes #123”、“Fixes #456”、“Refs #789”
- 共同作者：“Co-authored-by: Name <email>”

Branch Naming Conventions

分支命名约定

Format Pattern

格式模板

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

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

Branch Types

分支类型

Common prefixes:

```
feature/
```
or
```
feat/
```
- New features
```
fix/
```
or
```
bugfix/
```
- Bug fixes
```
hotfix/
```
- Urgent production fixes
```
release/
```
- Release preparation
```
docs/
```
- Documentation updates
```
refactor/
```
- Code refactoring
```
test/
```
- Test additions or fixes
```
chore/
```
- Maintenance tasks
```
experimental/
```
or
```
spike/
```
- Proof of concepts

常见前缀：

```
feature/
```
或
```
feat/
```
- 新功能分支
```
fix/
```
或
```
bugfix/
```
- Bug修复分支
```
hotfix/
```
- 紧急生产修复分支
```
release/
```
- 版本发布准备分支
```
docs/
```
- 文档更新分支
```
refactor/
```
- 代码重构分支
```
test/
```
- 测试新增或修复分支
```
chore/
```
- 维护任务分支
```
experimental/
```
或
```
spike/
```
- 概念验证分支

Examples

示例

bash

undefined

bash

undefined

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

undefined

experimental/graphql-api spike/performance-optimization

undefined

Branch Naming Rules

分支命名规则

Use hyphens for word separation (not underscores)
Lowercase only (avoid capitals)
Keep it short but descriptive (max 50 characters)
Include issue number when applicable
Avoid special characters except hyphens and forward slashes
No trailing slashes
Be consistent within your team

使用连字符分隔单词（不使用下划线）
全部小写（避免大写字母）
简短但具有描述性（最多50个字符）
适用时包含议题编号
避免特殊字符，仅允许连字符和斜杠
末尾不加斜杠
团队内部保持一致

Protected Branch Strategy

受保护分支策略

Main Branches

主要分支

main/master:

Production-ready code
Always deployable
Protected with required reviews
No direct commits
Merge only from release or hotfix branches

develop:

Integration branch for features
Pre-production testing
Protected with CI checks
Merge target for feature branches

staging:

Pre-production environment
QA testing branch
Mirror of production with new features

main/master：

生产就绪代码
始终可部署
启用必需评审保护
禁止直接提交
仅允许从release或hotfix分支合并

develop：

功能集成分支
预生产测试分支
启用CI检查保护
作为feature分支的合并目标

staging：

预生产环境分支
QA测试分支
与生产环境镜像一致，包含新功能

Protection Rules

保护规则

yaml

undefined

yaml

undefined

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

undefined

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

undefined

Semantic Versioning

语义化版本控制

Version Format

版本格式

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

Examples:

```
1.0.0
```
- Initial release
```
1.2.3
```
- Minor update with patches
```
2.0.0-alpha.1
```
- Pre-release alpha
```
1.5.0-rc.2+20240321
```
- Release candidate with build metadata

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

示例：

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

Version Increment Rules

版本递增规则

MAJOR (X.0.0):

Breaking changes
API incompatibilities
Major redesigns
Removal of deprecated features

MINOR (x.Y.0):

New features (backward compatible)
Deprecated features (still functional)
Substantial internal changes

PATCH (x.y.Z):

Bug fixes
Security patches
Performance improvements
Documentation updates

MAJOR（X.0.0）：

破坏性变更
API不兼容
重大重构
移除已废弃功能

MINOR（x.Y.0）：

新增向后兼容的功能
标记功能为废弃（仍可正常使用）
大量内部变更

PATCH（x.y.Z）：

Bug修复
安全补丁
性能优化
文档更新

Git Tags for Versions

Git版本标签

bash

undefined

bash

undefined

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"

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

undefined

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

undefined

Workflow Patterns

工作流模式

Git Flow

Branch structure:

```
main
```
- Production releases
```
develop
```
- Next release development
```
feature/*
```
- New features
```
release/*
```
- Release preparation
```
hotfix/*
```
- Emergency fixes

Feature workflow:

bash

undefined

分支结构：

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

功能分支工作流：

bash

undefined

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


**Release workflow:**
```bash

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


**版本发布工作流：**
```bash

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


**Hotfix workflow:**
```bash

git branch -d release/v1.2.0


**紧急修复工作流：**
```bash

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

undefined

git branch -d hotfix/critical-bug

undefined

GitHub Flow

Simplified workflow:

```
main
```
- Always deployable
```
feature/*
```
- All changes in feature branches

Workflow:

bash

undefined

简化工作流：

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

工作流步骤：

bash

undefined

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

undefined

undefined

Trunk-Based Development

主干开发模式

Single main branch:

Short-lived feature branches (< 2 days)
Frequent integration to main
Feature flags for incomplete features
Continuous integration

Workflow:

bash

undefined

单一主分支：

短生命周期功能分支（<2天）
频繁合并到主分支
使用功能标记管理未完成功能
持续集成

工作流步骤：

bash

undefined

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

undefined

undefined

Pull Request Conventions

拉取请求约定

PR Title Format

PR标题格式

Use Conventional Commits format:

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

使用Conventional Commits格式：

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

PR Description Template

PR描述模板

markdown

undefined

markdown

undefined

Summary

Brief description of changes and motivation.

Changes

Bullet list of specific changes
Reference architecture decisions
Note any breaking changes

Bullet list of specific changes
Reference architecture decisions
Note any breaking changes

Testing

Unit tests added/updated
Integration tests passed
Manual testing performed

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

Review Guidelines

评审指南

Reviewer checklist:

Code follows style guide
Commit messages follow conventions
Tests are comprehensive
Documentation is updated
No security vulnerabilities
Performance considerations addressed
Breaking changes are justified

Changelog Management

变更日志管理

Keep a Changelog Format

Keep a Changelog格式

markdown

undefined

markdown

undefined

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

User authentication with JWT tokens
API rate limiting middleware

User authentication with JWT tokens
API rate limiting middleware

Changed

Updated database schema for better performance

Updated database schema for better performance

Deprecated

Old authentication endpoint (use /api/v2/auth instead)

Old authentication endpoint (use /api/v2/auth instead)

Removed

Legacy XML API support

Legacy XML API support

Fixed

Memory leak in cache implementation
Race condition in concurrent requests

Memory leak in cache implementation
Race condition in concurrent requests

Security

Patch for SQL injection vulnerability

Patch for SQL injection vulnerability

[1.2.0] - 2024-03-15

Added

Real-time notifications system
User profile customization

Real-time notifications system
User profile customization

Fixed

Login redirect loop issue
Session timeout handling

Login redirect loop issue
Session timeout handling

[1.1.0] - 2024-02-01

Added

Search functionality
Export to CSV feature

Search functionality
Export to CSV feature

Changed

Improved UI responsiveness

undefined

Improved UI responsiveness

undefined

Automated Changelog

自动化变更日志

Use tools like:

```
conventional-changelog
```
- Generate changelog from commits
```
release-please
```
- Automated releases and changelog
```
semantic-release
```
- Fully automated version management

可使用以下工具：

```
conventional-changelog
```
- 从提交记录生成变更日志
```
release-please
```
- 自动化版本发布与变更日志生成
```
semantic-release
```
- 全自动化版本管理

Best Practices

最佳实践

Commit Often: Small, focused commits are easier to review and revert
Write Clear Messages: Future you will thank present you
One Concern Per Commit: Each commit should address one logical change
Test Before Committing: Ensure code works before committing
Reference Issues: Link commits to issue tracker
Review Your Own Changes: Use
```
git diff --staged
```
before committing
Keep History Clean: Rebase feature branches to keep linear history
Sign Your Commits: Use GPG signing for verified commits
Use .gitignore Properly: Never commit sensitive or generated files
Document Conventions: Keep team conventions in repository docs

频繁提交： 小型、聚焦的提交更易于评审和回滚
撰写清晰的消息： 未来的你会感谢现在的自己
每次提交单一关注点： 每个提交应解决一个逻辑变更
提交前测试： 确保代码可正常运行后再提交
关联议题： 将提交与议题追踪系统关联
自我评审变更： 提交前使用
```
git diff --staged
```
检查变更
保持历史清晰： 对功能分支进行变基以维持线性历史
签署提交： 使用GPG签名以验证提交
正确使用.gitignore： 绝不提交敏感文件或生成文件
记录约定： 将团队约定保存在仓库文档中

Team Workflow Examples

团队工作流示例

Small Team (2-5 developers)

小型团队（2-5人）

bash

undefined

bash

undefined

Simplified workflow

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

undefined

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

undefined

Medium Team (5-20 developers)

中型团队（5-20人）

bash

undefined

bash

undefined

Git Flow variant

Protected main and develop branches
Feature branches required
Release branches for versions
Hotfix workflow for emergencies
Squash merge for clean history

undefined

Protected main and develop branches
Feature branches required
Release branches for versions
Hotfix workflow for emergencies
Squash merge for clean history

undefined

Large Team (20+ developers)

大型团队（20+人）

bash

undefined

bash

undefined

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

undefined

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

undefined

Resources

资源

Additional guides and templates are available in the

assets/

directory:

```
templates/
```
- Commit message and PR templates
```
examples/
```
- Real-world workflow examples
```
tools/
```
- Git hooks and automation scripts

See

references/

directory for:

Conventional Commits specification
Semantic Versioning documentation
Git Flow and GitHub Flow guides
Keep a Changelog standards

更多指南和模板可在

assets/

目录中获取：

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

references/

目录包含：

Conventional Commits规范
语义化版本控制文档
Git Flow与GitHub Flow指南
Keep a Changelog标准

git-conventions

Original

Translation

Git Conventions Skill

Git 约定技能指南

When to Use

适用场景

Conventional Commits

Conventional Commits

Format

格式

Commit Types

提交类型

Examples

示例

Commit Message Rules

提交消息规则

Branch Naming Conventions

分支命名约定

Format Pattern

格式模板

Branch Types

分支类型

Examples

示例

Feature branches

Feature branches

Bug fix branches

Bug fix branches

Hotfix branches

Hotfix branches

Release branches

Release branches

Documentation branches

Documentation branches

Refactor branches

Refactor branches

Experimental branches

Experimental branches

Branch Naming Rules

分支命名规则

Protected Branch Strategy

受保护分支策略

Main Branches

主要分支

Protection Rules

保护规则

Example GitHub branch protection

Example GitHub branch protection

Semantic Versioning

语义化版本控制

Version Format

版本格式

Version Increment Rules

版本递增规则

Git Tags for Versions

Git版本标签

Create annotated tag

Create annotated tag

Push tags to remote

Push tags to remote

Push all tags

Push all tags

Create pre-release tag

Create pre-release tag

Delete tag

Delete tag

Workflow Patterns

工作流模式

Git Flow

Git Flow

Start feature

Start feature

Work on feature

Work on feature

Finish feature

Finish feature

Start release

Start release

Prepare release (bump version, update changelog)