Back to Details

commit-helper

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CockroachDB Commit Helper

CockroachDB 提交助手

Help the user create properly formatted commit messages and release notes that follow CockroachDB conventions.
帮助用户创建符合CockroachDB规范、格式正确的提交消息和发布说明。

Workflow

工作流程

  1. Analyze the changes: Run 
    git diff --staged
    or 
    git diff
    to understand what was modified
  2. Determine the package prefix: Identify the primary package affected
  3. Ask the user for:
    • Issue/epic number if not already known
    • Whether release notes are needed and what category fits best
  4. Write the subject line: Imperative mood, no period, under 72 characters
  5. Write the body: Explain the before/after, why the change was needed
  6. Add issue references: Include Resolves/Epic as appropriate
  7. Write the release note: Clear, user-focused description of the change
  8. Create the commit using the properly formatted message
  1. 分析更改：运行
    git diff --staged
    或
    git diff
    以了解修改内容
  2. 确定包前缀：识别受影响的主要包
  3. 询问用户以下信息：
    • 问题/史诗编号（如果尚未知晓）
    • 是否需要发布说明以及最适合的类别
  4. 编写主题行：使用祈使语气，无句号，长度不超过72个字符
  5. 编写正文：解释更改前后的情况、为什么需要进行此更改
  6. 添加问题引用：根据需要包含Resolves/Epic
  7. 编写发布说明：清晰、以用户为中心的更改描述
  8. 创建提交：使用格式正确的消息

Commit Message Structure

提交消息结构

Basic Format:
package: imperative title without period

Detailed explanation of what changed, why it changed, and
how it impacts users. Explain the problem that existed
before and how this commit solves it.

Include context about alternate approaches considered and
any side effects or consequences.

Resolves: #123
Epic: CRDB-357

Release note (category): Description of user-facing change
in past or present tense explaining what changed, how users
can see the change, and why it's important.
Key Requirements:
  • Must include release note annotation (even if "Release note: None")
  • Must include issue or epic reference
  • Must separate subject from body with blank line
  • Recommended prefix subject with affected package/area
  • Recommended use imperative mood in subject (e.g. "fix bug" not "fixes bug")
  • Recommended wrap body at 72-100 characters
基本格式：
package: imperative title without period

Detailed explanation of what changed, why it changed, and
how it impacts users. Explain the problem that existed
before and how this commit solves it.

Include context about alternate approaches considered and
any side effects or consequences.

Resolves: #123
Epic: CRDB-357

Release note (category): Description of user-facing change
in past or present tense explaining what changed, how users
can see the change, and why it's important.
关键要求：
  • 必须包含发布说明注释（即使是“Release note: None”）
  • 必须包含问题或史诗引用
  • 必须用空行分隔主题和正文
  • 建议在主题前添加受影响的包/区域前缀
  • 建议在主题中使用祈使语气（例如“fix bug”而非“fixes bug”）
  • 建议正文每行长度控制在72-100个字符

Release Note Categories

发布说明类别

When to include release notes:
  • Changes to user interaction or experience
  • Changes to product behavior (performance, command responses, architecture)
  • Bug fixes affecting external users
When to exclude release notes:
  • Internal refactors, testing, infrastructure work
  • Code that's too immature for docs (private preview features)
  • Internal settings beginning with 
    crdb_internal.
  • Functionality not accessible to external users
Valid Categories:
  • backward-incompatible change
    - Breaking changes to stable interfaces
  • enterprise change
    - Features requiring enterprise license
  • ops change
    - Commands/endpoints for operators (logging, metrics, CLI flags)
  • cli change
    - Commands for developers/contributors (SQL shells, debug tools)
  • sql change
    - SQL statements, functions, system catalogs
  • ui change
    - DB Console changes
  • security update
    - Security feature changes
  • performance improvement
    - Performance enhancements
  • cluster virtualization
    - Multi-tenancy infrastructure
  • bug fix
    - Problem fixes
  • general change
    - Changes that don't fit elsewhere
  • build change
    - Source build requirements
何时需要包含发布说明：
  • 用户交互或体验的更改
  • 产品行为的更改（性能、命令响应、架构）
  • 影响外部用户的 bug 修复
何时无需包含发布说明：
  • 内部重构、测试、基础设施工作
  • 尚未成熟到可文档化的代码（私有预览功能）
  • 以
    crdb_internal.
    开头的内部设置
  • 外部用户无法访问的功能
有效类别：
  • backward-incompatible change
    - 对稳定接口的破坏性更改
  • enterprise change
    - 需要企业许可证的功能
  • ops change
    - 面向运维人员的命令/端点（日志、指标、CLI 标志）
  • cli change
    - 面向开发者/贡献者的命令（SQL shell、调试工具）
  • sql change
    - SQL 语句、函数、系统目录
  • ui change
    - DB Console 更改
  • security update
    - 安全功能更改
  • performance improvement
    - 性能增强
  • cluster virtualization
    - 多租户基础设施
  • bug fix
    - 问题修复
  • general change
    - 不适合其他类别的更改
  • build change
    - 源码构建要求

Release Note Best Practices

发布说明最佳实践

Description guidelines:
  • Default to more information rather than less
  • Explain what changed, how it changed, and why it's relevant
  • Use past tense ("Added", "Fixed") or present tense ("CockroachDB now supports")
  • For bug fixes: describe cause, symptoms, and affected versions
  • Note if change is part of broader roadmap feature
Examples:
Good bug fix:
Release note (bug fix): Fixed a bug introduced in v19.2.3 that
caused duplicate rows in CREATE TABLE ... AS results when multiple
nodes attempt to populate the results.
Good feature:
Release note (enterprise change): Shortened the default interval
for the kv.closed_timestamp.target_duration cluster setting from
30s to 3s. This allows follower reads at 4.8 seconds in the past,
a much shorter window than the previous 48 seconds.
描述准则：
  • 宁多勿少，提供充分信息
  • 解释什么更改了、如何更改以及为什么相关
  • 使用过去时（“Added”、“Fixed”）或现在时（“CockroachDB now supports”）
  • 对于 bug 修复：描述原因、症状和受影响的版本
  • 注明更改是否属于更广泛的路线图功能的一部分
示例：
良好的 bug 修复说明：
Release note (bug fix): Fixed a bug introduced in v19.2.3 that
caused duplicate rows in CREATE TABLE ... AS results when multiple
nodes attempt to populate the results.
良好的功能说明：
Release note (enterprise change): Shortened the default interval
for the kv.closed_timestamp.target_duration cluster setting from
30s to 3s. This allows follower reads at 4.8 seconds in the past,
a much shorter window than the previous 48 seconds.

Issue References

问题引用

  • Resolves: #123
    - Auto-closes issue on PR merge
  • See also: #456, #789
    - Cross-references issues
  • Epic: CRDB-357
    - Links to epic
  • Resolves: #123
    - PR 合并时自动关闭问题
  • See also: #456, #789
    - 交叉引用问题
  • Epic: CRDB-357
    - 链接到史诗

How to Avoid Common Pitfalls

如何避免常见陷阱

  • Always include a release note annotation (even "Release note: None")
  • Use only valid category names from the list above
  • Keep release notes focused on user-facing information
  • Write specific descriptions that explain the impact to users
  • Use 
    backward-incompatible change
    category for any breaking changes
  • End subject lines without punctuation
  • Explain the "why" behind changes, not just the "what"
  • 始终包含发布说明注释（即使是“Release note: None”）
  • 仅使用上述列表中的有效类别名称
  • 发布说明应专注于面向用户的信息
  • 编写具体的描述，解释对用户的影响
  • 任何破坏性更改都使用
    backward-incompatible change
    类别
  • 主题行末尾不要加标点
  • 解释更改背后的“原因”，而不仅仅是“内容”

Pull Request Guidelines

拉取请求准则

  • Create PRs from your personal fork, not directly on cockroachdb/cockroach
  • Single-commit PRs: PR title should match commit title, PR body should match commit body
  • 从个人分支创建PR，不要直接在cockroachdb/cockroach上创建
  • 单提交PR：PR标题应与提交标题匹配，PR正文应与提交正文匹配