SuperAPI AI Directory

chinese-commit-conventions

Coding & development

View repository

Updated 10-16 09:09

About this skill

Chinese Git Commit Convention

1. Chinese adaptation of Conventional Commits

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

Type definition

Type Description Example scenario
feat New feature Add user registration module
fix Fix defect Fix white screen issue on login page
docs Documentation change Update API interface documentation
style Code formatting (does not affect logic) Adjust indentation, add missing semicolons
refactor Refactor (neither new feature nor fix) Split an overly long service class
perf Performance optimization Optimize homepage list query speed
test Test related Add unit tests for the user module
chore Build/tooling/dependency changes Upgrade webpack to v5
ci Continuous integration configuration Modify GitHub Actions workflow
revert Revert commit Revert the login refactor in v2.1.0

Principles

  • Keep type as an English keyword (good toolchain compatibility)
  • Use Chinese for scope and description
  • Use Chinese for the body to describe fully

2. Chinese commit message template

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

<body>

<footer>

Complete example

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

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

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

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

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

Closes #256

3. Subject line convention

Format

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

Rules

  • type: Required, choose from the type table above
  • scope: Optional, indicates the scope of impact, use a Chinese module name
    • Example:用户模块、订单、支付、基础组件
  • description: Required, a brief Chinese description, no more than 50 characters
    • Use verb-object phrases: "Add xxx", "Fix xxx", "Optimize xxx"
    • Do not end with a period
    • Do not write meaningless descriptions like "modified the code"

Good example

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

Counterexample

# 以下写法应避免
fix: 修了一个 bug
feat: 更新代码
chore: 改了点东西

4. Body writing convention

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

Writing points

  • DescriptionWhythis change needs to be made (background/reason)
  • DescriptionHowit is done (summary of the technical approach)
  • DescriptionScope of impact(which modules and interfaces are affected)
  • Each line must not exceed 72 characters (about 36 Chinese characters)
  • Leave a blank line between the body and the title

Body template

<改动背景和原因>

技术方案:
- <方案要点 1>
- <方案要点 2>

影响范围:<受影响的模块或服务>

5. Breaking Changes notation

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

Format 1: footer notation

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

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

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

Format 2: add an exclamation mark after type

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

Team conventions

  • Involves database table structure changes -> must note BREAKING CHANGE
  • Involves changes to public API parameters/return values -> must note
  • Involves changes to configuration file format -> must note
  • When noting, the migration method or upgrade steps must be stated

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 Usage

# footer 中关联多个平台
Closes #128
Jira: PROJ-456
禅道: #789

7. Changelog Auto-generation Configuration

Install conventional-changelog

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

package.json Scripts

{
  "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

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

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

commitlint.config.js

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],
    // 允许中文字符,关闭 subject-case 限制
    'subject-case': [0],
    // 关闭 header-max-length 或放宽(中文占宽较大)
    '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

npm install -D husky lint-staged
npx husky init

Configure commit-msg Hook

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

Configure pre-commit Hook

# .husky/pre-commit
npx lint-staged

lint-staged Configuration (package.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)

npm install -D commitizen cz-conventional-changelog

# package.json 中添加
{
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  },
  "scripts": {
    "commit": "cz"
  }
}

Run npm run commit to enter the interactive commit guide.

10. Team Standards Checklist

Self-check Before Committing

  • 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?
  • Has the period been removed from the end of the subject?
  • Does the body explain the reason for the change and the solution?
  • Are breaking changes marked with BREAKING CHANGE?
  • Are related Issues linked?
  • Does one commit do only one thing (atomicity)?

Team Implementation Steps

  1. Toolchain Configuration: Configure commitlint + husky according to the above steps to make the standards enforceable
  2. Template Sharing: Commit .commitlintrc、.husky/ and other configurations to the repository
  3. Team Training: Organize a 15-minute standards briefing and demonstrate tool usage
  4. Code Review: Focus on commit message quality during review
  5. Continuous Iteration: Review standards implementation quarterly and adjust based on team feedback

FAQ

Q: How should spaces be handled when mixing Chinese and English? A: Add a space between Chinese and English/numbers, e.g., "添加 Redis 缓存".

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

Q: How can standards consistency be ensured during multi-person collaboration? A: Rely on tools rather than self-discipline. With husky + commitlint configured, commits that do not meet the standards will be blocked.