Chinese Git Commit Specification

1. Chinese Adaptation of Conventional Commits

Based on the Conventional Commits 1.0.0 standard, adapted to the actual usage habits of Chinese teams.

Type Definitions

Type	Description	Example Scenarios
`feat`	New Feature	Add user registration module
`fix`	Bug Fix	Fix white screen issue on login page
`docs`	Documentation Change	Update API documentation
`style`	Code Formatting (no logic impact)	Adjust indentation, add missing semicolons
`refactor`	Refactoring (not new feature or bug fix)	Split overly long service classes
`perf`	Performance Optimization	Optimize homepage list query speed
`test`	Testing-related	Add unit tests for user module
`chore`	Build/Tool/Dependency Change	Upgrade webpack to v5
`ci`	CI Configuration	Modify GitHub Actions workflow
`revert`	Revert Commit	Revert login refactor in v2.1.0

Principles

Keep English keywords for
```
type
```
(good compatibility with toolchains)
Use Chinese for
```
scope
```
and
```
description
```
Use Chinese for detailed description in
```
body
```

2. Chinese Commit Message Template

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

<body>

<footer>

Complete Examples

feat(用户模块): 添加手机号一键登录功能

- 接入运营商一键登录 SDK
- 支持移动、联通、电信三网
- 登录失败自动降级到短信验证码

Closes #128

fix(订单): 修复并发下单导致库存超卖的问题

在高并发场景下，原有的库存扣减逻辑存在竞态条件。
改用 Redis 分布式锁 + 数据库乐观锁双重保障。

影响范围：订单服务、库存服务
测试确认：已通过 500 并发压测验证

Closes #256

3. Subject Line Specifications

Format

<type>(<scope>): <description>

Rules

type: Required, select from the type table above
scope: Optional, indicates the impact scope, use Chinese module names
- Examples:
```
用户模块
```
  ,
```
订单
```
  ,
```
支付
```
  ,
```
基础组件
```
description: Required, brief Chinese description, no more than 50 characters
- Use verb-object phrases: "Add xxx", "Fix xxx", "Optimize xxx"
- No period at the end
- Avoid meaningless descriptions like "Modified code"

Good Examples

feat(权限): 添加基于 RBAC 的细粒度权限控制
fix(支付): 修复微信支付回调签名验证失败的问题
perf(列表页): 优化大数据量表格的虚拟滚动渲染
refactor(网关): 将单体网关拆分为独立微服务

Bad Examples

# Avoid the following writing styles
fix: 修了一个 bug
feat: 更新代码
chore: 改了点东西

4. Body Writing Specifications

The Body is used to explain the motivation, solution, and impact of the change in detail.

Key Writing Points

Explain why the change is made (background/reason)
Explain how it is implemented (technical solution summary)
Explain impact scope (which modules or services are affected)
No more than 72 characters per line (about 36 Chinese characters)
Leave a blank line between the body and the subject

Body Template

<Change background and reason>

Technical Solution:
- <Solution point 1>
- <Solution point 2>

Impact Scope: <Affected modules or services>

5. Breaking Changes Annotation

When a commit contains incompatible changes, it must be annotated in the footer.

Format 1: Footer Annotation

feat(接口): 重构用户信息返回结构

将用户接口返回的扁平结构改为嵌套结构，前端需同步调整字段取值路径。

BREAKING CHANGE: /api/user/info 返回结构变更
- avatar 字段移入 profile 对象
- 移除已废弃的 nickname 字段，统一使用 displayName

Format 2: Exclamation Mark After Type

feat(接口)!: 重构用户信息返回结构

Team Agreements

Involving database table structure changes -> Must annotate BREAKING CHANGE
Involving public API parameter/return value changes -> Must annotate
Involving configuration file format changes -> Must annotate
When annotating, specify migration methods or upgrade steps

6. Issue Association

GitHub Format

Closes #128
Refs #129, #130

Gitee Format

Closes #I5ABC1
相关需求: https://gitee.com/org/repo/issues/I5ABC1

Coding Format

关联 Coding 缺陷 #12345
fixed=project-2024/issues/678

General Writing

# Associate multiple platforms in footer
Closes #128
Jira: PROJ-456
禅道: #789

7. Changelog Automatic Generation Configuration

Install conventional-changelog

bash

npm install -D conventional-changelog-cli conventional-changelog-conventionalcommits

package.json Scripts

json

{
  "scripts": {
    "changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s",
    "changelog:all": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s -r 0",
    "release": "standard-version"
  }
}

.versionrc.js Chinese Configuration

javascript

module.exports = {
  types: [
    { type: 'feat', section: '新功能' },
    { type: 'fix', section: '缺陷修复' },
    { type: 'perf', section: '性能优化' },
    { type: 'refactor', section: '代码重构' },
    { type: 'docs', section: '文档更新' },
    { type: 'test', section: '测试' },
    { type: 'chore', section: '构建/工具', hidden: true },
    { type: 'ci', section: '持续集成', hidden: true },
    { type: 'style', section: '代码格式', hidden: true }
  ],
  commitUrlFormat: '{{host}}/{{owner}}/{{repository}}/commit/{{hash}}',
  compareUrlFormat: '{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}'
}

8. commitlint Chinese Configuration

Installation

bash

npm install -D @commitlint/cli @commitlint/config-conventional

commitlint.config.js

javascript

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'chore', 'ci', 'revert'
    ]],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'subject-empty': [2, 'never'],
    'subject-max-length': [2, 'always', 100],
    // Allow Chinese characters, disable subject-case restriction
    'subject-case': [0],
    // Disable header-max-length or relax it (Chinese occupies more width)
    'header-max-length': [2, 'always', 120],
    'body-max-line-length': [1, 'always', 200],
    'footer-max-line-length': [1, 'always', 200]
  },
  prompt: {
    messages: {
      type: '选择提交类型:',
      scope: '输入影响范围（可选）:',
      subject: '填写简短描述:',
      body: '填写详细描述（可选，使用 "|" 换行）:',
      breaking: '列出不兼容变更（可选）:',
      footer: '关联的 Issue（可选，例如 #123）:',
      confirmCommit: '确认提交以上信息？'
    }
  }
}

9. husky + lint-staged Integration

Installation and Initialization

bash

npm install -D husky lint-staged
npx husky init

Configure commit-msg Hook

bash

# .husky/commit-msg
npx --no -- commitlint --edit "$1"

Configure pre-commit Hook

bash

# .husky/pre-commit
npx lint-staged

lint-staged Configuration (package.json)

json

{
  "lint-staged": {
    "*.{js,ts,jsx,tsx,vue}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss,less}": [
      "stylelint --fix",
      "prettier --write"
    ],
    "*.md": [
      "prettier --write"
    ]
  }
}

Interactive Commit (Optional)

bash

npm install -D commitizen cz-conventional-changelog

# Add to package.json
{
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  },
  "scripts": {
    "commit": "cz"
  }
}

Run

npm run commit

to start the interactive commit guide.

10. Team Specification Checklist

Pre-commit Self-check

Is the
```
type
```
correctly selected (feat/fix/docs/...)
Does the
```
scope
```
accurately describe the affected module
Is the
```
subject
```
a verb-object phrase and no more than 50 characters
Is the period removed from the end of the
```
subject
```
Does the
```
body
```
explain the change reason and solution
Are incompatible changes annotated with BREAKING CHANGE
Are related Issues associated
Does one commit only do one thing (atomicity)

Team Implementation Steps

Toolchain Configuration: Configure commitlint + husky according to the above steps to make the specification enforceable
Template Sharing: Submit configurations like
```
.commitlintrc
```
,
```
.husky/
```
to the repository
Team Training: Organize a 15-minute specification briefing to demonstrate tool usage
Code Review: Focus on commit message quality during Review
Continuous Iteration: Review the specification implementation every quarter and adjust based on team feedback

Common Questions

Q: How to handle spaces in mixed Chinese-English content? A: Add a space between Chinese and English/numbers, e.g., "添加 Redis 缓存".

Q: Should scope be in Chinese or English? A: Unify within the team. Chinese is recommended (good readability), but disable scope-case check in commitlint.

Q: How to ensure consistent specifications in multi-person collaboration? A: Rely on tools rather than self-discipline. Configure husky + commitlint, and non-compliant commits will be blocked.

chinese-commit-conventions

NPX Install

Tags

SKILL.md Content (Chinese)

Chinese Git Commit Specification

1. Chinese Adaptation of Conventional Commits

Type Definitions

Principles

2. Chinese Commit Message Template

Complete Examples

3. Subject Line Specifications

Format

Rules

Good Examples

Bad Examples

4. Body Writing Specifications

Key Writing Points

Body Template

5. Breaking Changes Annotation

Format 1: Footer Annotation

Format 2: Exclamation Mark After Type

Team Agreements

6. Issue Association

GitHub Format

Gitee Format

Coding Format

General Writing

7. Changelog Automatic Generation Configuration

Install conventional-changelog

package.json Scripts

.versionrc.js Chinese Configuration

8. commitlint Chinese Configuration

Installation

commitlint.config.js

9. husky + lint-staged Integration

Installation and Initialization

Configure commit-msg Hook

Configure pre-commit Hook

lint-staged Configuration (package.json)

Interactive Commit (Optional)

10. Team Specification Checklist

Pre-commit Self-check

Team Implementation Steps

Common Questions