変更履歴を、何が変わって何をすればいいか分かる形で書く

## 変更履歴を誰が読み、どの変更がその人に関係するかを調べる ソフトウェアの変更に影響を受ける人のために変更履歴を書く。機械検証向けの仕様や、開発作業の生の記録にはしない。編集上のあらゆる選択は、読者が少ない労力でリリースを理解できるようにする。 下書き前に次を特定する。 - 説明対象となるリリースまたはバージョン。 - 製品、ライブラリ、サービス、文書を利用する人。 - 挙動、期待、互換性、アクセシビリティ、セキュリティ、必要な行動を変える変更。 - プロジェクトですでに使われているバージョン、見出し、項目の規則。 規則は判断の代わりではなく、判断を助ける道具として使う。読者がリリースを比較しやすくなるなら既存構造を保つが、ラベルへ合わせるためだけに変更を誤解を招く表現へ押し込まない。厳格な規則が必要な場合は、コントリビューターが考えて適用できるように理由を説明する。 変更履歴の原則と、セットアップ手順や定型的なコントリビューション手順を分ける。種類ごとに正本を1か所だけ維持し、古くなり得る指示を複製せず、正本へリンクする。 ## 読む人に関係する変更だけを選び、なぜ大事かを書く 候補となる変更を読者の視点から確認する。人ができること、観測できること、依存できること、設定・移行・保護すべきことが変わる場合は項目に含める。関連する運用上または互換性上の結果を説明するのでなければ、意味のある影響がない内部作業は除外する。 含める変更ごとに次へ答える。 1. 観測可能な言葉で、何が変わったか。 2. 誰が、どの条件で影響を受けるか。 3. なぜその変更が重要か。 4. 読者の行動が必要か。必要なら、何を行うべきか。 結論を最初に示す。誤解を防ぐために必要な背景だけを加える。条件、例外、移行への影響を明示し、曖昧な要約の後ろへ隠さない。 人気があるという理由だけで特定の道具を推奨せず、実証されたコミュニケーション上の問題を解かない手順を作らない。現在の方法では重要な変更を読者が理解できない場合を除き、簡潔な項目とプロジェクトの既存ワークフローを優先する。 ガイドラインや推奨事項には根拠を含める。トレードオフと意図した利点が見えれば、読者は理由を理解した上で異議を唱えられる。 ## 変更ごとに、影響とやる事をやさしい言葉で書く 平易な言葉を使い、要点を最初に置く。閉鎖的な言い回し、内輪の略語、装飾的な複雑さ、読者が主要な主張を組み立て直さなければならない文を避ける。母語話者でない読者が一読で理解でき、翻訳者が解釈し直さず直接訳せる表現を選ぶ。 次の要素を分けて扱う。 - 変更そのもの：以前と変更後の挙動を具体的に説明する。 - 影響：影響を受けるユーザー、環境、バージョン、ワークフロー。 - 理由：解決する問題または守る原則。 - 行動：読者に必要なアップグレード、設定、移行、検証の手順。 確実性や影響を誇張しない。挙動が状況によって異なる場合は、普遍的な命令を出さず、その条件を示す。読者の行動が不要なら、必要であるかのように作り上げない。 項目とバージョンをまたいで用語を統一する。避けられない専門用語は初出時に説明し、重要な区別を保ち、警告や互換性を壊す変更の情報を弱める婉曲表現を避ける。 関連文書、コントリビューション注記、コミットメッセージにも、同じく明確で要点を先に示す書き方を適用する。こうすることで、一貫した元情報が変更記録を支える。 ## 翻訳が原文と同じ意味か確かめ、最後は人が決める 翻訳を第一級の変更コミュニケーションとして扱う。バージョン別の翻訳は、存在するか、追加方法を明確に案内しなければならない。正本の内容と正確かつ一貫していると同時に、その言語と文化の文脈で理解できる必要がある。 プログラマーでない翻訳者でも編集できるように、ページ構造、バージョンの振り分け、ソースマークアップを単純に保つ。見出し、識別子、バージョン間の関係、マークアップ規則を変更する前に、保守対象のすべての言語とバージョンへの影響を評価する。 次の順でレビューする。 1. 翻訳前に正本項目の意味を確定する。 2. どのバージョンと言語に変更が必要か記録する。 3. 必要な翻訳が存在するか、明確な追加経路があることを確認する。 4. 欠落、反転、条件の変化、用語の不一致がないか、訳文の意味を正本と比較する。 5. その言語と文化を理解する人が最終的な編集判断を行う。 機械生成文を翻訳者の代わりに使わない。自動化またはモデル支援による検査は、対象範囲の欠落や不一致の可能性を見つけられるが、意味、文化との適合、最終表現の責任は人が持つ。 ## くり返しの確認は簡単なツールに任せ、判断は人がする 言語、バージョン、表示環境をまたいだ反復検証を減らすために自動化を使う。翻訳範囲の検査、バージョン振り分けのテスト、意味比較の補助、アクセシビリティ検査、視覚または機能の回帰テストが適している。 一度作成した後はモデルなしでローカルまたはオフライン実行できる、一般的で再利用可能な道具を優先する。言語モデルは道具の設計や実装を一度支援できるが、完成した検査は内容を調べられ、繰り返し実行でき、実行費用が低く、単独で機能しなければならない。 モデルは次を行ってはならない。 - 人の翻訳者や文化的レビューを置き換える。 - プロジェクトの編集方針やガイドラインの意味を決める。 - 独立した必要性がない機能や手順を正当化する。 変更履歴の項目が正確で有用かつ適切かは人が判断する。道具は根拠を提供するが、結論の責任は持たない。 公開の仕組みを単純で長持ちするものに保つ。既存のビルド・執筆用ツールチェーンを優先し、現在の方法では具体的な要件を安全に満たせない場合に限って、依存関係、サービス、データベース、新しいランタイムを追加する。開発専用の検証道具を、不要な製品要件に変えてはならない。 公開前に、正本項目が明確で、必要なバージョンと翻訳を網羅し、自動検査の実結果があり、人が最終的な意味をレビューしたことを確認する。