verifying-changelog-in-framework
外部公開を想定したフレームワークにある CHANGELOG.md の内容が適切かどうかを確認するスキルです。CHANGELOG.md を更新する際、またはレビューする際に利用します。
When & Why to Use This Skill
This Claude skill automates the verification and review of CHANGELOG.md files for software frameworks to ensure high-quality release documentation. It enforces 'Keep a Changelog' standards and Semantic Versioning (SemVer) principles by analyzing code changes in the source directory. By focusing on a user-centric perspective, it helps maintainers clearly communicate functional impacts, breaking changes, and bug fixes, ensuring that documentation remains consistent, professional, and useful for end-users.
Use Cases
- Automated Pull Request Reviews: Automatically verify if CHANGELOG.md has been updated whenever public classes or methods in the 'src/' directory are modified.
- SemVer Compliance Auditing: Ensure that breaking changes are correctly categorized as major or minor version updates, preventing accidental versioning errors in public frameworks.
- User-Centric Documentation Refinement: Transform technical implementation details into clear, end-user focused descriptions that explain how changes affect the framework's interface.
- Standardized Formatting Enforcement: Validate that all entries follow specific formatting rules, such as linking to GitHub Issues/PRs and using Fully Qualified Class Names (FQCN) for clarity.
- Release Readiness Checks: Perform a final audit of the changelog before a release to ensure all bug fixes include descriptions of the original issues and provide alternative solutions where applicable.
| name | "verifying-changelog-in-framework" |
|---|---|
| description | "外部公開を想定したフレームワークにある CHANGELOG.md の内容が適切かどうかを確認するスキルです。CHANGELOG.md を更新する際、またはレビューする際に利用します。" |
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](github.com/your-repo/issues/123)のようにリンク形式で記載する - システムやコード、クラスを主語にする
- 変更点や追加内容等は端的に記載する
- バグ修正の場合はどのような事象・問題が起きていたかを記載する
- 代替手段がある場合は記載する
- クラス名は多少冗長でもFQCNで書く