Rules for Verifying CHANGELOG.md in Framework
-
フレームワークを利用するユーザー視点で、パッケージに変更が生じる場合は必ず CHANGELOG.md を更新します
-
基本的に src/ 以下の private でないクラスやメソッドに変更があった場合は更新が必要です
-
この際、実装が破壊的変更(breaking change)を伴う場合は、SemVer における minor バージョンまたは major バージョンの更新で対応する必要があることに注意します
-
ただし、内部の不具合を修正するために生じる変更(バグフィックス)は影響度の小さい破壊的変更であれば patch バージョンの更新を許容します
Important Formatting and Content Rules
変更に CHANGELOG.md を更新する際は、以下のフォーマットに従ってください。
-
フォーマットは Keep a Changelog に基づく
-
CHANGELOGは全てユーザー目線で見える変更を記述する
-
実装した詳細を書くのではなく、そのサービスを利用する人(ユーザー)から見たときにどのような機能追加・変更・修正があったのかを端的に記載する
-
ユーザーから本フレームワークを見たときのいわゆるインターフェイスとなる外側部分についてどんな変化が起きたかを書くこと
-
本フレームワークにどんな変化があったかではなく、ユーザーが使うときにどんな影響があるかを書くこと
-
PR や Issue の番号は #123 のようにリンク形式で記載する
-
システムやコード、クラスを主語にする
-
変更点や追加内容等は端的に記載する
-
バグ修正の場合はどのような事象・問題が起きていたかを記載する
-
代替手段がある場合は記載する
-
クラス名は多少冗長でもFQCNで書く