conventional-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Conventional Commit

Follow the Conventional Commits specification for all commits.

所有提交均需遵循Conventional Commits 规范。

Preconditions

前置条件

Validate branch

验证分支

Run

git rev-parse --abbrev-ref HEAD

If on

main

master

, stop and ask the user to create a feature branch.

Branch names should follow:

<TICKET_PREFIX>-<number>-<kebab-case-description>

(e.g.,

ENG-1333-migrate-review-flow

). If invalid, ask the user to rename the branch.

执行

git rev-parse --abbrev-ref HEAD

。

若当前处于

main

或

master

分支，请停止操作并要求用户创建功能分支。

分支名称应遵循：

<TICKET_PREFIX>-<number>-<kebab-case-description>

（例如：

ENG-1333-migrate-review-flow

）。若命名无效，请要求用户重命名分支。

Conventional Commits Spec

Conventional Commits 规范

The commit message format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

提交信息格式：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types (required)

类型（必填）

Type	Purpose
`feat`	A new feature (correlates with MINOR in SemVer)
`fix`	A bug fix (correlates with PATCH in SemVer)
`docs`	Documentation only changes
`style`	Changes that do not affect meaning (whitespace, formatting)
`refactor`	Code change that neither fixes a bug nor adds a feature
`perf`	Code change that improves performance
`test`	Adding or correcting tests
`build`	Changes to build system or external dependencies
`ci`	Changes to CI configuration files and scripts
`chore`	Other changes that don't modify src or test files

类型	用途
`feat`	新增功能（对应SemVer中的MINOR版本）
`fix`	修复Bug（对应SemVer中的PATCH版本）
`docs`	仅修改文档
`style`	不影响代码含义的更改（空白字符、格式调整等）
`refactor`	既不修复Bug也不新增功能的代码变更
`perf`	提升性能的代码变更
`test`	添加或修正测试
`build`	修改构建系统或外部依赖
`ci`	修改CI配置文件和脚本
`chore`	其他不修改源码或测试文件的变更

Scope (optional)

范围（可选）

A noun describing the section of codebase affected, in parentheses:

feat(parser): add ability to parse arrays

```
fix(auth): resolve token expiration bug
```

用于描述受影响代码库部分的名词，放在括号中：

feat(parser): add ability to parse arrays

```
fix(auth): resolve token expiration bug
```

Breaking Changes

破坏性变更

Append

after type/scope OR add

BREAKING CHANGE:

footer:

feat(api)!: remove deprecated endpoints

BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.

Breaking changes correlate with MAJOR in SemVer.

在类型/范围后追加

或添加

BREAKING CHANGE:

页脚：

feat(api)!: remove deprecated endpoints

BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.

破坏性变更对应SemVer中的MAJOR版本。

Steps

步骤

Review current state

bash

git status
git diff
git log -1 --oneline

Group changes logically - prefer multiple small commits over one large commit

Create commits

For each logical group:

Stage relevant files or hunks
Commit using Conventional Commit format

Option A: Use git commit directly (recommended for agents):

bash

git commit -m "feat(auth): add OAuth2 support"

Multi-line with body:

bash

git commit -m "feat(api): add pagination to list endpoints" \
  -m "Implements cursor-based pagination for all list endpoints." \
  -m "BREAKING CHANGE: Response format changed from array to object with data/meta keys."

Option B: Use

git-cz

non-interactive mode (streamich/git-cz, not standard cz):

bash

npx git-cz --non-interactive --type=feat --scope=auth --subject="add OAuth2 support"

With body/breaking changes:

bash

npx git-cz --non-interactive \
  --type=feat \
  --scope=api \
  --subject="add pagination to list endpoints" \
  --body="Implements cursor-based pagination for all list endpoints" \
  --breaking="Response format changed from array to object with data/meta keys"

Note: The standard
npx cz
(commitizen/cz-cli) is interactive-only and cannot be used by agents. Use
git commit
or
npx git-cz --non-interactive
instead.

Push the branch

bash

git push -u origin HEAD  # if no upstream
git push                 # otherwise

查看当前状态

bash

git status
git diff
git log -1 --oneline

按逻辑分组变更——优先选择多个小型提交而非一个大型提交

创建提交

针对每个逻辑分组：

暂存相关文件或代码块
使用Conventional Commit格式提交

选项A：直接使用git commit（推荐Agent使用）：

bash

git commit -m "feat(auth): add OAuth2 support"

带正文的多行提交：

bash

git commit -m "feat(api): add pagination to list endpoints" \
  -m "Implements cursor-based pagination for all list endpoints." \
  -m "BREAKING CHANGE: Response format changed from array to object with data/meta keys."

选项B：使用

git-cz

非交互模式（streamich/git-cz，非标准cz）：

bash

npx git-cz --non-interactive --type=feat --scope=auth --subject="add OAuth2 support"

带正文/破坏性变更的提交：

bash

npx git-cz --non-interactive \
  --type=feat \
  --scope=api \
  --subject="add pagination to list endpoints" \
  --body="Implements cursor-based pagination for all list endpoints" \
  --breaking="Response format changed from array to object with data/meta keys"

注意：标准的
npx cz
（commitizen/cz-cli）仅支持交互式操作，无法被Agent使用。请使用
git commit
或
npx git-cz --non-interactive
替代。

推送分支

bash

git push -u origin HEAD  # 若无上游分支
git push                 # 若已有上游分支

conventional-commit

Original

Translation

Conventional Commit

Conventional Commit

Preconditions

前置条件

Validate branch

验证分支

Conventional Commits Spec

Conventional Commits 规范

Types (required)

类型（必填）

Scope (optional)

范围（可选）

Breaking Changes

破坏性变更

Steps

步骤

Commit Message Guidelines

提交信息指南

Notes

注意事项

References

参考资料