commit-helper

CockroachDB コミットヘルパー

ユーザーが CockroachDB の規約に沿った、適切な形式のコミットメッセージとリリースノートを作成できるよう支援します。

ワークフロー

1. 変更内容の分析: git diff --staged または git diff を実行して、何が変更されたかを把握します
2. パッケージプレフィックスの決定: 主に影響を受けるパッケージを特定します
3. ユーザーへの確認: 以下をたずねます
   • まだ分かっていない場合は、Issue/エピック番号
   • リリースノートが必要かどうか、また最も適切なカテゴリー
4. 件名の作成: 命令形、末尾に句点なし、72 文字未満
5. 本文の作成: 変更前後の状態と、その変更が必要だった理由を説明します
6. Issue 参照の追加: 必要に応じて 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」の場合も含む）
• 必須: Issue またはエピックの参照を含めること
• 必須: 件名と本文を空行で区切ること
• 推奨: 件名の先頭に、影響を受けるパッケージや領域を付けること
• 推奨: 件名では命令形を使うこと（例: 「fixes bug」ではなく「fix bug」）
• 推奨: 本文は 72〜100 文字で折り返すこと

リリースノートのカテゴリー

リリースノートを含めるべき場合:

• ユーザーの操作や使用感の変更
• 製品の動作の変更（パフォーマンス、コマンドの応答、アーキテクチャ）
• 外部ユーザーに影響するバグ修正

リリースノートを除外すべき場合:

• 内部リファクタリング、テスト、インフラ関連の作業
• ドキュメント化するには成熟度が不十分な機能（プライベートプレビュー機能）
• crdb_internal. で始まる内部設定
• 外部ユーザーからアクセスできない機能

有効なカテゴリー:

• backward-incompatible change - 安定したインターフェースに対する破壊的変更
• enterprise change - エンタープライズライセンスが必要な機能
• ops change - オペレーター向けのコマンドやエンドポイント（ロギング、メトリクス、CLI フラグ）
• cli change - 開発者やコントリビューター向けのコマンド（SQL シェル、デバッグツール）
• 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.

Issue の参照

• Resolves: #123 - PR のマージ時に Issue を自動でクローズします
• See also: #456, #789 - Issue 同士を相互参照します
• Epic: CRDB-357 - エピックにリンクします

よくある落とし穴の回避

• 必ずリリースノートの注釈を含めてください（「Release note: None」も含む）
• 上記の一覧にある有効なカテゴリー名のみを使用してください
• リリースノートは、ユーザーに関係する情報に絞ってください
• ユーザーへの影響を説明する、具体的な説明を書いてください
• 破壊的変更には、必ず backward-incompatible change カテゴリーを使用してください
• 件名の末尾には句読点を付けないでください
• 「何を」変えたかだけでなく、「なぜ」変えたのかを説明してください

プルリクエストのガイドライン

• プルリクエストは、cockroachdb/cockroach に直接ではなく、個人のフォークから作成してください
• 単一コミットのプルリクエスト: PR のタイトルはコミットのタイトルと、PR の本文はコミットの本文と一致させてください
• 複数コミットのプルリクエスト: 本文には、コミットの集合が達成する最終的な目標を要約し、レビュアーがコミットごとにレビューするために必要な文脈を示してください（例えば、最初のコミットでリファクタリングを済ませておき、最後のコミットですべてを結び付ける、といった構成です）。コミット同士に全体を通した関連がない場合（例えば、関連のない機械的な変更をいくつかまとめている場合）は、個々のコミットがそれ自体で説明になっていると記載しても問題ありません。