SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillschinese-commit-conventions

chinese-commit-conventions

Coding & development

View repository

Updated 10-15 08:33

About this skill

Chinese Git Commit Conventions

1. Conventional Commits Chinese Adaptation

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 Bug fix Fix blank screen issue on login page
docs Documentation changes Update API interface documentation
style Code formatting (does not affect logic) Adjust indentation, add missing semicolons
refactor Refactoring (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/tool/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

  • type retains English keywords (good toolchain compatibility)
  • scope and description use Chinese
  • body uses a complete Chinese description

2. Chinese commit message template

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

<body>

<footer>

Complete Example

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

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

Closes #128

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

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

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

Closes #256

3. Subject Line Conventions

Format

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

Rules

  • type: Required, selected from the type table above
  • scope: Optional, indicates the scope of impact; use Chinese module names
    • 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 Conventions

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

Writing Key Points

  • Explainwhythis change is being made (background/reason)
  • Explainhowit is done (technical approach summary)
  • Explainimpact scope(which modules and interfaces are affected)
  • Each line should not exceed 72 characters (about 36 Chinese characters)
  • Leave one blank line between the body and the title

Body Template

<改动背景和原因>

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

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

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: add an exclamation mark after type

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

Team Conventions

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

6. Issue Linking

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 Syntax

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

7. Changelog Automatic 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 the commit-msg Hook

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

Configure the 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 Specification Checklist

Self-Check Before Committing

  • Whether the type is correctly selected (feat/fix/docs/...)
  • Whether the scope accurately describes the affected module
  • Whether the subject is a verb-object phrase and does not exceed 50 characters
  • Whether the period at the end of the subject has been removed
  • Whether the body explains the reason for the change and the approach
  • Whether incompatible changes are marked with BREAKING CHANGE
  • Whether the related Issue has been linked
  • Whether one commit does only one thing (atomicity)

Team Implementation Steps

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

Frequently Asked Questions

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

Q: Should scope use 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 specification consistency be ensured during multi-person collaboration? A: Rely on tools rather than self-discipline. With husky + commitlint configured, commits that do not conform to the specification will be blocked.