リリース手順 (yarn release)
WingStats Manager（broadcast-Overlay）のリリース作業を yarn release 1 コマンドに集約するためのドキュメント。push と tag push は依然として人間の手作業で、CLAUDE.md の「リリース管理」原則を構造的に守る前提で書かれている。
🚧 自動化の範囲: version bump / CHANGELOG 追記 / release commit / annotated tag 作成。 🚫 自動化しない:
git push、git push --tags、package.json直接編集、CHANGELOG.md 直接編集（このスクリプト経由でのみ許可）。
0. 前提
- ブランチが
main（または--allow-branch <name>で明示的に許可） - working tree がクリーン（既ステージ / 未追跡変更なし）
yarn typecheck/yarn lint/yarn test:unit/yarn buildがローカルで passgit fetch --tagsが走る（スクリプトが自動で叩く）- 直近 tag 〜 HEAD に 少なくとも 1 つの Conventional Commit（
feat:/fix:/perf:等）がある
1. 基本手順
# 1) どの type で bump するかを決めてコマンドを叩く
yarn release patch # 1.2.3 → 1.2.4
yarn release minor # 1.2.3 → 1.3.0
yarn release major # 1.2.3 → 2.0.0
yarn release --version 1.5.0 # 明示指定（現状より大きい値のみ）
# 2) 事前チェックが順に流れる
# ✓ branch / clean tree / fetch / tag duplicate / yarn ci 系
# 3) CHANGELOG.draft.md がエディタで開く
# Conventional Commits を section 別に分類した markdown が入っている
# 必要に応じて文面を整え、エディタを閉じて保存
# 4) スクリプトが続きを実行
# - package.json の version 書き換え
# - CHANGELOG.md の先頭にドラフトを挿入
# - release commit + annotated tag を作成（local のみ）
# 5) 「次のコマンド」が表示される
# git push origin main
# git push origin v1.2.4
# → これは **手動で**実行してください2. オプション
| フラグ | 用途 |
|---|---|
--no-edit | エディタを開かずドラフトをそのまま採用（CI / 自動化時のみ推奨） |
--dry-run | ファイル / commit / tag を一切書き換えず、出力だけ確認 |
--skip-checks | yarn typecheck / lint / test:unit / build を skip（直前に手で全部走らせた前提） |
--allow-branch <name> | main 以外で release を許可（hotfix リハーサル等） |
--draft <path> | ドラフトの出力先を指定（既定: ./CHANGELOG.draft.md） |
-h / --help | ヘルプ |
3. 失敗時の戻し方
スクリプトは 作業内容を消さない設計（git reset --hard を使わない）。各失敗ケースの状態:
| 失敗ポイント | スクリプトがやること | 手動で必要なら |
|---|---|---|
| prechecks 失敗 | 何も書き換えていない、そのまま exit 1 | 警告に従って fix |
| エディタ異常終了 | CHANGELOG.draft.md を消し、何も書き換えていない | — |
| draft が空 | CHANGELOG.draft.md を消し、何も書き換えていない | — |
| ファイル書き換え後の失敗 | git restore --staged --worktree で package.json / CHANGELOG.md を HEAD に戻す | — |
| commit 後の tag 失敗 | git reset --soft HEAD^ で release commit を取消 + ファイル復元 | — |
| Ctrl+C 中断 | 同上（commit があれば soft reset、ファイル変更は restore） | — |
release を完全に取り消したい
push する前なら:
git tag -d vX.Y.Z # local tag を消す
git reset --soft HEAD^ # release commit を取り消し（変更は staging に残る）
git restore --staged --worktree -- package.json CHANGELOG.mdpush 済みで取り消したい場合は、tag を delete + revert commit を別途作成する（ここではフォローしない、慎重に）。
4. push（手動）
スクリプト終了時の表示に従う。必ず両方 push する:
git push origin main
git push origin vX.Y.Ztag を push すると .github/workflows/release.yml が起動し、GitHub Release + NSIS / Portable build が自動で作られる。tag を push しないとビルドは走らない。
5. CHANGELOG ドラフトの作り方（参考）
scripts/release/generateChangelog.ts の純粋関数で、vX.Y.Z..HEAD の commit を以下のルールで分類する:
| commit type | section |
|---|---|
feat: / feature: | ✨ 新機能・アップデート |
fix: / revert: | 🐛 バグ修正 |
perf: / refactor: / style: | 🔧 改善 |
docs: / test: / build: / ci: / chore: | 🛠 内部 / ドキュメント |
type!: または body に BREAKING CHANGE: | 💥 破壊的変更（最上段に出る） |
Merge pull request / Merge branch で始まるコミットと、release: vX.Y.Z 系の自前リリース commit は CHANGELOG に含めない。
6. 関連リンク
CLAUDE.mdリリース管理項 — 自動化禁止事項・原則CHANGELOG.md— 出力先 / 既存書式の参照.spec-workflow/specs/release-workflow-helper/— 設計と実装ログ