【ITニュース解説】How to Standardize Commit Messages with Commitlint and Custom Rules

ソフトウェア開発の現場では、複数のエンジニアが協力して一つのプログラムを作成する。その過程で、誰が、いつ、どのような変更を加えたのかを記録することが非常に重要になる。この記録が「コミットメッセージ」と呼ばれるもので、プログラムの変更履歴に添えられる短い説明文のことだ。しかし、このコミットメッセージの書き方がバラバラだと、後から変更内容を追跡したり、特定の機能がどの作業（タスク）と関連しているのかを特定するのが難しくなるという問題がしばしば発生する。

記事で紹介されているチームも同様の問題に直面していた。彼らは「Jira」というプロジェクト管理ツールを使って作業を管理しており、一つ一つの作業には「TWSF-1234」のような固有の識別番号（タスクID）が割り当てられていた。しかし、コミットメッセージにこのタスクIDを含めるかどうかは個々のエンジニアに任されており、結果として、どのコードの変更がどの作業に対応しているのかが分からなくなり、プログラムの進捗状況や変更の意図を把握するのが困難になっていたのだ。

この問題を解決するために、彼らが導入したのが「Commitlint（コミットリント）」というツールだった。Commitlintは、エンジニアが作成するコミットメッセージが、あらかじめ決められたルールに沿っているかどうかを自動的にチェックしてくれるツールだ。これにより、Gitと呼ばれるプログラムの変更履歴管理システムに、一貫性があり、誰にとっても分かりやすいきれいな履歴を残すことができるようになる。Commitlintは、一般的なコミットメッセージのルール（例えば、変更の種類を示すプレフィックスをつけるなど）を適用することもできるし、プロジェクト固有の特別なルールを自分たちで作成して適用することも可能だ。このチームは、既存の一般的なルールを使いつつ、さらに独自のルールを追加することで問題を解決しようとした。

彼らが作成したカスタムルールは、コミットメッセージの「スコープ」と呼ばれる部分に、JiraのタスクIDを特定の形式で必ず含めるというものだった。コミットメッセージは通常、「タイプ(スコープ): 説明」という形式で書かれることが多い。例えば「feat(新機能): ログイン機能を追加」のような形だ。このチームは、スコープの部分に「TWSF-1234」のような形式でタスクIDを強制的に含めるようにしたのだ。

具体的な設定方法を見てみよう。Commitlintの設定は、「commitlint.config.js」というファイルに記述する。このファイルでは、まず一般的なコミットルールセットを「@commitlint/config-conventional」として継承し、それに加えて「twsf-task-scope」という名前のカスタムルールを追加した。この「twsf-task-scope」ルールは、コミットメッセージのスコープ部分が「TWSF-」で始まり、その後に数字が続くパターン（例えば「TWSF-1234」）に合致するかどうかをチェックするように定義されている。このチェックには「正規表現」という、文字列のパターンを記述するための特別な記法が使われている。もしスコープがこのパターンに合致しない場合、Commitlintはコミットを拒否し、「Scope must follow the pattern TWSF-<task-number>, e.g., TWSF-1234」という具体的なエラーメッセージを表示して、正しい形式での入力を促すようになっている。

このルールが適用された場合、例えば「feat(TWSF-1234): add export report button」のようなコミットメッセージは、スコープに「TWSF-1234」という正しい形式のタスクIDが含まれているため、有効なコミットとして受け入れられる。しかし、「fix(report): fix export bug」のようなコミットメッセージでは、スコープが「report」となっており、タスクIDの形式に従っていないため、Commitlintによって拒否され、コミットはできない。これにより、全てのコミットメッセージに必ずタスクIDが含まれるようになる。

この仕組みを実際にプロジェクトに導入するには、いくつかの手順が必要だ。まず、「npm」というツールを使ってCommitlintとその関連パッケージをプロジェクトにインストールする。これは、プロジェクトでCommitlintを使えるようにするための準備作業だ。次に、先ほど説明した「commitlint.config.js」ファイルをプロジェクトのルートディレクトリに作成し、定義したルールを記述する。

そして最も重要なのが、CommitlintをGitの作業の流れに組み込むことだ。これには「Husky（ハスキー）」というツールが使われる。Huskyは、Gitが特定の動作（例えば、プログラムの変更をコミットする時）を実行しようとするときに、あらかじめ設定したスクリプトを自動的に実行させる「フック」という仕組みを提供する。この場合、「commit-msg」というフックを設定する。これは、コミットメッセージが入力された直後に実行されるフックだ。具体的には、プロジェクト内の「.husky/commit-msg」というファイルを作成し、その中に「npx --no-install commitlint --edit "$1"」というコマンドを記述する。このコマンドは、入力されたコミットメッセージをCommitlintに渡し、定義されたルールに基づいてチェックさせるためのものだ。これにより、エンジニアがコミットしようとすると、自動的にCommitlintが起動し、メッセージを検証するようになる。ルールに違反していれば、コミットは停止され、エラーメッセージが表示されるため、エンジニアは正しい形式に修正してから再度コミットする必要がある。

この一連のシステムを導入した結果、チームのコミットメッセージは劇的に改善されたという。全てのプログラムの変更が明確にJiraのタスクと結びつくようになり、どの変更が何のために行われたのかが容易に追跡できるようになった。これにより、他のエンジニアがコードレビューを行う際や、新しいプログラムを本番環境にデプロイする際、さらには過去の変更履歴を監査する際にも、作業がはるかにスムーズに進むようになったのだ。

Commitlintを使って独自のルールを作成し、それをプロジェクトに適用することは、開発の透明性を高め、チーム全体の連携を強化するための非常に効果的な手段である。特に大規模なプロジェクトや、複数のエンジニアが関わるプロジェクトにおいて、コミットメッセージの標準化は、将来的なメンテナンス性やトラブルシューティングの効率を大きく向上させる重要な取り組みと言えるだろう。