Chinese Git Commit Guidelines

1. Chinese Adaptation of Conventional Commits

Based on Conventional Commits 1.0.0 specification, adapted for 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 interface docs
`style`	Code Format (no logic impact)	Adjust indentation, add semicolons
`refactor`	Refactoring (not new feature/fix)	Split overly long service class
`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
```
(better 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(User Module): Add one-click login via phone number

- Integrated carrier one-click login SDK
- Supports China Mobile, China Unicom, China Telecom
- Automatically downgrade to SMS verification code on login failure

Closes #128

fix(Order): Fix inventory oversold issue caused by concurrent orders

In high-concurrency scenarios, the original inventory deduction logic had race conditions.
Adopted dual protection of Redis distributed lock + database optimistic lock.

Affected Scope: Order Service, Inventory Service
Test Verification: Passed 500 concurrent pressure tests

Closes #256

3. Subject Line Guidelines

Format

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

Rules

type: Required, select from the type table above
scope: Optional, indicates affected scope, use Chinese module names
- Examples:
```
User Module
```
  ,
```
Order
```
  ,
```
Payment
```
  ,
```
Basic Components
```
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(Permission): Add fine-grained permission control based on RBAC
fix(Payment): Fix WeChat Pay callback signature verification failure issue
perf(List Page): Optimize virtual scrolling rendering for large-data tables
refactor(Gateway): Split monolithic gateway into independent microservices

Bad Examples

# Avoid the following
fix: Fixed a bug
feat: Updated code
chore: Changed something

4. Body Writing Guidelines

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's done (technical solution summary)
Explain affected scope (which modules/interfaces are impacted)
No more than 72 characters per line (about 36 Chinese characters)
Leave a blank line between body and subject

Body Template

<Change background and reason>

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

Affected Scope: <Impacted modules or services>

5. Breaking Changes Marking

When a commit contains incompatible changes, it must be marked in the

footer

Format 1: Footer Marking

feat(API): Refactor user information return structure

Changed the flat structure returned by the user API to a nested structure; front-end needs to adjust field access paths accordingly.

BREAKING CHANGE: /api/user/info return structure changed
- avatar field moved into profile object
- Removed deprecated nickname field, unified use of displayName

Format 2: Add Exclamation Mark After Type

feat(API)!: Refactor user information return structure

Team Agreements

Database table structure changes -> Must mark BREAKING CHANGE
Public API parameter/return value changes -> Must mark
Configuration file format changes -> Must mark
Must include migration methods or upgrade steps when marking

6. Issue Association

GitHub Format

Closes #128
Refs #129, #130

Gitee Format

Closes #I5ABC1
Related Requirement: https://gitee.com/org/repo/issues/I5ABC1

Coding Format

Link Coding Defect #12345
fixed=project-2024/issues/678

General Writing

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

7. Changelog Auto-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: 'New Features' },
    { type: 'fix', section: 'Bug Fixes' },
    { type: 'perf', section: 'Performance Optimizations' },
    { type: 'refactor', section: 'Code Refactoring' },
    { type: 'docs', section: 'Documentation Updates' },
    { type: 'test', section: 'Testing' },
    { type: 'chore', section: 'Build/Tools', hidden: true },
    { type: 'ci', section: 'Continuous Integration', hidden: true },
    { type: 'style', section: 'Code Formatting', 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 or relax header-max-length (Chinese characters take 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: 'Select commit type:',
      scope: 'Enter affected scope (optional):',
      subject: 'Enter brief description:',
      body: 'Enter detailed description (optional, use "|" for line breaks):',
      breaking: 'List incompatible changes (optional):',
      footer: 'Associated Issues (optional, e.g., #123):',
      confirmCommit: 'Confirm the above commit information?'
    }
  }
}

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 enter interactive commit guidance.

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 there no period at the end of the
```
subject
```
Does the
```
body
```
explain the change reason and solution
Are incompatible changes marked with BREAKING CHANGE
Are related Issues associated
Does one commit only do one thing (atomicity)

Team Implementation Steps

Toolchain Configuration: Configure commitlint + husky as per the above steps to make the specification enforceable
Template Sharing: Commit 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 reviews
Continuous Iteration: Review specification implementation quarterly and adjust based on team feedback

Frequently Asked Questions

Q: How to handle spaces when mixing Chinese and English? A: Add a space between Chinese and English/numbers, e.g., "Add Redis cache".

Q: Should
scope
be in Chinese or English? A: Just keep it consistent within the team. Chinese is recommended (better readability), but you need to disable the scope-case check in commitlint.

Q: How to ensure consistent specifications during collaborative work? A: Rely on tools rather than self-discipline. Configure husky + commitlint properly, and commits that don't meet the specifications will be blocked.

chinese-commit-conventions

NPX Install

Tags

SKILL.md Content (Chinese)

Chinese Git Commit Guidelines

1. Chinese Adaptation of Conventional Commits

Type Definitions

Principles

2. Chinese Commit Message Template

Complete Examples

3. Subject Line Guidelines

Format

Rules

Good Examples

Bad Examples

4. Body Writing Guidelines

Key Writing Points

Body Template

5. Breaking Changes Marking

Format 1: Footer Marking

Format 2: Add Exclamation Mark After Type

Team Agreements

6. Issue Association

GitHub Format

Gitee Format

Coding Format

General Writing

7. Changelog Auto-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

Frequently Asked Questions