チェンジログは誰が書いていて、誰が書くべきか

チームに誰がチェンジログを書くのかと尋ねると、正直な答えはたいてい「覚えている誰か」であり、 これはCIでチェンジログの項目を強制するがメカニカルな レベルで修正しようとしているのとまったく同じ失敗モードだ。しかし項目が存在することを強制して も、誰が良い項目を書く資格があるかは決まらない。その問いを飛ばしてしまうチームは、たいてい 強制しやすい人、通常はPRの作者に、それが本当に上手く書ける人かどうかを確認しないままデフォル トで頼ることになる。

なぜPRの作者が自動的に最良のチェンジログ執筆者にはならないのか

彼女は実装を知っているが、必ずしも影響を知っているわけではなく、それは異なる種類の知識だから だ。Conventional commitsはどこで力尽きるかは、 コミットメッセージ側からこのギャップを扱っている。fix(auth): reject expired refresh tokens は正しいが、顧客には何も伝えない。その修正を書いた人は、それを翻訳するのに最も不向きなことが 多い。何時間もそのバグの観点で考え続けたせいで、ユーザーが実際に何を経験したかという外部の 視点を失っているからだ。それは、実装を影響へと翻訳することが、そのものを作った経験とは別の スキルであり、コードにどれほど長けたエンジニアであっても習熟には練習が要るという、テクニカル ライターという職業が存在するのとまったく同じ理由だ。

それはプロダクトやサポートがすべての項目を代わりに書くべきだということか

いいえ、彼らは逆のギャップを持っているからだ。ユーザーにとって何が重要かは知っているが、実際 に何が出荷されたかを常に知っているわけではなく、それは読みやすいが範囲において時々誤っている 項目、まだフラグの背後にある機能に対する「今はXをサポートしています」という主張、あるいは 三つのうち一つのケースしかカバーしていないのに完了したと説明された修正を生み出す。開発者が 書いた項目の失敗モードは読みにくいが正確であり、PMが書いた項目の失敗モードは読みやすいが未検証 だ。どちらの役割も、良い項目に必要なものの両方の半分を所有していない。

実際に機能する所有権モデルはどのようなものか

変更に最も近い人からの下書きを、ユーザーに最も近い人がレビューし、全員が誰か他の人が問題を 捕まえてくれると想定する代わりに、最終的な文言に責任を持つ一人の指名された人物がいることだ。 下書きは、優れている必要があるよりも、存在して正確である必要のほうが大きい。開発者が書いた、何が変わったかを 正しく述べる粗い一文は、磨かれているが未検証のものよりも良い出発点だ。明確さのために書き直す ことは、正確さのために書き直すことよりも簡単だからだ。レビューのステップは、PMまたはサポート リードが下書きを読み、可読性のギャップを捕らえる唯一の質問をする場所だ。コードを見ていなくて もこれを理解できるだろうか、と。

常に同じ人が責任を持つべきか、それとも交代制であるべきか

指名され安定していることは、少なくとも最終承認については交代制に勝る。交代する所有者は、 チームの慣習をゼロから再導出する誰かによって毎回項目がレビューされることを意味し、それは まさに声が項目ごとに漂流し、読者がチェンジログが委員会によって書かれたことに気づき始める 仕組みだ。一人の人物、あるいは非常に小さな安定したグループは、時間をかけて判断を蓄積する。 いつ「改善しました」と言い、いつ具体的な数字を挙げるか、いつ修正が独自の項目を必要とし、 いつバッチにまとめるか。その判断は、作業を均等に分配することよりも価値がある。

下書き（開発者、PRから）:
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

レビュー済み（チェンジログ所有者、実際のPRと照合済み）:
「修正: 日付でソートされたエクスポートが、最初の
ページを超えると順序を無視した結果を返すことが
ありました。現在はすべてのページで一貫しています。」

小さなチームは一行のテキストのためにこれほど多くのプロセスを必要とするか

別々の人物としての役割ではないが、二つのステップはソロであっても依然として重要だ。一人だけの チームは開発者でありレビュアーでもあり、その規模で生き残る規律は、レビューを別個の精神的な パスとして行うことであり、修正を書くことからその説明を公開することへ、同じ呼吸の中で直接 飛び移らないことだ。小規模での罠は、外部から誰も強制しないために第二のパスを完全に飛ばして しまうことであり、二人目が足りないことではない。そのパスが捕らえるために存在する正確さの ギャップは、同じ人物が理論的には自分自身の盲点に気づくことができるという理由だけでは消えない。

最終的な項目に誰も責任を持たないとどうなるか

チェンジログは完全に失敗するのではなく、不均一に劣化する。それは読者が指摘するまで誰も気づか ないため、より悪い。ある項目は、書いた人が気にかけていたために鋭いままだが、他の項目は、書い た人が急いでいて公開前に誰も捕まえなかったために、「様々な改善とバグ修正」のように曖昧になる。 Keep a Changelogのフォーマット制約は、構造的な 逸脱、欠落した日付、間違ったカテゴリを捕らえるが、テンプレートの中には、技術的には正しく フォーマットされている曖昧な項目を捕らえるものは何もない。それはまさに、指名された所有者が 存在して埋めるべきギャップだ。

FAQ

チェンジログ所有者はエンジニアリングの役割であるべきか、プロダクトの役割であるべきか? 両方とも、その人が範囲を検証する技術的な流暢さと、外部の読者のために書くのに十分な実装から の距離の両方を持っているなら機能する。肩書きは、両方の半分をこなせるか、あるいは自分ができ ない半分について誰に尋ねればよいか知っているかどうかほど重要ではない。

オンコールのようなローテーションスケジュールはチェンジログの所有権に適していることがあるか? 量については時々、チームが小さすぎて一人がすべてをレビューできない場合はそうだ。声と判断に ついてはノーだ。それはまさにローテーションが侵食するものだからだ。安定した一人のレビュアー を維持しながら下書きの負担を共有するローテーションは、ドリフトなしにその利点を得る。

現在の所有権の設定に何か問題があることを示す最も早い兆候は何か? 正確だが読みにくい項目、あるいは読みやすいが範囲において間違っている項目が、誰が書いたかに 従うパターンで現れることだ。品質が一貫しているのではなく作者と相関しているなら、ギャップは 所有権にあり、執筆スキルにはない。

自動化は所有権がどれほど重要かを減らすか? 必要な執筆量を減らすが、必要な判断量は減らさない。チェンジログの自動化 は、パイプラインが安全に生成できるもの、フォーマット、公開、クロスポスティングを扱っている。 文言、グループ化、そして何が言及に値するかは、パイプラインのどれだけが自動化されているかに かかわらず、人間の決定であり続ける。

PRの作者とレビュアーが文言について意見が合わない場合はどうなるか? レビュアーの判断が優先される。彼らが答えている問い、つまり「外部の読者はこれを理解できるか」 こそが、その役割が守るために存在するものだからだ。だからといってエンジニアの読み取りが無価値 になるわけではない。意見の相違が文言ではなく正確さについてのものであれば、レビュアーは譲る。 範囲を正しく把握することは作者側の役割だからだ。文言をめぐる相違と正確さをめぐる相違を分けて 考えることが、これらの大半が膠着状態になるのを防ぐ。

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

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