チェンジログの自動化と、その限界について

チェンジログの自動化がうまく機能するのは、収集、分類、公開を自動化し、選定と言い回しで止まるときだ。すべてを自動化すればフォーマットされたgit logを出荷することになる。何も自動化しなければ、チェンジログはリリース前に記憶から一気に書かれることになる。有用な問いは、どれだけ自動化するかではなく、どの部分を自動化するかだ。

チェンジログ自動化のプロジェクトは、二つの方向のどちらかで失敗し、どちらも最初の設計ミーティングの時点で予測可能だ。自動化しすぎないと、チェンジログは誰かが更新すべき文書になり、それは短い籤を引いた誰かによって断続的に更新されることを意味する。自動化しすぎると、フォーマットされたgit logになる。完全で正確だが、誰にも読まれない。

チェンジログのどの部分を自動化すべきか

四つのステップのうち三つ。収集と公開は完全に。分類は人間の上書きを伴う一次通過として。選定と言い回しは決して自動化しない。

収集。 変更が起きる場所（コミット、PR、チケット）から取り出してリストにすること。これは完全に自動化しよう。人間はこれが苦手で、退屈で、締め切りの下で飛ばされがちなステップだ。Conventional commitsやPRのラベルが通常の原材料になる。

分類。 何かがAdded、Fixed、Changed、Deprecated、Removed、Securityのどれかを決めること。コミットタイプやPRラベルから一次通過を自動化し、人間に上書きさせよう。精度はメタデータだけで約80パーセントであり、誤った20パーセントはまさに重要な項目に集中している。あいまいさが重要性と相関しているからだ。

選定と言い回し。 読者に何を伝えるべきか、どう伝えるかの決定。これは自動化してはならない。 これが成果物のすべての価値だ。それ以外はすべてロジスティクスにすぎない。

公開。 完成した項目をページ、フィード、メール、アプリ内ウィジェット、Slackチャンネルへ届けること。完全に、一つのソースから自動化しよう。実際に手作業の大半が費やされるのはここであり、ほとんど誰もそれを数えていない。これはまた、変更を求めた人にそれが出荷されたと伝えられるステップでもあり、それがチェンジログ側からのフィードバックループの完結のすべての内容だ。そのステップのメールに関する半分は、プロダクトアップデートメールのテンプレートで扱っている独自の形を持つ。

最後の点は考える価値がある。チームはチェンジログを執筆の問題と見なしがちで、その後ほとんどの時間を配布に費やす。項目をメールツールにコピーし、アプリ内用に再フォーマットし、Slackに貼り付け、ドキュメントページを更新する。執筆には一時間かかる。コピーは各リリースごとに一時間かかり、それが永遠に続く。それは機械が担うべき部分だ。

境界線が動くと何が起こるか

上に動かすとgitのダンプになる。 コミットからの完全な自動化は、顧客の前にbump deps、fix flaky test、wip、address review commentsを出荷することになる。これをやったすべてのチームは、その後フィルターを追加し、そのフィルターは別の名前で再導入された選定のステップにすぎず、使い勝手はさらに悪化している。

下に動かすと一気書きになる。 完全に手動の収集は、項目がリリース時に記憶から書かれることを意味する。それはKeep a Changelogが冒頭から警告しているモードであり、静かに劣化していく。チェンジログは、誰も時間がなかったまさにその週まで、維持されているように見え続ける。

チェンジログ自動化のパイプラインはどんな形か

四つのステップと、下書きが公開される場所に置かれたちょうど一つの人間のゲート。

1. マージ時にPRから下書きの項目を導出する。ラベルまたはコミットの接頭辞からタイプを、最初の下書きとしてタイトルを、PRへのリンクを、記録された著者を。それを未リリースのバケツに入れる。
2. 誰でもいつでもどの下書きも編集でき、編集は安価だ。ほとんどは一行が書き直される。
3. リリースを切るには、バケツ内のすべての項目が編集されるか、明示的に内部向けとしてマークされている必要がある。このゲートが設計のすべてだ。これがなければ、忙しい週に下書きが未編集のまま出荷される。
4. 公開は、リリースされたセットからの分岐だ。公開ページ、フィード、メール、ウィジェット、Slackの投稿。一つのソース、複数のレンダリング、コピーなし。

ステップ3は人間が必要な唯一の場所であり、下書きがまともであればリリースあたり約十分かかる。顧客の要望が関わる場合、下書きはそれが閉じるissueも運び、それがステップ4に要望者へ知らせることを可能にする。機能要望のテンプレートは、そのリンクが生き残るように設計されている。このステップが、より広いリリースの流れの中でどこに位置するかは、リリース管理プロセスで扱っている。

自動化はあなたのデータに何を求めるか

チェンジログがMarkdownファイルであれば、上記のどれも機能しない。ファイルは再パースなしに五つの表面にレンダリングできず、文章をパースすることが、見出しの半分だけを表示するウィジェットになってしまう理由だからだ。

項目は構造化されている必要がある。タイプ、日付、バージョンまたはリリース識別子、対象読者、本文、リンク。それがあれば、ファイル、ページ、フィード、メールはすべてビューになる。この構造的な点こそが、ツールを選ぶ前に正しくやる価値のある唯一のことだ。後から安く追加できないものだからだ。必要とするすべての変更に対して実際に項目が作られない限り、これらのどれも機能しない。CIでチェンジログ項目を必須化するは、その手順を記憶に任せる代わりに、項目のないマージをパイプラインに拒否させる方法を扱っている。

私たちはchangeloopを構築している。そこではチェンジログはまずフィードであり、その後にページになる。だからこれを中立的な推奨ではなく利害関係として読んでほしい。料金はカード不要の無料リポジトリ一つ分であり、その形を見るには十分だ。チェンジログツールは、私たちが競合する製品も含めて他に何があるかのまとめであり、チェンジログジェネレーターは、パイプラインに踏み出す前に導出を見たい場合に、収集と分類のステップをブラウザで行ってくれる。

テスト

マージされた変更と、その変更があなたのリポジトリを読まない顧客に見えるようになるまでの分数を数えてみよう。その分数の大半が誰かがツール間でテキストをコピーしている時間であれば、必要な自動化は執筆ではなく公開の側にある。

FAQ

AIはチェンジログを書けるか? 下書きを作ることはできる。マージされたpull requestを与えられたモデルは、たいていの場合タイトルと本文の使える最初の下書きを生成し、それは収集と分類がより良く行われたものだ。読者に何かを伝えるべきかどうかという選定、そして最終的な言い回しは、依然として対象読者を知る人間を必要とし、そのゲートなしに下書きを公開するパイプラインは、間違ったステップを自動化したことになる。

チェンジログジェネレーターとチェンジログの自動化の違いは何か? ジェネレーターはコミットを一度、要求に応じてフォーマットされたリストに変換する。自動化はマージのたびに動き、未リリースのバケツを維持し、リリースを人間のレビューに条件付け、一つのソースからすべての表面に公開する。ジェネレーターは、手動で実行されるパイプラインの最初のステップだ。

チェンジログはコミットとpull requestのどちらから自動化すべきか? 変更の単位がPRであるpull requestからだ。タイトルと説明は変更全体について一度書かれ、PRは自分が閉じるissueをリンクする。コミットベースの導出は、コミットが単位であり慣習に従っているときに機能する。

自動化が内部の変更を公開してしまうのをどう防ぐか? chore、ci、test、refactor、依存関係の更新をデフォルトで内部向けとして分類し、公開への昇格を意識的な行為にしよう。逆のデフォルト、つまり誰かが隠さない限り公開、という状態が、bump depsが顧客に届いてしまう仕組みだ。

この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。

changeloopの関連ページ： changelogツール比較, changelogジェネレーター