Back to Details

git-commit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Commit Guidelines

Git 提交规范

Follow these rules when creating commits for this repository.
在为本仓库创建提交时，请遵循以下规则。

The 7 Rules

7条规则

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood ("Add feature" not "Added feature")
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how
  1. 用空行分隔主题与正文
  2. 主题行长度限制在50字符以内
  3. 主题行首字母大写
  4. 主题行末尾不要加句号
  5. 使用祈使语气（例如"Add feature"而非"Added feature"）
  6. 正文每行最多72字符
  7. 正文说明变更内容和原因，而非实现方式

Key Principles

核心原则

Be concise, not verbose. Every word should add value. Avoid unnecessary details about implementation mechanics - focus on what changed and why it matters.
Subject line should stand alone - don't require reading the body to understand the change. Body is optional and only needed for non-obvious context.
Focus on the change, not how it was discovered - never reference "review feedback", "PR comments", or "code review" in commit messages. Describe what the change does and why, not that someone asked for it.
Avoid bullet points - write prose, not lists. If you need bullets to explain a change, you're either committing too much at once or over-explaining implementation details.
保持简洁，避免冗长。 每个词汇都应具备价值。无需赘述实现细节的无关内容——重点说明变更内容及其重要性。
主题行应独立表意——无需阅读正文就能理解变更内容。正文为可选内容，仅用于说明非显而易见的背景信息。
聚焦变更本身，而非变更的触发原因——提交信息中绝不要提及"评审反馈"、"PR评论"或"代码评审"。描述变更的作用和原因，而非他人要求你进行此变更。
避免使用项目符号——采用散文式表述，而非列表形式。如果需要用项目符号来解释变更，要么是你一次提交的内容过多，要么是过度解释了实现细节。

Format

格式要求

Always use a HEREDOC to ensure proper formatting:
bash
git commit -m "$(cat <<'EOF'
Subject line here

Optional body paragraph explaining what and why.
EOF
)"
请始终使用HEREDOC来确保格式正确：
bash
git commit -m "$(cat <<'EOF'
Subject line here

Optional body paragraph explaining what and why.
EOF
)"

Good Examples

优秀示例

Add session isolation for concurrent executions
Fix encoding parameter handling in file operations

The encoding parameter wasn't properly passed through the validation
layer, causing base64 content to be treated as UTF-8.
Add session isolation for concurrent executions
Fix encoding parameter handling in file operations

The encoding parameter wasn't properly passed through the validation
layer, causing base64 content to be treated as UTF-8.

Bad Examples

反面示例

Update files

Changes some things related to sessions and also fixes a bug.
Problem: Vague subject, doesn't explain what changed
Add file operations support

Implements FileClient with read/write methods and adds FileService
in the container with a validation layer. Includes comprehensive test
coverage for edge cases and supports both UTF-8 text and base64 binary
encodings. Uses proper error handling with custom error types from the
shared package for consistency across the SDK.
Problem: Over-explains implementation details, uses too many words
Update files

Changes some things related to sessions and also fixes a bug.
问题：主题模糊，未说明具体变更内容
Add file operations support

Implements FileClient with read/write methods and adds FileService
in the container with a validation layer. Includes comprehensive test
coverage for edge cases and supports both UTF-8 text and base64 binary
encodings. Uses proper error handling with custom error types from the
shared package for consistency across the SDK.
问题：过度解释实现细节，篇幅过长

Checklist Before Committing

提交前检查清单

  • Subject is ≤50 characters
  • Subject uses imperative mood
  • Subject is capitalized, no period at end
  • Body (if present) explains why, not how
  • No references to review feedback or PR comments
  • No bullet points in body
  • Not committing sensitive files (.env, credentials)
  • 主题行长度≤50字符
  • 主题行使用祈使语气
  • 主题行首字母大写，末尾无句号
  • 正文（若存在）说明原因而非实现方式
  • 未提及评审反馈或PR评论
  • 正文未使用项目符号
  • 未提交敏感文件（.env、凭证文件等）