Back to Details

conventional-commits

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Conventional Commits

Conventional Commits

Structured commit message format for version control that provides clear, readable project history.
一种用于版本控制的结构化提交消息格式，可提供清晰、易读的项目历史。

Overview

概述

The Conventional Commits specification provides:
  • Automated changelog generation - Tools can parse commits to generate CHANGELOG.md
  • Semantic versioning - Commit types map to version bumps (feat → minor, breaking → major)
  • Clear project history - Standardized format makes git log readable
  • Automated releases - CI/CD can trigger releases based on commit types
Conventional Commits规范提供以下功能：
  • 自动生成变更日志 - 工具可解析提交内容来生成CHANGELOG.md
  • 语义化版本控制 - 提交类型对应版本更新（feat → 次版本号，破坏性变更 → 主版本号）
  • 清晰的项目历史 - 标准化格式让git log更易读
  • 自动化发布 - CI/CD可根据提交类型触发发布

Quick Reference

快速参考

TypeUse ForVersion Bump
feat
New featureMINOR
fix
Bug fixPATCH
docs
Documentation onlyPATCH
style
Formatting, no logic changePATCH
refactor
Code restructuring, no behavior changePATCH
perf
Performance improvementPATCH
test
Adding or updating testsPATCH
build
Build system or dependenciesPATCH
ci
CI/CD configurationPATCH
chore
Maintenance, no user-facing changePATCH
revert
Revert a previous commitPATCH
类型适用场景版本更新
feat
新功能MINOR
fix
Bug修复PATCH
docs
仅文档更新PATCH
style
代码格式化，无逻辑变更PATCH
refactor
代码重构，无行为变更PATCH
perf
性能优化PATCH
test
添加或更新测试PATCH
build
构建系统或依赖更新PATCH
ci
CI/CD配置变更PATCH
chore
维护工作，无用户可见变更PATCH
revert
回滚之前的提交PATCH

Format

格式

text
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
Rules:
  • Type is required
  • Scope is optional - use parenthesized section affected: 
    (api)
    , 
    auth)
    , 
    parser)
  • Description is required
  • Keep description concise, imperative mood, lowercase, no trailing period
  • Body and footer are optional
  • Separate subject from body with blank line
  • Wrap body at 72 characters
text
<type>[可选范围]: <描述>

[可选正文]

[可选页脚]
规则：
  • 类型为必填项
  • 范围为可选项 - 使用括号标注受影响的模块：
    (api)
    、
    (auth)
    、
    (parser)
  • 描述为必填项
  • 描述需简洁、使用祈使语气、小写、结尾无句号
  • 正文和页脚为可选项
  • 主题与正文之间用空行分隔
  • 正文每行不超过72个字符

Examples

示例

text
feat: add user authentication

Implement JWT-based authentication with login/logout endpoints.
Includes password hashing and session management.

Closes: #123
text
fix(api): handle null response from server

Previous implementation crashed when server returned null.
Now returns empty result set.

Assisted-by: GLM 4.6 via Claude Code
text
feat(storage)!: change bucket listing API

BREAKING CHANGE: bucket list now returns async iterator
instead of array. Update all callers to use for-await.
text
refactor(core): simplify error handling

Consolidate duplicate error handlers into single utility.
No behavior changes - internal cleanup only.
text
revert: feat(auth): add OAuth support

This reverts commit 8b5a1c2. OAuth provider changed
their API and we need to redesign integration.
text
feat: add user authentication

Implement JWT-based authentication with login/logout endpoints.
Includes password hashing and session management.

Closes: #123
text
fix(api): handle null response from server

Previous implementation crashed when server returned null.
Now returns empty result set.

Assisted-by: GLM 4.6 via Claude Code
text
feat(storage)!: change bucket listing API

BREAKING CHANGE: bucket list now returns async iterator
instead of array. Update all callers to use for-await.
text
refactor(core): simplify error handling

Consolidate duplicate error handlers into single utility.
No behavior changes - internal cleanup only.
text
revert: feat(auth): add OAuth support

This reverts commit 8b5a1c2. OAuth provider changed
their API and we need to redesign integration.

Breaking Changes

破坏性变更

Indicate breaking changes in two ways:
Option 1: Add 
!
after type/scope
text
feat(api)!: remove deprecated endpoint
Option 2: Add 
BREAKING CHANGE:
footer
text
feat(api): remove deprecated endpoint

BREAKING CHANGE: endpoint no longer exists. Use newEndpoint instead.
有两种方式标记破坏性变更：
方式1: 在类型/范围后添加
!
text
feat(api)!: remove deprecated endpoint
方式2: 添加
BREAKING CHANGE:
页脚
text
feat(api): remove deprecated endpoint

BREAKING CHANGE: endpoint no longer exists. Use newEndpoint instead.

AI Attribution

AI贡献声明

AI agents must disclose their assistance in the commit footer:
text
Assisted-by: [Model Name] via [Tool Name]
Examples:
  • Assisted-by: GLM 4.6 via Claude Code
  • Assisted-by: Claude Opus 4.5 via claude.ai
AI Agent必须在提交页脚中披露其协助：
text
Assisted-by: [Model Name] via [Tool Name]
示例：
  • Assisted-by: GLM 4.6 via Claude Code
  • Assisted-by: Claude Opus 4.5 via claude.ai

Common Mistakes

常见错误

MistakeWhy WrongCorrect
Added login feature
Past tense, capitalized
feat: add login feature
fix bug.
Trailing period
fix: resolve login error
update
Missing type
chore: update dependencies
feature:add-auth
Missing space after colon
feat: add authentication
FEAT: big change
Uppercase type
feat: add authentication
Multi-line description no blank lineNo separationAdd blank line after subject
错误示例错误原因正确示例
Added login feature
过去式、首字母大写
feat: add login feature
fix bug.
结尾有句号
fix: resolve login error
update
缺少类型
chore: update dependencies
feature:add-auth
冒号后缺少空格
feat: add authentication
FEAT: big change
类型为大写
feat: add authentication
多行描述无空行分隔主题与正文未分离在主题后添加空行

Body Guidelines

正文撰写指南

  • What: Motivation for the change (vs. code comments describe HOW)
  • Contrast: Explain the WHY and WHAT, not code details
  • Wrap at 72 characters for readability in git log
text
feat(summarization): add support for nested bullet points

Previous implementation only flattened all content. Now preserves
hierarchy by respecting indentation levels. Users can now create
structured summaries with parent-child relationships.

Closes: #456
  • 内容: 变更的动机（代码注释描述的是实现方式，此处需说明原因）
  • 重点: 解释原因和变更内容，而非代码细节
  • 每行不超过72个字符，以保证在git log中可读性良好
text
feat(summarization): add support for nested bullet points

Previous implementation only flattened all content. Now preserves
hierarchy by respecting indentation levels. Users can now create
structured summaries with parent-child relationships.

Closes: #456

Footer Guidelines

页脚撰写指南

Use footers for:
  • Breaking changes: 
    BREAKING CHANGE: detailed explanation
  • Issue references: 
    Closes: #123
    , 
    Fixes: #456
    , 
    Refs: #789
  • AI attribution: 
    Assisted-by: Model via Tool
Multiple footers separated by blank lines:
text
feat: add batch upload

Implements multipart upload for large files.

BREAKING CHANGE: upload() signature changed - now requires options object
Closes: #123
Assisted-by: GLM 4.6 via Claude Code
页脚可用于以下场景：
  • 破坏性变更: 
    BREAKING CHANGE: detailed explanation
  • 关联议题: 
    Closes: #123
    , 
    Fixes: #456
    , 
    Refs: #789
  • AI贡献声明: 
    Assisted-by: Model via Tool
多个页脚用空行分隔：
text
feat: add batch upload

Implements multipart upload for large files.

BREAKING CHANGE: upload() signature changed - now requires options object
Closes: #123
Assisted-by: GLM 4.6 via Claude Code

Git Commit Flags

Git提交标记

Required flag: Always use 
--signoff
when committing:
bash
git commit --signoff -m "feat: add user authentication"
The 
--signoff
flag adds a 
Signed-off-by
trailer to the commit message, indicating the committer has certified the commit follows developer certificate of origin (DCO).
必填标记: 提交时始终使用
--signoff
：
bash
git commit --signoff -m "feat: add user authentication"
--signoff
标记会在提交消息末尾添加
Signed-off-by
尾注，表示提交者已认证该提交遵循开发者原产地证书（DCO）。

Testing Your Commit

提交验证

Before committing, verify:
  1. Type is from allowed list
  2. Description is imperative mood (add, fix, update)
  3. Description is lowercase
  4. No trailing period on description
  5. Breaking changes marked with 
    !
    or footer
  6. AI attribution included (if applicable)
  7. Body explains WHY not HOW
  8. Using 
    --signoff
    flag
提交前，请验证以下项：
  1. 类型属于允许的列表
  2. 描述使用祈使语气（add、fix、update等）
  3. 描述为小写
  4. 描述结尾无句号
  5. 破坏性变更已用
    !
    或页脚标记
  6. 已包含AI贡献声明（如适用）
  7. 正文解释了原因而非实现方式
  8. 使用了
    --signoff
    标记