RustNL 2024番外編、GitのアクティビティからChagelogを生成するgit-cliffを紹介する

RustNL 2024ではないが、Rustつながりの番外編として2023年11月19日から21日にイタリアのフィレンツェで開催されたRustLabというカンファレンスから、Gitのアクティビティログからソフトウェアリリースには欠かせないChangelogを生成するgit-cliffというソフトウェアに関するセッションを紹介する。カンファレンスについては以下の公式イベントページを参照して欲しい。

●公式サイト：RustLab 2023

RustLabは2024年も開催予定となっており、2024年11月9日から11日の3日間開催される。

●2024年のイベント：RustLab

プレゼンテーションを行ったのはトルコ在住のプログラマーOrhun Parmaksiz氏だ。Parmaksiz氏はShuttle.rsというRustを使った開発者向けのPaaS的なサービスを提供するソフトウェアを開発する企業の社員である。またRustによるオープンソースソフトウェア開発で生計を立てているエンジニアで、Rustを使ったキャラクターベースのターミナルUIの開発ツールであるRatatuiの開発者でもある。

Shuttle.rsはサーバーやデータベースなどのバックエンドのインフラストラクチャー側の設定をRustのコードから実装できるというInfrastructure-as-Codeの一歩先を行くソフトウェアを提供している。通常のIaCはYAMLファイルで構成を定義し、それをGitのリポジトリーで管理し、インフラを操作するコマンドを直接叩かずにすべての情報を一か所に集約することで自動化を進めるという発想だが、Shuttle.rsはそれをRustのプログラミング言語で操作するというのが最大の違いだ。

●Shuttle.rs：https://www.shuttle.rs/

今回は、デベロッパーとしての悩みを解決するために、Git上でデベロッパーが行ったアクティビティからソフトウェアリリースには必須のChangelogを作成するツールをゼロから開発したという経緯を解説する内容となった。

RustLab 2023でセッションを行うParmaksiz氏

動画は以下から参照して欲しい。

●動画：Turning Git commits into changelog with Git-Cliff

Arch Linux/Alpine LinuxのメンテナーでもあるParmaksiz氏

セッションは解決したい課題の確認、可能な解決方法の紹介、git-cliffが開発された経緯、そして実装の内容などとなっている。

セッションの内容を紹介

デベロッパーの視点でGitを使って開発を行い、ソフトウェアに対してxx.xx.xxなどのバージョン番号フォーマットを使い、自動化をしたいと思っているという前提でソフトウェアのリリースを行うとしたら、当然、リリースノートを作成する必要があることを確認。参加者はRustのデベロッパーなので、ここは既知の前提と言ったところだろう。

Rustのデベロッパーが納得する前提条件

その上でChangelogについてはWikipediaの記述を引用して紹介。バグ修正や新機能などがリストアップされ、そのリリースについての変更点が漏れなく理解できるフォーマットとなっていることを説明した。

ChangelogのWikipediaの記述を引用して説明

そしてサンプルとしてのChangelogを見せて、バージョン番号、日付、追加／変更／削除された内容がリストとして表示されていることを示している。

サンプルのChangelogを紹介

Gitにも標準機能としてShortlogという機能があるが、これはあくまでもユーザーごとに行われたアクティビティをリスト化しているだけでChangelogとしては不十分と説明した。

git shortlogでは不十分

他にもさまざまなツールがあるが、どれもParmaksiz氏にとっては不十分であったとして、Rustでゼロから開発することを選んだと説明した。

他のツールを紹介。どれも満足できるものではなかった

そしてChangelogの作成は難しくはないが、手間のかかる面倒なタスクであり、それの自動化を助けるのがConventional CommitsとSemantic Versioningであると説明。この二つの内容についてはLIFULLのエンジニアが書いたブログ記事が参考になるだろう。

●参考：Conventional Commitsについて

要はGitでのコミットに際して一定の記法を採用して、デベロッパーによるコミットの個人差をなくし、粒度や意図を均一化しようという発想だ。

Conventional CommitsとSemantic VersioningでChangelog作成を自動化

具体的な例を挙げて説明。ここでは機能追加、修正、ドキュメント追加などを、種類ごとにマークダウン化していることがわかる。

時系列になっているバラバラのログを種類ごとに整理

git-cliff開発の経緯は2021年5月にさかのぼる。ここでは当初のアイデア、ゼロから開発しようと決めた記録が紹介された。

git-cliff開発に至る経緯。2021年5月8日に開発することを決めた

その上で必要な処理を整理。ここではGitリポジトリーの読み取り、コミットのパース、Chagelogの生成、書き出しという段階に整理されている。

git-cliffに必要な処理を整理

ここからは実際のRustのソースコードを示しながら解説を行った。Gitの読み取りについては複数のツールが存在していることを紹介し、その中からgit2というライブラリーを使用することに決めたという。

git2を使ってリポジトリーをオープン

機能追加（feature）、修正（fix）などのConventional Commitのコマンドをパースしてメッセージを配列に格納するコードを説明。

パースする処理を解説

結果として、マークダウン形式で0.1.0というバージョン番号の修正内容のリストと機能追加のリストが生成されていることを説明した。

マークダウンで書かれたChangelogの内容例

そしてソフトウェアの機能を分解したフロー図を紹介。ここでは構成を読み取る部分とGitのコミットを処理する部分、それにマークダウンにレンダリングする部分にわかれている。

git-cliffの処理を機能に分解して解説

この処理に利用した外部のモジュールについても説明を行った。Rustでプログラムを開発する際、再利用できる外部モジュールが多数存在することはエコシステムのためには必須だ。ここではアーギュメントのパース、構成情報、Gitへのアクセス、テンプレートについてclap、git2、Teraなどのライブラリーを利用していることを紹介した。

利用した外部モジュールの紹介

ここでTeraについても、式や変数を使ってマークダウン化できるテンプレートエンジンであると紹介した。

Teraの紹介

●参考：https://keats.github.io/tera/

git-cliffを使って生成されたChangelogを紹介。項目が簡素なリスト化されていて読み易くなっている。

生成されたChangelogを紹介

git-cliffの使い方、CLIを紹介。ここではインストールから構成ファイルの編集、実行方法などを簡単に紹介している。

git-cliffの使い方を紹介

また構成ファイルであるTOML^※ファイルの内容についても簡単に触れた。このソースコードではリストのヘッダーに追加する絵文字などが表示されており、シンプルながら可読性を高めたいという意図を感じる。

※TOML：設定ファイルのフォーマットの一種。Tom's Obvious, Minimal Languageのアクロニム。Tomは作者の名前から。

構成ファイルの内容を説明

git-cliffの使い方としてさまざまなパターンがあることを説明。リリースには使われなかったコミットだけを集約する機能や、コミットのレンジを設定してその範囲内のコミットだけを使って生成する機能などが用意されていることを紹介した。

git-cliffのさまざまな使い方を紹介

実際にrelease-plzというcrateでは、Rustのパッケージをリリースする操作を自動化する機能を実装しており、その中でgit-cliffがChangelog生成に使われていることを紹介した。

release-plzというパッケージで使われているgit-cliff

またWeb UIが用意されていることも紹介した。

git-cliffのWeb UIを紹介

最後に2021年の10月以降、GitHubのスターの数も劇的に増加していることを紹介。多くのRustデベロッパーから信頼されていることを示してセッションを終えた。

デベロッパーである自身のニーズから使えるツールはないか検索し、結果として最適なツールがないことを理解した上で開発、公開し、多くのユーザーからの賛同を得るというのはオープンソースソフトウェアとしては王道と言える。ちなみに最新バージョンである2.4.0ではGitHub以外にGiteaでホストされているリポジトリーにも対応したことが明らかになった。

●参考：What's new in 2.4.0?

自身が所属するShuttle.rsであるRustのバックエンドをサービスとして提供するという、ビジネスとも相乗効果があるツール開発はビジネスの観点から見ても最適なミッシングピースだったと言えるだろう。ツールがカバーする領域も明確に定義され、コミュニティも小規模ながら活発に活動しているようだ。今後のParmaksiz氏の活躍に注目していきたい。