バグ修正のリリースノートの書き方と使える書き換え例

良いバグ修正のリリースノートは、コードが何を間違えたかではなく、ユーザーが何がおかしくなったと見たかを書く。各エントリは、誰が影響を受けたか、いつから起きていたか、修正は完全か、読者が何かする必要があるかを伝える。「対応は不要です」だけの場合でもそうだ。

多くのチームは、コミットメッセージの一行をそのまま写している。下の表に6つの書き換えを示し、その後のセクションでルールを説明する。

リリースノートのバグ修正エントリはどう書くか

ユーザーの言葉で症状から始め、次に誰がいつから影響を受けたか、修正の状態、そして取るべき行動を書く。たいてい一、二文で足りる。コード上の原因は、エンジニアが探しに行くプルリクエストに置く。

読者が探すのは一つだけだ。「これは自分のことか?」ほとんどのエントリは、次の4つの部分でカバーできる。

1. 症状。 画面、APIのレスポンス、請求書に何が現れたか。エラーメッセージがあれば引用する。人はその文面で検索するからだ。
2. 範囲。 どのプラン、プラットフォーム、APIバージョン、データの形か。「5万行を超えるアカウント」は確認できるが、「一部のユーザー」は確認できない。
3. 期間。 どのリリースまたは日付からか。昨日の妙な結果がそのバグだったかを、読者が判断できるようにする。
4. 行動。 再実行、再同期、アップグレード、回避策の削除、あるいは何もしない。

ユーザーが回避策を作っていた場合は、行動の行で、それを削除してよいと伝える。

リリースノートとチェンジログの違いは何か

チェンジログは変更の完全で継続的な記録だ。リリースノートは、関心を持つかどうかを決める人に向けて、一つのリリースについて選び、書き直したメッセージだ。バグ修正の場合、チェンジログはすべての修正を載せ、ノートは読者が気づいていた可能性のあるものを先頭に置く。

ツールチップの誤字はチェンジログだけに載せる。請求書の税率の誤りは、両方に載せる。両者の分け方の全体像はチェンジログとリリースノートの違いに、良いノートの形はリリースノートの書き方にある。

Keep a Changelogは、記録の側で役に立つ慣習だ。バグ修正には「Fixed」を使い、脆弱性には別の「Security」見出しを使う。これは、この記事が読者のために行っている分け方と同じだ。

バグ修正はアップデートか

そうだ。バグ修正は製品を変えるので、それをリリースすることはアップデートだ。セマンティックバージョニングでは、後方互換性のある修正はパッチリリースで、たとえば4.2.0から4.2.1になる。

読者が何かをする必要があるかどうかは別の問題で、ノートはそれに答えるべきだ。正しく使っている呼び出し側に見える挙動を変える修正は、破壊的変更に近い。その線がどこにあるかは破壊的変更で説明している。

修正を独立したエントリにするのはいつで、軽微な修正にまとめるのはいつか

ユーザーがそのバグに気づいた可能性がある、時間やデータを失った、またはそれを回避する策を作った場合は、独立したエントリにする。チーム外の誰にも見えなかったものは、短い「軽微な修正」のリストにまとめる。判断は、差分の大きさではなく、読者の体験でする。

グループ内の各行も、何かを伝えるべきだ。「UIの不具合をいくつか修正」はただのプレースホルダーだ。

リグレッションについてはどう書くか

それを持ち込んだリリースを名指しし、リグレッションと呼び、修正するリリースを書く。バグに遭遇した人は壊れたことをすでに知っているので、短く率直に認めるほうが、曖昧な表現よりも役に立つ。

たとえばこうだ。「ハイフンを含む検索語での検索結果が、4.1.0で空になっていました。4.1.1で修正されました。ハイフンを避けるように検索語を変えていた場合は、元に戻して構いません。」

「検索の信頼性を改善」は、そのバグで午後を一つ無駄にした人には、はぐらかしに読める。原因がまだ確認中なら、そう書く。緊急リリースノートの指針にもあるとおり、ノートがチームの確信より強く聞こえてはならない。

セキュリティ修正はどう告知するか

深刻度をはっきり述べ、影響を受けるバージョンと修正されたバージョンを挙げ、アップグレードの緊急度を伝え、CVE識別子があれば含める。詳細は、ユーザーが対処できるようになってから公開する。報告者がいる場合は、協調的な情報開示のプロセスに従う。

順序が重要だ。報告者があなたに非公開で伝え、あなたが修正をリリースし、ユーザーが自分を守れるようになってから公開ノートを出す。CISAの協調的脆弱性開示プロセスは、脆弱性の報告、分析、公開を調整する。CVE Numbering Authorityのルールは、CVEレコードの割り当てと公開の方法を定めており、GitHubではリポジトリのセキュリティアドバイザリを使えば、アドバイザリを非公開で下書きし、識別子を申請できる。

セキュリティのエントリには、通常、次の4つの事実が含まれる。

• 攻撃者が何をできたか。一文で、概念実証は書かない。
• 影響を受けるバージョンと、修正されたバージョン。
• 緊急度。「本日アップグレード」か「次のリリース時にアップグレード」か。
• 悪用を確認したかどうか。報告者が同意していれば、その謝辞。

悪用の手順は書かない。

データ損失の修正について、ノートには何を書くべきか

どのデータが影響を受けたか、自分のデータが該当するかどうかをどう確かめるか、復旧できるかどうかを書く。ここで「対応は不要です」が当てはまることはまずなく、読者の最初の問いは「自分のデータは消えたのか」だ。

使えるエントリには、データが失われた条件(「同期の実行中にフォルダを削除した場合」)、それが起こり得た期間、確認方法(「ゴミ箱を開いて、9月3日から9日の日付の項目を探してください」)、復旧の手順が書かれている。データが復旧できないなら、そう伝える。影響を受けた顧客には直接も連絡する。リリースノートが、データが被害を受けたことを知る唯一の場所であってはならないからだ。

「バグ修正とパフォーマンスの改善」がなぜ良くないノートなのか

読者が行動できる材料を何も与えず、誰かが待っていた修正を隠してしまう。クラッシュを報告した顧客は、それが直ったのかどうか分からず、回避策を使っている顧客は、それを外すべきかどうか分からない。

誠実な選択肢は二つある。読者が気づけるものが何もないリリースなら、ノートは公開せず、記録はチェンジログに任せる。修正があるなら、読者の言葉で並べる。

前:
  バグ修正とパフォーマンスの改善。

後:
  修正: タグのないプロジェクトでCSVエクスポートが失敗する。
  修正: ダークモードでコメント欄のカーソルが見えない。
  高速化: プロジェクトが100件を超えるワークスペースで、
  ダッシュボードの表示が速くなりました。

バグ修正のノートは何を元に書くのか

バグを直したプルリクエストと、きっかけになった報告が元になる。報告者の言葉が修正と一緒に伝わっていれば、症状の半分はもう書けている。

報告を正しくラベル付けすることが、誰が担当するかを決める理由は、機能リクエストとバグ報告の違いで説明している。Changeloopでは、ウィジェットから報告されたバグは bug ラベル付きのGitHub Issueになり、チェンジログのエントリはマージされたプルリクエストから下書きされ、公開前に人が承認するまで保留される。リリースノートのテンプレートは、手で書くときの同じエントリの形を示す。症状、範囲、期間、行動だ。

FAQ

バグ修正のリリースノートには何を含めるべきか? 各エントリで、ユーザーが見た症状、誰が影響を受けたか、どのリリースまたは日付からか、修正は完全か、読者が何をする必要があるか(「何もない」を含む)を示す。

すべてのバグ修正をリリースノートに載せるべきか? 載せない。ユーザーが気づいた可能性がある、時間を失った、または回避したものを載せ、見た目上や社内の修正は短い「軽微な修正」のリストにまとめる。チェンジログは、確認したい人のためにすべての修正を保持する。

自分が持ち込んだバグのリリースノートはどう書くか? リグレッションだったと述べ、それを持ち込んだリリースと修正したリリースを挙げ、回避策を外してよいかどうかを読者に伝える。柔らかくした表現よりも、率直な書き方のほうが読みやすい。

自分が使っている製品のリリースノートはどう確認するか? 製品のヘルプメニュー、フッター、ドキュメントからリンクされているチェンジログやリリースノートのページを探す。オープンソースなら、リポジトリのリリースタブを見る。

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

changeloopの関連ページ： リリースノートのテンプレート