Back to Details

verifying-changelog-in-framework

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Rules for Verifying CHANGELOG.md in Framework

Rules for Verifying CHANGELOG.md in Framework

  • フレームワークを利用するユーザー視点で、パッケージに変更が生じる場合は必ず CHANGELOG.md を更新します
    • 基本的に src/ 以下の private でないクラスやメソッドに変更があった場合は更新が必要です
    • この際、実装が破壊的変更（breaking change）を伴う場合は、SemVer における minor バージョンまたは major バージョンの更新で対応する必要があることに注意します
    • ただし、内部の不具合を修正するために生じる変更（バグフィックス）は影響度の小さい破壊的変更であれば patch バージョンの更新を許容します
  • Always update CHANGELOG.md when there are changes to the package from the perspective of framework users
    • Basically, updates are required when there are changes to non-private classes or methods under src/
    • Note that if the implementation involves a breaking change, you must address it by updating the minor or major version in accordance with SemVer
    • However, changes made to fix internal bugs (bug fixes) that are breaking changes with low impact are allowed to be addressed with a patch version update

Important Formatting and Content Rules

Important Formatting and Content Rules

変更に CHANGELOG.md を更新する際は、以下のフォーマットに従ってください。
  • フォーマットは Keep a Changelog に基づく
  • CHANGELOGは全てユーザー目線で見える変更を記述する
  • 実装した詳細を書くのではなく、そのサービスを利用する人（ユーザー）から見たときにどのような機能追加・変更・修正があったのかを端的に記載する
  • ユーザーから本フレームワークを見たときのいわゆるインターフェイスとなる外側部分についてどんな変化が起きたかを書くこと
  • 本フレームワークにどんな変化があったかではなく、ユーザーが使うときにどんな影響があるかを書くこと
  • PR や Issue の番号は 
    [#123](github.com/your-repo/issues/123)
    のようにリンク形式で記載する
  • システムやコード、クラスを主語にする
  • 変更点や追加内容等は端的に記載する
  • バグ修正の場合はどのような事象・問題が起きていたかを記載する
  • 代替手段がある場合は記載する
  • クラス名は多少冗長でもFQCNで書く
When updating CHANGELOG.md for changes, follow the format below.
  • The format is based on Keep a Changelog
  • The CHANGELOG should only describe changes visible from the user's perspective
  • Instead of writing implementation details, briefly describe what features were added, changed, or fixed from the viewpoint of the service user
  • Describe changes to the external parts that serve as the interface of this framework from the user's perspective
  • Focus on the impact on users when they use the framework, rather than the changes within the framework itself
  • PR and Issue numbers should be written in link format like 
    [#123](github.com/your-repo/issues/123)
  • Use systems, code, or classes as the subject
  • Briefly describe changes and additions
  • For bug fixes, describe the phenomenon or problem that occurred
  • If there are alternative methods, include them
  • Write class names using their FQCN even if it is somewhat verbose