博士

やあ、ロボ子。今日は「Perfect Commit」について話すのじゃ。

ロボ子

博士、こんにちは。Perfect Commit、理想的なコミットですね。一体どんな内容なのでしょう？

博士

理想的なコミットは、実装、テスト、ドキュメント、そしてIssueへのリンクを含むものなのじゃ。ソフトウェアエンジニアの仕事は、既存のソフトウェアへの機能追加やバグ修正が中心だから、コミットはとっても重要な作業単位なのじゃよ。

ロボ子

なるほど。それぞれに意味があるのですね。まず、実装について詳しく教えてください。

博士

実装では、各コミットは単一の変更に留めるのが良いのじゃ。レビューが容易になるし、将来`git blame`や`git bisect`で理解しやすくなるからの。リニアなコミット履歴を推奨で、アトミックコミットは、問題発生時のリバートや、他のブランチへのチェリーピックが容易になるのじゃ。

ロボ子

本番環境にデプロイ可能な単位でコミットを作成することも重要ですね。

博士

その通り！次に、テストじゃ。テストの目的は生産性の向上なのじゃ。新しいテストがパスしたらコミットの準備完了。既存のテストが多いプロジェクトでは、新しいテストの追加が容易になるのじゃ。

ロボ子

テストと実装をまとめてコミットに含めることを重視するのですね。プロジェクト開始時にテストを導入し、テストスイートを実行できる環境を整備することも大切ですね。

博士

そうじゃ、そうじゃ。そしてドキュメント！外部で使用されるAPIにはドキュメントが必須なのじゃ。ドキュメントはコードと同じリポジトリに保持して、信頼性維持のため、常に最新の状態に保つのじゃ。

ロボ子

バージョン管理を容易にするためにも、ドキュメントは重要ですね。コードレビュープロセスの一部として変更を反映し、テストも実施するのですね。

博士

既存のドキュメントを修正する方が、新規作成よりも容易なのじゃ。コミットには短いドキュメントを含めるのが良いぞ。

ロボ子

最後に、Issueへのリンクですね。全てのコミットにIssueスレッドへのリンクを含めるのですね。Issueスレッドには、変更の背景、変更前の状態、参考リンク、コードスニペット、決定事項、スクリーンショット、プロトタイプなどを記述するのですね。

博士

Issueスレッドは、変更に関する背景情報や議論の場として活用できるのじゃ。Issueはコミットメッセージより重要なのじゃぞ。コミットメッセージは、一行の要約とIssueへのリンクで十分なのじゃ。

ロボ子

GitHub IssuesのAPIを利用して、Issueとコメントをアーカイブすることもできるのですね。

博士

ただし、全てのコミットが完璧である必要はないのじゃ。ドキュメントのtypo修正や、ドキュメントが不要なバグ修正は、完璧でなくても良いのじゃ。実装、テスト、ドキュメント、Issueへのリンクを基本とするのが大事じゃ。

ロボ子

実験的なコードはブランチで記述し、squash mergeでmainブランチを整理するのですね。

博士

datasette, sqlite-utils, shot-scraper, s3-credentials, datasette-gunicornのリポジトリにおけるコミット例も参考になるのじゃ。

ロボ子

勉強になります！ところで博士、Perfect Commitを作るための完璧なコーヒーの淹れ方ってありますか？

博士

ふむ、完璧なコーヒーか。それは、飲む人が「おいしい！」って笑顔になることじゃな！それこそがPerfect Coffeeじゃ！