conventional-commit-message

Conventional Commit メッセージ

conventional-changelog-conventionalcommits プリセットまたは互換性のある Conventional Commits リリースツールを使用するリポジトリで、コミットメッセージを作成、修正、レビュー、提案する際にこのスキルを使用します。

コミットの形式

Conventional Commits 1.0.0 のメッセージ構造を使用します。

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

[optional body]

[optional footer(s)]

ルール：

• type は必須です。後ろに、任意の括弧付き scope、任意の !、そして : が続きます。
• description は必須で、: の直後に記述します。簡潔で変更履歴に適した内容にし、固有名詞や識別子で大文字・小文字の区別が必要な場合を除き、小文字にします。末尾にピリオドは付けません。
• scope は任意で、コードベースのセクション名を指定します。
• 長めの本文は任意です。description の後に空行を1行入れて記述し、形式は自由です。
• フッターは任意です。本文または description の後に空行を1行入れて記述し、それぞれ Token: value または Token #value の形式にします。
• フッターのトークンでは、BREAKING CHANGE を除き、スペースの代わりにハイフンを使用します（例：Reviewed-by）。BREAKING-CHANGE は BREAKING CHANGE と同義です。
• フッターの値にはスペースや改行を含められます。次の有効なフッタートークンと区切り文字が現れると、フッターの値は終了します。
• Conventional Commit の各要素では大文字・小文字は区別されません。ただし、フッタートークンに BREAKING CHANGE を使用する場合は、大文字で記述する必要があります。
• 一貫性のある変更ごとに1つのコミットにすることを推奨します。1つの差分にリリースノートに記載すべき無関係な変更が含まれている場合は、分割を提案してください。
• 生成される変更履歴の箇条書きとして読みやすい description にしてください。add some feature、update stuff、fix issue のような曖昧な実装メモは避けてください。support custom scopes、preserve prerelease tags、require Node.js 22 のように、ユーザーにとっての成果が伝わる表現を推奨します。
• description 内のコード識別子はバッククォートで囲みます。対象は、関数、オプション、フラグ、型、ファイル名です。例：add `autocase` to match camelCase and kebab-case forms、support `--no-*` negation。GitHub ではコミットメッセージ内のバッククォートがレンダリングされ、生成された変更履歴にもそのまま残ります。また、通常の文章では意味が曖昧になりうる flag や rest などの単語をコードとして示せます。
• 意図的な GitHub ユーザーメンションでない @ で始まるトークンは、すべてバッククォートで囲みます。対象は、スコープ付きパッケージ名（@types/node）、デコレーター（@Injectable）、JSDoc／アノテーションタグ（@deprecated）です。コミットメッセージや変更履歴で @name をバッククォートなしで記述すると、GitHub がユーザーメンションとして解析し、無関係な GitHub アカウントにリンクしたり通知したりする可能性があります。
• 能動態の動詞句が通常は適しています。プロジェクトにとって受動態が明らかに自然な場合を除き、custom scopes were added よりも support custom scopes を優先してください。

破壊的変更は、ヘッダーの : の直前に ! を付けるか、破壊的変更フッターを記述して示します。影響がわかっている場合は、フッターを使用してください。

feat(parser)!: remove legacy token fallback

BREAKING CHANGE: custom token fallbacks are no longer applied during parsing.

! を使用し、破壊的変更フッターを記述しない場合、破壊的変更の内容は description で説明します。

種類の選択

デフォルトで表示される種類：

• feat：ユーザー向け機能です。Features に表示され、マイナーバージョンが上がります。コミットで新機能を追加する場合に使用します。
• feature：feat の使用可能な別名です。既存のプロジェクトのスタイルに合わせる場合を除き、feat を優先してください。
• fix：バグ修正または正確性の修正です。Bug Fixes に表示され、パッチバージョンが上がります。コミットがバグ修正に該当する場合に使用します。
• perf：パフォーマンス改善です。Performance Improvements に表示され、パッチバージョンが上がります。
• revert：コミットの取り消しです。Reverts に表示され、パッチバージョンが上がります。

デフォルトで非表示の種類：

• docs：ドキュメントのみの変更です。
• style：動作の変更を伴わない、フォーマット、空白、句読点、またはスタイルのみの変更です。
• chore：変更履歴に含めず、バージョンも上げない一般的なメンテナンスです。より適切な非表示の種類がない場合にのみ使用します。
• refactor：動作や API を意図的に維持するコード変更です。
• test：テストのみの変更です。
• build：ビルドシステム、パッケージ化、依存関係のメタデータ、生成されたビルド設定に関する変更です。
• ci：CI ワークフローまたは自動化のみの変更です。

非表示の種類は、変更履歴に含めず、バージョンも上げない意図を示すものとして扱います。コード変更がリリース済みの動作や API に明らかな影響を与えない場合は、ソースファイルを変更していても、fix や feat ではなく非表示の種類を使用してください。

feat と fix 以外の種類も Conventional Commits 仕様で認められていますが、仕様上、破壊的変更のマーカーが含まれない限り、暗黙の SemVer への影響はありません。このリポジトリのプリセットでは、設定されたコミットの種類を通じて、表示方法とバージョン変更の動作が追加で定義されています。

すべての非表示の変更に対する受け皿として chore を使わないでください。変更の内容を最も正確に表す非表示の種類を優先してください。パッケージマネージャー、ビルドツール、依存関係のメタデータ、生成されたビルド設定、ワークスペース設定には build、CI のみの自動化には ci、テストには test、ドキュメントには docs、動作を維持するコードの再構成には refactor、フォーマットのみの変更には style を使用します。

リリースへの影響を意図していない限り、非表示のコミットに !、BREAKING CHANGE、または Release-As を追加しないでください。これらのシグナルは、非表示／バージョン変更なしという意図を上書きします。

非表示の種類を選ぶ前に、変更されたファイルがメタデータ、設定、テスト、生成ファイル、CI であっても、差分によって公開パッケージのパブリックコントラクトが変わるかどうかをまず確認してください。パブリックコントラクトには、サポート対象のランタイムおよびプラットフォームのバージョン、パッケージのエクスポート、CLI の動作、設定プリセット、ピア依存関係の要件、生成される出力、ドキュメント化された API、デフォルトの動作が含まれます。パブリックコントラクトが厳しくなる、これまでサポートされていた使い方が削除される、またはユーザーに見える動作が変わる場合は、表示される種類を使用してください。これまでサポートされていた使い方が機能しなくなる場合は、! と BREAKING CHANGE フッターを使用してください。

リリースへの影響や破壊的変更を示すよくある注意点：

• ランタイム、プラットフォーム、ブラウザー、またはエンジンの最小要件を引き上げる。
• パッケージのエクスポート、エントリーポイント、CLI フラグ、オプション、設定プリセット、またはドキュメント化された API を削除、改名、または範囲縮小する。
• ピア依存関係のバージョン範囲や必須の外部ツール要件を厳しくする。
• 利用者に提供される生成出力、デフォルト値、検証ルール、解析動作、またはリント／設定ルールを変更する。

影響に基づく判断基準

ファイルパスではなく、リリースへの影響に基づいて種類を選びます。

• 公開されている動作の追加：feat。
• 公開されている動作の修正：fix。
• 動作を変えずに実行時の速度やメモリ使用量を改善：perf。
• dependencies における実行時依存関係の更新：fix。公開パッケージの依存関係グラフを変更し、正確性、セキュリティ、実行時の動作を改善する可能性があるため、ソースコードに変更がない場合でもリリースを実行する必要があります。依存関係の更新によって、サポート対象の公開動作が変更または削除される場合に限り、! を使用します。
• 公開契約の厳格化、または以前サポートされていた使い方の削除：feat! または fix! と BREAKING CHANGE フッターを使用します。例：engines.node を Node.js 22 に引き上げる場合、require Node.js 22 のような件名を使用します。
• 動作を維持した内部の書き換え：refactor。
• 出荷される動作の変更を伴わない、依存関係のロックファイルやパッケージマネージャーの保守、ビルドツール、生成されるビルド設定、ワークスペースのパッケージマネージャー設定：build。ただし、ローカルのスタイルで別の非公開タイプが強く推奨されている場合を除きます。
• CI のみのワークフロー編集：ci。
• プロダクトコードへの影響を伴わないテストの追加や調整：test。
• ドキュメント、README、例の文章のみの変更：docs。
• より具体的な非公開タイプに当てはまらない一般的な保守作業：chore。

ソースコードの変更がユーザーから見えるかどうか判断できない場合は、テストと公開 API の使用状況を確認します。防御的な整理、移行のための処理、非公開ヘルパーの名前変更、リント修正、型のみの再構成の場合は、非公開タイプを優先します。

スコープの選択

スコープを選ぶ前に、リポジトリを確認します。

git diff --staged --name-only
git diff --name-only
rg --files -g '*commitlint*' -g '.commitlintrc*' -g 'commitlint.config.*'
rg --files -g 'package.json'

まずステージ済みの変更を使用します。ステージ済みの変更がない場合は、作業ツリーの差分を使用します。

プロジェクトで commitlint を使用している場合は、メッセージを選ぶ前に設定を確認します。設定では、許可されるタイプやスコープ、必須の大文字・小文字の形式、最大文字数、その他のローカルな書式ルールが定められていることがあります。よくある場所は .commitlintrc、.commitlintrc.json、.commitlintrc.yaml、.commitlintrc.yml、.commitlintrc.js、.commitlintrc.cjs、.commitlintrc.mjs、.commitlintrc.ts、commitlint.config.js、commitlint.config.cjs、commitlint.config.mjs、commitlint.config.ts です。

単一リポジトリのプロジェクト：

• 通常、スコープは省略します。
• プロジェクトですでに cli、docs、deps、release、サブシステム名などの明確なスコープが使われている場合に限り、スコープを使用します。

モノレポ：

• 影響を受けるパッケージ名をスコープとして使うのが望ましいです。
• ワークスペースのパッケージ名、既存の commitlint の scope-enum、または最近のコミットからパッケージのスコープを判断します。
• commitlint またはローカルツールが複数のスコープに対応しており、一貫したリリース上の変更が複数の公開パッケージに影響する場合、変更を1つのパッケージにまとめるのではなく、影響を受けるすべてのパッケージスコープを使用します。
• リポジトリで認められている複数スコープの区切り文字を優先します。ローカル設定で複数スコープが有効になっているものの、区切り文字が明らかでない場合は、カンマ区切りのスコープリストを使用する前に commitlint で検証します。
• パッケージ名が npm スコープ付きの場合は、リポジトリで既存の規約に従います。完全なパッケージ名を使う場合と、スコープを除いたパッケージ名の部分を使う場合があります。
• 変更されたパッケージが1つの場合は、そのパッケージのスコープを使用します。
• 共通の理由で複数のパッケージが変更された場合、役立つ意味を付け加えられるなら、deps、dev-deps、release などの共通スコープを使用します。
• 多数のパッケージに影響するモノレポ全体のリリース関連変更では、リポジトリでスコープが必須でない限り、スコープを省略するのが望ましいです。通常、リリースツールは global スコープではなく、変更されたパッケージを使って影響を受けるパッケージを判定します。
• 複数のパッケージが異なる理由で変更された場合は、まず共通の意図を正確に表現する方法を検討します。妥当なメッセージが曖昧になったり、リリースへの影響を隠したりする場合に限り、別々のコミットを提案します。

依存関係のみの作業：

• deps が許可されたスコープの場合、dependencies における実行時依存関係の更新には fix(deps) を使用します。
• 開発時のみ使用するツール依存関係の更新には、dev-deps が許可されたスコープであれば dev-deps を使用します。

メッセージ作成のワークフロー

1. 変更されたファイルと差分の概要を確認します。
2. リリースされる動作への影響を特定します。
3. 表示するタイプか、非表示にするタイプかを選びます。
4. 有効な範囲のうち、最も限定的なものを選びます。
5. 表示する場合はユーザーの視点から、非表示にする場合はメンテナンスの意図から、件名を変更履歴の箇条書きとして記述します。
6. 破壊的変更、課題のクローズ、リリース種別、重要なコンテキストに必要な場合のみ、本文やフッターを追加します。
7. 作業が課題、PR、バグ報告、またはユーザー提供のトラッカー URL に明示的に関連している場合は、コミットの本文またはフッターに該当する参照を含めます。課題をクローズする修正には、Fixes #123. のようなクローズ用フッターを使用します。クローズしない参照には、Refs #123. のような非クローズ用の参照を使用します。
8. commitlint が設定されていて CLI を利用できる場合は、候補をユーザーに提示する前に検証します。

可能であれば、まずローカルにインストールされた commitlint バイナリで検証します。リポジトリにインストールされたバージョンと設定を使いつつ、パッケージマネージャーの環境、サンドボックス、レジストリの動作を回避できるため、パッケージマネージャーの実行コマンドより ./node_modules/.bin/commitlint を優先します。

echo 'type(scope): subject' | ./node_modules/.bin/commitlint

ローカルバイナリがなく、現在の環境で実行しても問題ない場合に限り、代替手段としてパッケージマネージャーの実行コマンドを使用します。

echo 'type(scope): subject' | pnpm commitlint
echo 'type(scope): subject' | npm exec commitlint
echo 'type(scope): subject' | npx commitlint

例ではなく、実際の候補メッセージを使用します。複数行のメッセージでは、メッセージ全体を正確に保持する printf または別のコマンドを使用します。

printf '%s\n\n%s\n' 'feat(parser)!: remove legacy token fallback' 'BREAKING CHANGE: custom token fallbacks are no longer applied.' | ./node_modules/.bin/commitlint

commitlint の検証に失敗した場合は、タイプ、範囲、大文字・小文字、または件名の長さを調整して、再度検証します。commitlint が設定されていても、現在の環境で CLI を実行できない場合は、その旨をユーザーに伝えます。

課題への参照は自然に記載します。

fix(parser): handle empty commit body refs #123

コミットによって課題をクローズする場合にのみ、クローズ用のキーワードを使用します。

fix(cli): preserve prerelease tag when appending changelog

Fixes #123.

モノレポ内の複数のパッケージに影響する、一貫性のある変更では、リポジトリでサポートされている場合、複数のスコープを使用します。

fix(package-a,package-b): preserve compare links

Fixes #123.

例

表示するリリース項目：

feat(writer): support scoped package links
feat!: require Node.js 22
feat: add `rest` function to read all remaining arguments
fix(parser): keep issue references from multiline footers
fix(cli): handle `--no-*` flags in strict mode
perf(git-client): avoid duplicate tag lookups
revert: feat(writer): support scoped package links

リリース種別を変更しない非表示の項目：

refactor(conventional-changelog): simplify context defaults
test(writer): cover empty reference groups
docs(conventionalcommits): clarify hidden commit types
build(dev-deps): update oxlint
ci: use node 22 in tests
chore(release): prepare package metadata

モノレポのパッケージスコープ：

fix(conventional-changelog-writer): preserve reference order
refactor(conventional-commits-parser): split token normalization
test(git-client): cover lightweight tags

出力スタイル

ユーザーがコミットメッセージを求めた場合、説明や代替案を求められていない限り、推奨するメッセージのみを出力します。影響が不確かな場合は、簡潔な選択肢を 2 つ提示し、それぞれのリリースへの影響を説明します。

fix(parser): handle empty commit body

または、リリース種別の変更を意図しない場合：

refactor(parser): handle empty commit body defensively