Back to Details

conventional-commit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Conventional Commit Messages

约定式提交信息

Follow these conventions when creating commits.
创建提交时请遵循以下规范。

Prerequisites

前提条件

Before committing, ensure you're working on a feature branch, not the main branch.
bash
undefined
提交前，请确保你在功能分支而非主分支上工作。
bash
undefined

Check current branch

检查当前分支

git branch --show-current

If you're on `main` or `master`, create a new branch first:

```bash
git branch --show-current

如果你在`main`或`master`分支上，请先创建新分支：

```bash

Create and switch to a new branch

创建并切换到新分支

git checkout -b <type>/<short-description>

Branch naming should follow the pattern: `<type>/<short-description>` where type matches the commit type (e.g., `feat/add-user-auth`, `fix/null-pointer-error`, `refactor/extract-validation`).
git checkout -b <type>/<short-description>

分支命名应遵循`<type>/<short-description>`格式，其中type与提交类型匹配（例如`feat/add-user-auth`、`fix/null-pointer-error`、`refactor/extract-validation`）。

Format

格式

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

<body>

<footer>
The header is required. Scope is optional. All lines must stay under 100 characters.
<type>(<scope>): <subject>

<body>

<footer>
标题为必填项，作用域为可选项。所有行长度不得超过100字符。

Commit Types

提交类型

TypePurpose
build
Build system or CI changes
chore
Routine maintenance tasks
ci
Continuous integration configuration
deps
Dependency updates
docs
Documentation changes
feat
New feature
fix
Bug fix
perf
Performance improvement
refactor
Code refactoring (no behavior change)
revert
Revert a previous commit
style
Code style and formatting
test
Tests added, updated or improved
类型用途
build
构建系统或CI配置变更
chore
日常维护任务
ci
持续集成配置变更
deps
依赖更新
docs
文档变更
feat
新增功能
fix
修复Bug
perf
性能优化
refactor
代码重构（无行为变更）
revert
回滚之前的提交
style
代码风格与格式调整
test
测试用例新增、更新或改进

Subject Line Rules

主题行规则

  • Use imperative, present tense: "Add feature" not "Added feature"
  • Capitalize the first letter
  • No period at the end
  • Maximum 70 characters
  • 使用祈使句、现在时态：例如用“Add feature”而非“Added feature”
  • 首字母大写
  • 句末不加句号
  • 最长70字符

Body Guidelines

正文指南

  • Explain what and why, not how
  • Use imperative mood and present tense
  • Include motivation for the change
  • Contrast with previous behavior when relevant
  • 说明做了什么和为什么做，无需说明怎么做
  • 使用祈使句和现在时态
  • 包含变更的动机
  • 必要时与之前的行为进行对比

Conventional Commits

约定式提交规范

The commit contains the following structural elements, to communicate intent to the consumers of your library:
  • fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
  • feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
  • BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
  • types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others.
  • footers other than BREAKING CHANGE: <description> may be provided and follow a convention similar to git trailer format.
提交包含以下结构化元素，用于向库的使用者传达意图：
  • fix：此类提交用于修补代码库中的Bug（对应语义化版本中的PATCH版本）。
  • feat：此类提交用于向代码库中引入新功能（对应语义化版本中的MINOR版本）。
  • BREAKING CHANGE：包含BREAKING CHANGE:页脚，或在类型/作用域后添加!的提交，表示引入了破坏性API变更（对应语义化版本中的MAJOR版本）。破坏性变更可以属于任何类型的提交。
  • 除fix:和feat:之外的其他类型也是允许的，例如@commitlint/config-conventional（基于Angular规范）推荐使用build:、chore:、ci:、docs:、style:、refactor:、perf:、test:等类型。
  • 除BREAKING CHANGE: <description>之外的其他页脚也可以提供，并且遵循与Git trailer格式类似的规范。

Examples

示例

Simple fix

简单修复

fix(api): Handle null response in user endpoint

The user API could return null for deleted accounts, causing a crash
in the dashboard. Add null check before accessing user properties.
fix(api): Handle null response in user endpoint

The user API could return null for deleted accounts, causing a crash
in the dashboard. Add null check before accessing user properties.

Feature with scope

带作用域的功能

feat(alerts): Add Slack thread replies for alert updates

When an alert is updated or resolved, post a reply to the original
Slack thread instead of creating a new message. This keeps related
notifications grouped together.
feat(alerts): Add Slack thread replies for alert updates

When an alert is updated or resolved, post a reply to the original
Slack thread instead of creating a new message. This keeps related
notifications grouped together.

Refactor

重构

refactor: Extract common validation logic to shared module

Move duplicate validation code from three endpoints into a shared
validator class. No behavior change.
refactor: Extract common validation logic to shared module

Move duplicate validation code from three endpoints into a shared
validator class. No behavior change.

Breaking change

破坏性变更

feat(api)!: Remove deprecated v1 endpoints

Remove all v1 API endpoints that were deprecated in version 23.1.
Clients should migrate to v2 endpoints.

BREAKING CHANGE: v1 endpoints no longer available
feat(api)!: Remove deprecated v1 endpoints

Remove all v1 API endpoints that were deprecated in version 23.1.
Clients should migrate to v2 endpoints.

BREAKING CHANGE: v1 endpoints no longer available

Revert Format

回滚格式

revert: feat(api): Add new endpoint

This reverts commit abc123def456.

Reason: Caused performance regression in production.
revert: feat(api): Add new endpoint

This reverts commit abc123def456.

Reason: Caused performance regression in production.

Principles

原则

  • Each commit should be a single, stable change
  • Commits should be independently reviewable
  • The repository should be in a working state after each commit
  • 每个提交应对应单一、稳定的变更
  • 提交应可独立评审
  • 每次提交后仓库应处于可工作状态

References

参考资料