mcpField
C
commit-helper

commit-helper

github.com/cockroachdb开发32.6k642 次安装6 周前更新
代码仓库

关于 commit-helper

面向 CockroachDB 贡献者，帮助按项目约定撰写提交信息和发行说明，涵盖变更分析、消息结构、问题引用、发行说明分类及 PR 背景。

主要功能

  1. 01检查暂存和未暂存变更
  2. 02编写带包名前缀的提交标题
  3. 03组织提交正文和问题引用
  4. 04选择发行说明类别
  5. 05提供 PR 摘要指导

适用场景

  1. 01撰写符合约定的提交信息
  2. 02添加必需的发行说明标注
  3. 03准确说明面向用户的变更
  4. 04为多提交 PR 准备背景说明

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cockroachdb/cockroach --skill commit-helper

安装后在 Claude Code 中输入/commit-helper确认已加载。

详细介绍

CockroachDB 提交信息助手

帮助用户创建格式规范的提交信息和发行说明，遵循 CockroachDB 约定。

工作流

  1. 分析更改：运行 git diff --staged 或 git diff，了解修改内容
  2. 确定软件包前缀：识别受影响的主要软件包
  3. 询问用户：
    • 如果尚不清楚，询问问题或 Epic 编号
    • 询问是否需要发行说明，以及最合适的类别
  4. 编写主题行：使用祈使语气，不加句号，不超过 72 个字符
  5. 编写正文：说明更改前后的情况，以及更改的原因
  6. 添加问题引用：酌情添加 Resolves/Epic
  7. 编写发行说明：清晰、面向用户地描述更改
  8. 创建提交：使用格式规范的提交信息

提交信息结构

基本格式：

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”）
  • 必须包含问题或 Epic 引用
  • 必须在主题和正文之间留一个空行
  • 建议在主题前加上受影响的软件包或领域
  • 建议在主题中使用祈使语气（例如“fix bug”，而不是“fixes bug”）
  • 建议将正文每行控制在 72–100 个字符

发行说明类别

需要包含发行说明的情况：

  • 用户交互或体验发生变化
  • 产品行为发生变化（性能、命令响应、架构）
  • 影响外部用户的错误修复

不需要包含发行说明的情况：

  • 内部重构、测试、基础设施工作
  • 尚不适合写入文档的代码（私有预览功能）
  • 以 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 - 源代码构建要求

发行说明最佳实践

描述指南：

  • 默认提供更多信息，而非更少
  • 说明更改了什么、如何更改，以及为何与用户相关
  • 使用过去时（“Added”“Fixed”）或现在时（“CockroachDB now supports”）
  • 对于错误修复，说明原因、症状和受影响的版本
  • 如果更改属于更广泛的路线图功能，请注明

示例：

优秀的错误修复示例：

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.

问题引用

  • Resolves: #123 - 合并 PR 时自动关闭问题
  • See also: #456, #789 - 交叉引用问题
  • Epic: CRDB-357 - 链接到 Epic

如何避免常见问题

  • 始终添加发行说明标注（即使是“Release note: None”）
  • 仅使用上述列表中的有效类别名称
  • 发行说明应聚焦于面向用户的信息
  • 撰写具体描述，说明对用户的影响
  • 对于任何破坏性更改，使用 backward-incompatible change 类别
  • 主题行末尾不要添加标点
  • 说明更改背后的“原因”，而不仅仅是“内容”

拉取请求指南

  • 从个人 fork 创建 PR，不要直接在 cockroachdb/cockroach 上创建
  • 单提交 PR：PR 标题应与提交标题一致，PR 正文应与提交正文一致
  • 多提交 PR：正文应总结这一组提交最终实现的目标，并提供读者逐个提交审查 PR 所需的背景信息（例如，前几个提交可能会先完成重构，为最后一个提交做好准备，以便接入所有内容）。如果这些提交之间没有总体关联（例如，PR 将几项互不相关的机械性变更放在一起），可以说明各个提交本身已经阐明了变更内容。

评论

支持 Markdown