changeloopブログ
リリースノートの実践
私たちがよく考えていることは二つです。誰かに読まれるリリースノートの書き方と、changelogを手作業で管理するのをやめる方法です。ニュースレターも登録も不要です。記事だけをどうぞ。
バグ修正のリリースノートの書き方と使える書き換え例
バグ修正のリリースノートは、症状、影響を受けた人、次の行動を示せば役に立つ。書き換え例と、セキュリティとデータ損失のルールを解説する。
リリースノートの実践1分で読めます
ソフトウェア製品で顧客フィードバックを求める方法と使える質問文
顧客フィードバックは、ユーザーが作業を終えた直後に、その場で具体的な質問を一つだけ投げて集める。場面別の質問文、避ける聞き方、回答の扱いを紹介する。
フィードバックループ1分で読めます
プロダクトロードマップの例:6つの形式と、それぞれの失敗パターン
Now/Next/Laterなど6形式のロードマップを、現実的な項目例で解説する。各形式が向く読者と崩れる典型的な原因、形式の選び方、最新に保つ方法を紹介する。
フィードバックループ1分で読めます
頻繁にリリースするチームのためのリリース管理プロセス
スコープ計画から振り返りまでの七つのステップで、リリース管理プロセスを説明する。各担当者と完了条件、リリース種別ごとの違い、DORA指標を紹介する。
エンジニアリング1分で読めます
あらゆる種類の変更に使えるリリースノートの例文集
新機能、改善、バグ修正、破壊的変更など8種類のリリースノート例文を、請求書アプリを題材に示し、なぜ機能するのかを一つずつ解説する。
リリースノートの実践1分で読めます
Stripe APIのバージョニングの仕組みと、真似すべき点
Stripe APIは、アカウントごとに日付付きバージョンを固定し、リクエストごとに上書きもできる。その仕組みとWebhook、コスト、真似すべき点を解説する。
APIの変更1分で読めます
チェンジログは誰が書いていて、誰が書くべきか
チェンジログは誰が書くべきか。PR作者は何が変わったかを、PMはなぜ重要かを知っている。どちらか一方だけでは、顧客に使える項目は書けない。
エンジニアリング1分で読めます
緊急リリースノート: 実時間の時間的プレッシャーの下で書く
緊急リリースは、数日ではなく数分でリリースノートを書く必要がある。通常の執筆プロセスが前提とする時間的余裕がない中で、何を書くかを説明する。
リリースノートの実践1分で読めます
Protobufの破壊的変更：ワイヤー上で生き残るもの
Protobufの破壊的変更は、URLではなくワイヤーフォーマット上で起きる。安全なフィールド変更と、全クライアントを静かに壊す変更の違いを説明する。
APIの変更1分で読めます
チェンジログのファイル形式、JSONかYAMLか単なるMarkdownか
チェンジログの形式は、ページやウィジェットに使えるか人間にしか読まれないかを決める。Markdown、JSON、YAMLの代償と移行の判断基準を説明する。
エンジニアリング1分で読めます
重複する機能リクエスト、声を失わずに統合する
重複する機能リクエストの統合は、不注意だと言い回しを失う。言い回しを残す統合手順、誤った一致の見分け方、提出者への通知と功績の扱いを説明する。
フィードバックループ1分で読めます
バージョン番号のないGraphQLの非推奨化
GraphQLにはURLにv1やv2がなく、フィールドはディレクティブで一つずつ非推奨化される。破壊的変更の定義、受信者の把握、安全な削除時期を説明する。
APIの変更1分で読めます
API移行ガイドをどう書けばいいか、その方法
API移行ガイドは、互換性のない変更を障害ではなくチェックリストに変える。何を含め、誰がいつ書くか、チェンジログだけでは足りない理由を説明する。
APIの変更1分で読めます
GitHub Actionsのためのチェンジログチェック
GitHub Actionsのチェンジログチェックは、項目がなければマージを拒否する。記憶頼みの運用が続かない理由と、チェック自体が壊すものも解説する。
エンジニアリング1分で読めます
顧客を失わずに機能リクエストを断る方法とは
ループを閉じるとは、出荷を伝えることだけではない。難しいのは関係を損なわずに断ることだ。悪い拒否の原因と、そのまま使える文例を説明する。
フィードバックループ1分で読めます
フィーチャーフラグのリリースノート：何を、いつ伝えるか
フィーチャーフラグでは、マージと出荷が同じ出来事ではない。ループを閉じる正しいタイミングと、緊急停止スイッチの場合の扱いを具体例とともに説明する。
フィードバックループ1分で読めます
機能リクエストを見失わずに追跡していく方法
機能リクエストの追跡は、届かないか、集めて放置されるかで失敗する。両方に耐える仕組み、自動トリアージ向けのラベル、次に作る物の決め方を説明する。
フィードバックループ1分で読めます
機能リクエストが実はバグレポートである時
新しい設定を求めるチケットは、隠れたバグの回避策かもしれない。誤ったラベルは優先順位を狂わせる。顧客の言葉から見分ける方法と判断者を説明する。
フィードバックループ1分で読めます
サポートチケット対機能リクエスト：どちらを信じるべきか
サポートチケットと機能リクエストボードは、異なるものを測っている。片方の急増をもう片方と同一視すると優先順位を誤る。どちらを信じるべきかを説明する。
フィードバックループ1分で読めます
Gitタグ、リリース、そしてあなたのチェンジログ
Gitタグ、リリース、チェンジログのエントリは、一つの出来事の三つの記録だ。混同するとずれる理由と、三つが噛み合うべき形を具体例とともに説明する。
エンジニアリング1分で読めます
社内向けリリースノート：他に誰が知るべきか
サポートと営業は、混乱した顧客からローンチを知ることが多い。社内向けリリースノートは顧客向けと形が異なり、顧客より先にチームへ届くよう設計する。
リリースノートの実践1分で読めます
社内向けAPIチェンジログ：他チームにとって何が変わるか
公開APIと違い、社内向けAPIチェンジログには二フロア先の読者がいる。この違いの由来、呼び出し側の台帳を誰が持つか、実務での対応を説明する。
APIの変更1分で読めます
モバイルアプリのリリースノート：文字数制限が何を削るのか
App StoreとPlay Storeで見えるのは数行だけで、リンクも張れない。その狭い枠でどこを削るべきか、強制アップデートの場合はどうするかを説明する。
リリースノートの実践1分で読めます
モノレポのチェンジログ：一つにまとめるか、パッケージごとか
モノレポのチェンジログは、全体で一つでもパッケージごとでもよい。正しい形を決めるのは構造ではなく、誰がログを読み、何を探しているかという点だ。
エンジニアリング1分で読めます
新機能をどう発表するか(沈黙にしないために)
新機能の発表の多くは、誰も読み返さないチャネルで静かに消える。どこで発表し、何を最初に言い、求めていた人へどう直接届けるかを説明する。
リリースノートの実践1分で読めます
積み上がる機能リクエストにどう優先順位をつけるか
追跡とグループ化とラベル付けをしても、どれを先に出すかという難問は残る。実際に機能するフレームワークと、生の投票数が隠してしまうものを説明する。
フィードバックループ1分で読めます
エンタープライズ向けリリースノート：一つのアカウントで何が変わるか
エンタープライズ向けリリースノートは、プライベートビルド上の顧客に合わせて調整する。公開版をそのまま送ると、未提供の変更で混乱を招くおそれがある。
リリースノートの実践1分で読めます
セマンティックバージョニングとあなたのチェンジログ
セマンティックバージョニングは、エントリを読む前に、リリースが呼び出し側をどれだけ痛めうるかを伝える。各番号の約束と対応するエントリの責任を説明する。
エンジニアリング1分で読めます
APIのSunsetヘッダー、それを送るべきタイミング
APIのSunsetヘッダーは、バージョンがいつ応答を止めるかを機械可読な形でクライアントに伝える。RFC 8594の定めと、ブラウンアウトの利点を解説する。
APIの変更1分で読めます
Webhookチェンジログ、誰も求めなかった破壊的変更
Webhookのペイロード変更は、受信側が拒否できないため静かに壊れる。破壊的変更の定義、ペイロードのバージョニング、受信者の把握と安全な移行を扱う。
APIの変更1分で読めます
チェンジログとは何か、そして何が含まれるべきか
チェンジログとは、製品で何が変わったかを日付付きで記録したものだ。影響を受ける人々のために書く。含める内容、置き場所、配信方法を説明する。
リリースノートの実践1分で読めます
APIチェンジログ: 何を公開し、誰が読むのか
APIチェンジログの読者は、自分のコードが来月も動くかを知りたい人だ。各エントリが負うべき内容と置き場所、開発者が購読する方法を説明する。
APIの変更1分で読めます
人々が追い続けるチェンジログページの作り方
チェンジログページを作る価値があるのは、誰かが戻ってくると期待できる場合だけだ。置き場所、各エントリの要件、フィード、ウィジェットを説明する。
エンジニアリング1分で読めます
読まれるプロダクトアップデートメールのテンプレート
読まれるプロダクトアップデートメールとは、求めていた本人に届くものだ。テンプレートの構造、四つのメール種別、件名、セグメント、同意の要否を説明する。
リリースノートの実践1分で読めます
開発者を失わずにAPIを非推奨化する方法
非推奨化は、日付の付いた一つの約束だ。具体的なスケジュール、通知テンプレート、レスポンスヘッダー、サンセットを事故にしないための決定的な一手を説明する。
APIの変更1分で読めます
呼び出し元のためのAPIバージョニングのベストプラクティス
壊れるものだけをバージョン管理し、呼び出し元に見える場所へ置き、古い版も期日まで動かし続けよう。代表的な四つのスキームを長所と短所で比較する。
APIの変更1分で読めます
破壊的変更に該当するものと、安全な出荷方法
破壊的変更とは、正しい呼び出し元が耐えられない変更のこと。何が該当し何が該当しないか、CIでの検出方法、安全な出荷の手順を解説する。
APIの変更1分で読めます
チェンジログ側から顧客フィードバックループを閉じる方法
フィードバックループが閉じるのは、依頼した本人に出荷を伝えたときだけだ。四つのステップのどこで途切れるか、チェンジログが最適な理由を説明する。
フィードバックループ1分で読めます
チェンジログの項目になる機能要望テンプレート
出荷された機能の依頼を見つけられなければ、機能要望は役に立たない。依頼を振り分けるラベルの付け方と、チェンジログが後で読む各項目の中身を説明する。
フィードバックループ1分で読めます
issueトラッカーから作る三列の公開ロードマップ
公開ロードマップは未来の約束だから、小さく保ち、すでに追跡しているissueから組み立てる。各項目はラベル一つで列から列へ動かす形にしよう。
フィードバックループ1分で読めます
チェンジログの自動化と、その限界について
収集、フォーマット、公開は自動化してよいが、選定と言い回しは自動化してはならない。チェンジログ実務での境界線と、それが動いたときの影響を見ていく。
エンジニアリング1分で読めます
チェンジログとリリースノート、その違いはどこにあるのか
チェンジログは何が変わったかを残す継続的な記録、リリースノートは読み手のために選んだメッセージだ。両者の本質的な違いを分かりやすく整理する。
リリースノートの実践1分で読めます
Conventional commitsからチェンジログへとつなげる方法
Conventional commitsはチェンジログを導出可能にするが、読みやすくはしない。この慣習が与えるもの、限界、人間が埋めるべき隙間を具体的に説明する。
エンジニアリング1分で読めます
本当にユーザーに読まれるリリースノートを書くための実践的な方法
バグ修正と性能改善とだけ書いても、リリースノートにはならない。すべての項目が答えるべき一つの質問と、それに沿った書き直しの実例を紹介する。
リリースノートの実践1分で読めます
Keep a Changelog、実際に導入してみて分かったこと
Keep a Changelogの仕様は一ページで短いが、導入するとチームは逸れていく。仕様が語ること、意図的に残したこと、現実で破綻する点を検証する。
エンジニアリング1分で読めます
本当に価値のあるリリースノートのベストプラクティス集
多くのベストプラクティスは文体の助言にすぎない。ここでは読者の行動を変える実践と、人気だが実はカーゴカルトにすぎない三つの慣習を取り上げる。
リリースノートの実践1分で読めます