Conventional Commitsでコミットログにシンプルな秩序を

Conventional Commitsとは、コミットログにシンプルな秩序を持ち込むための軽量な規約で、決めているのは実質「1行目を "[scope]: " で書く」ことだけです。
このスライドは v1.0.0に合わせて執筆しました。

Transcript

1. で コミットログにシンプルな秩序を Conventional Commits ～ Git・GitHub・GitLab・Bitbucketでの保ち方 ～ 2026-09-26 北海道もくもく会 オンライン 発表資料 1
2. 自己紹介 ひだお（hidao80） 好きなこと: 情報整理：Markdown-vault × AI 自作ツール開発：PWA / UserScript / ブラウザ拡張機能 HN: / ... 活動: 技術記事投稿：Qiita / Zenn / dev.to OSS個人開発：VS Code / Chrome拡張 / PWA モットー: 最適・最小・理性的 / 三方利益 2
3. TL;DR ルールは少なく、形だけは揃える 決めるのは実質1行目の形だけ（最新はv1.0.0） 2. typeがSemVerに直結 → CHANGELOG・バージョンを自動化 3. Git・各サービスともネイティブ非対応 4. 基本はcommit-msgフック＋CI／サーバー側検証 5. 近道はsquash merge＋PR/MRタイトル検証 1. 3
4. きっかけ：コミットログの表記揺れ セッションごとに書き方が変わる 1. Add login feature / ログイン機能を追加 人間とエージェントが混ざる 粒度も語彙も違う 2. 「何が変わったか」をコードから読み解く羽目に → ※本発表は公式ドキュメント調査に基づくもの 4
5. 仮説 ルールは少なく、形だけは揃える コミットの「意味」は1行目に機械可読な形で固定 検証はツールに任せる 人間とAIは「何を書くか」だけを考える 細かいルールを何十項目並べても守られない 5
6. Conventional Commits とは コミットメッセージのための軽量な規約 人間と機械の両方が読みやすい履歴を作る 源流はAngularのコミット規約 <type>[optional scope]: <description> [optional body] [optional footer(s)] 6
7. 基本構造 要素 type scope description body footer 必須 必須 任意 必須 任意 任意 内容 変更の種類（ feat 、 fix など） 影響範囲。 feat(parser): 短い要約 詳細。前に空行1行 Gitのトレーラー形式 7
8. type とSemVerの対応 type / 記法 SemVer fix: PATCH feat: MINOR または BREAKING CHANGE: docs: chore: など ! 仕様が義務付けるtypeは fix と feat だけ BREAKING CHANGE だけは大文字必須 MAJOR 影響なし 8
9. 「シンプルな秩序」と呼ぶ理由 覚えることは1行目の形・2つのtype・ ! くらい $ git log --oneline a1b2c3d feat(auth): add SSO login d4e5f6a fix: prevent racing of requests b7c8d9e docs: correct spelling of CHANGELOG 変更の種類が一目でわかる ツールがバージョンの上げ方まで判断できる 9
10. 記述例 feat(lang): add Polish language feat(api)!: send an email to the customer when shipped fix: prevent racing of requests Reviewed-by: Z Refs: #123 10
11. 公式FAQで押さえておきたいこと 大文字/小文字: どちらでもよいが一貫させる revert: revert type＋ Refs: フッター推奨 複数typeにまたがる: 可能なら分割 初期開発: リリース済み前提で運用 全員が規約を使う必要は？: 不要 squashならマージ時にメンテナーが整えられる 11
12. 全体像：どこもネイティブ対応していない 規約は書き方であって、各サービスの機能ではない 作り込みすぎるとシンプルさが台無し 設計で見るポイント 検証: どこで止めるか 2. squash: mainに残るのは何か 3. リリース自動化: CHANGELOG・バージョン 1. 12
13. サービス比較①：検証とsquash 観点 サーバー側検証 時 squash Git GitHub なし （Actionsで検証） PRタイトルを 既定にできる GitLab Push rules （Premium以上） テンプレート 既定 %{title} Bitbucket なし（アプリ） DC: フック Cloud: マージ時に編集可 単体: commit-msg （ローカル）／ pre-receive （自前サーバー） 13
14. サービス比較②：リリースと独自記法 観点 GitHub リリース自動化 release-please 独自記法 GitLab Bitbucket semantic-release semantic-release （公式プラグイン） semantic-release closing keywords closing patterns Smart Commits Fixes #123 Changelog: （専用なし） （Jira連携） 独自記法はbody・footerに共存できる 14
15. Git ：commit-msgフック npm install -D @commitlint/cli @commitlint/config-conventional echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js npm install -D husky npx husky init echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg はGitのトレーラーそのもの 注意： --no-verify で素通りできる footer 15
16. AI エージェントとの相性 規約違反 → コミット失敗 → エラーが返る エージェントはエラーを読んで書き直せる プロンプトで頼むより、失敗させて直させる （仮説・未検証） 16
17. GitHub ：squash merge＋PRタイトル検証 サーバー側の検証機能はない action-semantic-pull-request でPRタイトルを検証 設定「Default to PR title for squash merge commits」 → 個々のコミットは自由、mainだけ規約どおり 17
18. GitHub ：リリース自動化と注意点 リリースPRを自動作成 semantic-release: CIでタグ付け・リリース release-please: 注意 標準の自動生成リリースノートはPRのラベルで分類 → コミットのtypeは見ていない 18
19. GitLab ：Push rulesで止められる つの中で唯一、クラウド版でもpushを拒否できる Premium以上。実体は pre-receive フック 4 (?-m)^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?!?: .+ 複数行モードで評価 → (?-m) で先頭行だけ見る（未検証） 19
20. GitLab ：Changelogの注意点 テンプレートの既定は %{title} （MRタイトル） 標準のChangelog APIは Changelog: トレーラー で分類 → Conventional Commitsのtypeは見ていない 両方書くか、semantic-releaseに寄せる squash 20
21. Bitbucket ：Cloudは外側で守る にはサーバー側フックがない ローカルの commit-msg フック Pipelinesでcommitlint Marketplaceアプリのmerge check Data Centerならpush時に検証できる Smart Commitsとは本文・footerで両立 Cloud 21
22. どう組み合わせるか ローカル: commit-msg フックで書いた瞬間に弾く 2. PR/MR: squash＋タイトル検証でmainを揃える 3. サーバー: 使えるなら --no-verify も塞ぐ 4. リリース: release-please／semantic-release 1. ポイントは2番目 22
23. 秩序を求める範囲を絞る 秩序が必要なのはあとから読まれるmain 作業途中まで縛ると失敗と書き直しが増える 最後に残る1行だけを検証すれば負担は最小 公式FAQ：全員が規約を使う必要はない squashならメンテナーがマージ時に整えられる 23
24. 未検証・確認が必要なこと の正規表現の実挙動 Bitbucket Cloudでのsemantic-release構成 フックで弾かれたAIエージェントの自己修正力 「mainだけ規約どおり」でのバージョン決定 GitLab Push rules 今後、自分のリポジトリで確かめる予定 24
25. まとめ ルールは少ないのに、SemVerに直結する規約 どのサービスもネイティブ非対応 基本はフック＋CI／サーバー側検証 近道はsquash＋PR/MRタイトル検証 1 行目の形だけ揃え、最小限の仕組みで保つ 25
26. ご清聴ありがとうございました 26