baserproject baserCMS リリースノート（VERSION.txt）作成ガイド
plugins/baser-core/VERSION.txt に、前回リリースからの変更内容を追記する作業の手順書。
コミットログをそのまま貼るのではなく、利用者（baserCMS を使うサイト管理者・開発者）が読んで意味が分かる文章に翻訳するのがこの作業の本質。
VERSION.txt の書式
ファイル先頭は開発中バージョン、次にライセンスヘッダ、その下に凡例行があり、以降がリリースブロック。
5.4.0-dev
/////////// (ライセンスヘッダ) ///////////
CHG: 変更内容 / BUG: バグフィックス / NEW: 機能追加
[2026-07-30] basercms-5.3.0
- CHG [BC] リンク先URLに必須ラベルを表示する
- BUG [BC] ログインボタンの二重クリック防止を実装
- BUG [UL] ファイルの公開期間外に設定するとフロントで500エラーになる不具合の修正
[2026-07-30] basercms-5.2.9
...
- 新しいリリースブロックほど上に置く（凡例行の直下、既存の最新ブロックの上に挿入）。
- 1 行の書式は
- <NEW|CHG|BUG> [略号] 内容（半角スペース区切り、行頭は-）。 - Issue 番号がある場合は行末に
fix #NNNN。
手順
1. 対象ブランチを確認する
現在のブランチを対象とする。 他ブランチの内容は混ぜない。
git rev-parse --abbrev-ref HEAD
5.4.x にいるなら 5.4.x の履歴だけを対象にする。作業ブランチ（fix/... や security/...）にいる場合は、
本当にそのブランチのリリースノートを書くのかをユーザーに確認する。
2. 前バージョンとリリースバージョンをユーザーに確認する
ここは必ずユーザーに確認して確定させる。 既定値を提示したうえで AskUserQuestion で選んでもらう。
| 項目 | 既定値の求め方 |
|---|---|
| 前バージョン（比較の起点） | VERSION.txt 先頭のリリースブロック見出しのバージョン（例 basercms-5.3.0 → 5.3.0） |
| リリースバージョン（見出しに書く番号） | VERSION.txt 1 行目（例 5.4.0-dev → 5.4.0） |
| 日付 | 実行日（[YYYY-MM-DD]） |
タグの実在を確認する（タグ名はバージョン番号そのもの。v は付かない）。
git tag --sort=-creatordate
前バージョンのタグが存在しない場合は、比較の起点（タグ／コミット）をその場でユーザーに確認する。
3. コミットを収集する
git log 5.3.0..HEAD --no-merges --format=%h%x09%s
各コミットの変更ファイルは次で確認する（プラグイン判定に使う）。
git show --stat --format= <コミットハッシュ>
パイプや複合コマンドは使わず、単一コマンドで実行する（
AGENTS.mdのシェル実行方針）。
4. 利用者に不要なコミットを除外する
以下は VERSION.txt に載せない。
| 除外対象 | 判定の目安 |
|---|---|
| Merge コミット | git log --no-merges で除外済み。Merge branch ... |
| リリース作業そのもの | 「バージョン番号を変更」「VERSION.txt を更新」など |
| テストのみの変更 | 変更ファイルが tests/ 配下だけ。「〜Test が時々失敗する問題を修正」「テストを追加」 |
| CI / GitHub Actions / 開発環境 | .github/、docker/、*.yml のみの変更。Copilot 設定、PR 自動アサインなど |
| 依存パッケージの更新・Dependabot | 「axios を 1.18.0 に更新」「ビルドツール系の依存を更新」など |
| 今回のリリースで新規搭載したプラグイン内の修正 | そのリリースで初めて同梱されたプラグイン（例: 5.4.0 の BurgerEditor / MCP）の不具合修正・仕様変更 |
新規搭載プラグインの扱い: そのリリースで初めて同梱されたプラグインについては、プラグイン内の不具合修正・仕様変更を
個別の行にしない。利用者にとって「以前の版」が存在せず、「修正された」と書かれても意味がないため。NEW の 1 行に含める。
NEW [BE] リッチテキストエディタ「BurgerEditor」をコアプラグインとして標準搭載
↑ この 1 行に含める。搭載前に行った BurgerEditor 内の修正（アップロード制限の強化、
エディタ用CSSのパス修正など）は個別に書かない
例外: PHP・CakePHP の対応バージョンの変更は依存更新ではなく利用者に影響する仕様変更なので CHG として記載する。
- CHG [BC] PHP8.5対応
- CHG [BC] CakePHP5.2対応
内部リファクタリングやコメント修正など、利用者から見て挙動が一切変わらないものも除外してよい。 迷ったら「これを読んだ利用者が何か判断・行動できるか」で決める。
5. プラグイン略号を判定する
コミットの変更ファイルパス plugins/<name>/ から下表で変換する。複数プラグインにまたがる場合は、
利用者から見て主たる機能の略号を使う。
| 略号 | 対象 |
|---|---|
| BC | baser-core、および利用者から見て「システム全体」に属する変更。コア付随プラグイン（bc-admin-third / bc-front / bc-installer / bc-favorite / bc-widget-area / bc-content-link / bc-editor-template / bc-search-index / bc-theme-config / bc-theme-file）も BC に寄せる |
| CC | コンテンツ管理・カスタムコンテンツ（bc-custom-content、コンテンツ管理まわり） |
| BG | ブログ（bc-blog） |
| ML | メール（bc-mail） |
| UL | アップローダー（bc-uploader） |
| SO | SEO（bc-seo） |
| BE | BurgerEditor（bc-burger-editor） |
| MC | MCP（bc-mcp） |
| CL | BcColumn（BcColumn） |
表記揺れの正規化: 過去の履歴には UP（アップローダー）が混在するが、新規記載では UL に統一する。
既存の過去ブロックは書き換えない。
表にないプラグインが出てきた場合は、略号案を提示してユーザーに確認してから使い、この対応表にも追記する。
6. 利用者から見た 1 つの変更に集約する
同じ不具合・同じ機能に属する複数コミットは 1 行にまとめる。修正の途中経過、followup、レビュー指摘対応、 テスト追加は表に出さない。
例（4 コミット → 1 行）:
BcBurgerEditor アップロード時の拡張子制限を強化
BcBurgerEditor 編集フォームの FormProtection の除外指定を限定
BcBurgerEditor 拡張子制限とフィールド除外のテストを追加
BcBurgerEditor allowedAdmin を有効にした経路のテストを追加
↓
- BUG [BE] BurgerEditor でファイルアップロード時の制限が不十分だった問題を修正
7. NEW / CHG / BUG に分類する
| 種別 | 内容 |
|---|---|
| NEW | これまで無かった機能・画面・設定項目の追加 |
| CHG | 既存の仕様・挙動・表示の変更、改善、対応バージョンの変更 |
| BUG | 意図した動作をしていなかったものの修正 |
判断に迷うもの:
- 「バリデーションを追加した」→ 今まで通っていた入力が通らなくなる = CHG。ただし本来弾くべきものが弾けていなかったなら BUG。
- 「エラーメッセージを分かりやすくした」→ CHG
- 「500 エラーになる」「保存できない」「表示されない」→ BUG
8. 利用者に伝わる文章に書き換える
クラス名・メソッド名・変数名などの内部実装用語は、利用者が触る画面・機能の名前に置き換える。 1 行 1 文、簡潔に。末尾は「〜を修正」「〜に対応」「〜を追加」「〜を変更」で揃える。
| コミットログ（実装者視点） | VERSION.txt（利用者視点） |
|---|---|
Accept-Language にワイルドカードが指定されるとサイト全体が500になる不具合を修正 |
- BUG [BC] 特定のブラウザ設定でサイト全体が500エラーになる不具合を修正 |
固定ページ一覧で draft が NULL のレコードが除外される不具合を修正 |
- BUG [BC] 【固定ページ】一部のページが一覧に表示されない不具合を修正 |
BcBaserHelper->getContentsName でプラグインのコントローラー名が取得できず default になる件を修正 |
- BUG [BC] プラグインのページでコンテンツ名が正しく取得できない件を修正 |
BlogHelperTest::testPosts が乱数依存で時々失敗する問題を修正 |
（テストのみ → 記載しない） |
補足のルール:
- 画面名を頭に付ける場合は
【ユーザー管理】【ブログ】のように全角隅付き括弧を使う（既存ブロックの慣例）。必須ではない。 - 「〜という問題を解決」「〜する件を修正」など既存の言い回しに合わせてよい。冗長な前置きは削る。
- セキュリティ修正は、攻撃手法の詳細を書かず「〜が閲覧できてしまう問題を修正」程度に留める。
9. Issue 番号を付ける
コミットメッセージ本文・PR 本文から Issue 番号を拾い、あれば行末に fix #NNNN を付ける。
- マージコミット由来の
(#4503)のような PR 番号は落とす。 - Issue 番号が見つからないものは番号なしでよい。
- 複数コミットを集約した場合、代表となる Issue 番号 1 つを付ける。
- BUG [ML] 【メール】確認画面で送信時にバリデーションエラーが発生するとエラーになる件を修正 fix #4338
10. 並び替える
- カテゴリ順: NEW → CHG → BUG
- カテゴリ内はプラグイン順: BC → CC → BG → ML → UL → SO → BE → MC → CL（略号対応表の順）
[2026-08-27] basercms-5.4.0
- NEW [BC] ...
- NEW [BG] ...
- CHG [BC] ...
- CHG [CC] ...
- BUG [BC] ...
- BUG [BG] ...
- BUG [BE] ...
11. VERSION.txt に追記する
下書きの確認は挟まず、直接 plugins/baser-core/VERSION.txt に書き込む（差分でレビューする前提）。
- 挿入位置は凡例行
CHG: 変更内容 / BUG: バグフィックス / NEW: 機能追加の直下、既存の最新ブロックの上。 - 凡例行との間、および前ブロックとの間は既存の慣例どおり空行を空ける。
- ファイル 1 行目の
X.Y.Z-devはこのスキルでは触らない（リリース作業側の管轄）。
書き込み後、git diff plugins/baser-core/VERSION.txt で挿入位置と書式を確認し、
除外したコミットのうち判断が微妙だったものがあればユーザーに伝える。
チェックリスト
- 現在のブランチを確認した
- 前バージョンとリリースバージョンをユーザーに確認して確定した
- Merge / テストのみ / CI / 依存更新のコミットを除外した
- PHP・CakePHP の対応バージョン変更は CHG として拾った
- 略号が対応表どおり（
UPを使っていない） - 関連コミットが 1 行に集約されている
- 今回新規搭載したプラグイン内の BUG / CHG を個別に書いていない
- 内部実装の用語（クラス名・メソッド名）が残っていない
- PR 番号を書かず、Issue 番号だけ
fix #NNNNで付けた - NEW → CHG → BUG、その中でプラグイン順に並んでいる
- 凡例行の直下に挿入されている
関連スキル
- テスト実行:
basercms-unittest - コアプラグイン化に伴う追加:
basercms-core-plugin-convert - セキュリティ修正の対応:
basercms-security-advisory