# Basercms Release Note

> baserCMS の plugins/baser-core/VERSION.txt に、リリース分の変更履歴（NEW/CHG/BUG）をコミットログから生成して追記する手順。「VERSION.txt を更新して」「リリースノートを作って」「変更履歴をまとめて」「今回のリリース分の変更点を書き出して」「前回リリースからの差分を VERSION.txt に反映」等のときに参照する。対象ブランチの決定、前バージョン／リリースバージョンの確認、利用者に不要なコミット（Merge・テストのみ・CI・依存更新）の除外、プラグイン略号（BC/CC/BG/ML/UL/SO/BE/MC/CL）の判定、利用者視点への言い換え、Issue 番号の付与、NEW→CHG→BUG の並び替え、VERSION.txt への挿入までを収録。

- Skill: `baserproject/basercms-release-note` (Agent Skill)
- Install (CLI): `npx skillmds@latest add baserproject/basercms-release-note`
- Raw SKILL.md: https://api.skillmd.com/api/skills/baserproject/basercms-release-note/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: baserproject (https://skillmd.com/u/baserproject)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/baserproject/basercms-release-note

---


# 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. 並び替える

1. **カテゴリ順**: NEW → CHG → BUG
2. **カテゴリ内はプラグイン順**: 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`