generate-release-notes

name: generate-release-notes description: "次回リリースのリリースノート下書きを生成する。GitHub Releases に掲載するリリース告知文（冒頭の概要文・付箋ブロック・What's Changed 箇条書き）を、前回リリースタグ以降のコミット・PR から自動で整理し /tmp に出力する。リリース直前にユーザーから実行される想定"

KonomiTV の GitHub Releases に掲載するリリースノート全体の下書きを生成するスキル。 冒頭のリリース告知文・付箋ブロック (NOTE/WARNING 等)・## What's Changed の箇条書きまでを一括で出力する。 ユーザーが次のバージョンをリリースする直前に実行し、/tmp/konomi-tv-release-notes-draft.md に Markdown ファイルを出力する。

このスキルの目的

リリースノートの執筆はユーザー本人にしか書けない文体・判断が求められる高負荷な作業であり、この負荷がリリース頻度の低下に直結していた。 このスキルの目的は ユーザーの過去のリリースノートの文体・構成・ニュアンスを忠実に再現し、ユーザーの手修正を最小限に抑えた下書きを生成すること にある。

単なる changelog の羅列ではなく「この人が書いたリリースノートに見える」品質が求められる。 具体的には:

• 文体の再現: カジュアルだが正確。太字・下線・絵文字の使い方、体言止めと動詞終わりの使い分け、サブリストの粒度まで過去リリースと揃える
• 強調の判断: 目玉機能は🎉＋太字＋下線で派手に、フィードバック対応は出典を明記、外部起因のバグ修正はその経緯に言及する傾向がある
• 省略の判断: 内部リファクタ・CI 修正・定型コミットは積極的に省略し、ユーザーに見える変更だけを載せる
• 付箋の意図: NOTE/WARNING 等の付箋ブロックは「ダウンロード前に読んでほしい」注意書きとして毎回意図的に掲載されている

過去のリリースノートの実例は以下のファイルに収録している。スキル実行時は必ず目を通し、文体・トーンを合わせること。

• past-intro-examples.md — 冒頭告知文の実例集
• past-release-notes-examples.md — What's Changed 箇条書きの実例集

前提

• 出力されたファイルはユーザーが GitHub Releases のリリース編集画面にコピペし、加筆訂正・画像追加などを行った上で公開する
• したがって、出力内容は 完成形ではなく下書き でよい。ただし過去のリリースノートと同じ文体・構成に極力近づけること
• Dependabot PR 一覧・外部コントリビューター PR 一覧・New Contributors セクションは GitHub の「Generate release notes」ボタンで自動生成される。 このスキルではこれらを出力する必要はない。ユーザーが GitHub 側の自動生成結果と、このスキルの出力をマージして最終版を作る
• gh CLI が認証済みの前提で使ってよい

リリースの粒度判定と書き分け

書き分けの軸は バージョン番号そのもの ではなく 「告知文で目立たせる価値のある目玉 (新機能・大規模改善) が含まれているか」 である。 バージョン番号はあくまで補助的な目安にすぎず、最終的にはコミット内容を見て判断する。

目玉ありリリース (典型例: マイナーリリース v0.13.0 → v0.14.0)

新機能の追加や大きな UX 改善など、ユーザーがアップデートする動機になる目玉が1つ以上ある ケース。 コミット数が多いマイナーリリースが中心だが、パッチリリースでもユーザー要望対応で新機能を一つ入れたなど、目玉に相当する変更があるなら同じ扱いでよい。

• 告知文: 目玉を 太字+下線+絵文字 で派手に強調し、その背景や使い方も含めて1〜3段落で紹介する
• 箇条書き: 機能追加/重要な改善/バグ修正のカテゴリごとに整理。目玉項目はネストしたサブリスト (- ) で経緯や使い方を補足する
• 過去実例: past-intro-examples.md の v0.13.0 / v0.12.0 / v0.11.0 / v0.10.1 (※ v0.10.1 はパッチリリースだが NX-Jikkyo 対応という目玉があったため強調している)、past-release-notes-examples.md の v0.12.0 / v0.11.0

目玉なしリリース (典型例: 不具合修正主体のパッチリリース v0.14.0 → v0.14.1)

機能追加がほとんどなく、不具合修正と細かな改善が中心のケース。 そもそも目立たせる対象がないので、無理に強調しない。 ユーザーは「何が直ったか」を一覧したいだけで、各修正の背景説明までは求めていない。

• 告知文は2〜3行の総括にとどめる。太字+下線での長文強調を入れない
  • 「v0.X.0 リリース後に判明したいくつかの不具合を修正したパッチリリースです。」のような一文を導入とし、続く2〜3行で「どの領域の修正が中心か」を簡潔に書く程度に抑える
  • 太字を使うのは導入の一文と、ベータ版定型文の太字部分のみ。個別修正は太字で強調しない
  • 個別の修正の経緯 (どのコミットで何をしたか) は告知文に書かない。すべて箇条書き側に任せる
  • 過去実例: past-intro-examples.md の v0.10.1 のような目玉がある場合と比べると、目玉なしの場合の告知文はこれよりさらに薄くなる
• 箇条書きはネストしたサブリスト (- ) を原則として使わない
  • バグ修正が主体になるため、各項目を1行の太字で淡々と並べる方が見通しが良い
  • サブリストを使ってよいのは、修正の経緯が複雑で1行では誤解を招くケースに限る
  • 「TSID が含まれないため〜」のような技術的背景は箇条書きの本文に書く必要はなく、Issue 側を参照してもらえばよい
  • 過去実例: past-release-notes-examples.md の v0.10.1 の箇条書きスタイル (シンプルな1行項目の並び)

判別の手順

1. Step 0 でバージョン番号を受け取る
2. Step 1 のコミット読解時に、Add: prefix のコミット・大きな Update: での機能追加コミット・ユーザーが体感できるレベルの大規模改善コミットを数える
3. 上記が 1つ以上あれば目玉あり、ゼロなら目玉なし として扱う
4. 判別が曖昧 (例: 「これは目玉として扱うほどでもないが、ユーザーにとっては嬉しい機能拡張」など) な場合は、ユーザーに確認する

バージョン番号の遷移はあくまで参考程度の傾向であり、コミットの実態が優先される。 パッチリリースでも目玉があれば普通に強調していいし、マイナーリリースでも目玉がなければ目玉なし扱いで書く。

報告者への感謝表記 (全リリース共通)

KonomiTV では Issue / PR / フィードバックフォーム / Twitter DM など複数のチャネルからユーザー報告が寄せられる。 報告者由来の修正にはきちんと感謝の意を示し、報告チャネルを明示する ことで、ユーザーが報告しやすい雰囲気を維持する。 これはマイナー・パッチ問わず全リリース共通で適用する。

検出方法

各コミットの body (git log --format='%b' <hash> で取得) や PR 本文を確認し、以下のいずれかが当てはまる場合に「報告者由来の修正」として扱う。

• コミット body に感謝・受領系のキーワードがある: 「ご報告」「ご教示」「ご指摘」「フィードバック」「ありがとう」「教えていただいた」「報告いただいて」など
• コミットメッセージに (Close #XX) / (Fix #XX) / (Related: #XX) がある: 該当 Issue がユーザーから提出されたバグ報告/機能要望かを gh issue view #XX で確認する。ユーザー報告 Issue であれば対象
• PR が外部コントリビューターからのもの: 既にスキル本体の「箇条書きの書式ルール」で (thanks @author) 表記の対象としている。重複しないよう注意

表記の書き方

報告者由来の修正項目には、以下のいずれかの形で末尾に感謝表記を添える。

• Issue 報告由来: (Close [#XX](https://github.com/tsukumijima/KonomiTV/issues/XX) — ご報告ありがとうございました！)
• PR 由来 (外部): (PR [#XX](https://github.com/tsukumijima/KonomiTV/pull/XX), thanks @author)
• フィードバックフォーム/DM 由来 (Issue 化されていない): (フィードバックフォームからのご報告に対応 — ありがとうございました！)
• コミット body に明示的な感謝メッセージがあるが Issue が無い場合: (ご報告ありがとうございました！)

過去のリリースノートでも「フィードバックフォームからいただいたリクエストへの対応です」「ご報告ありがとうございました」「(thanks @author)」のような表記が散見される。下書き段階ではこれらを 必ず明示 すること (ユーザーが後で削るのは簡単だが、追加し忘れて公開してしまうと報告者に伝わらない)。

判定例

• コミットメッセージ: Fix: [Server] EpgTimerSrv.ini の同一セクションに重複するキーが存在する場合でもパースエラーが発生しないようにする、body: ご報告いただいて調べたらこれで横転 → 対象 (body に「ご報告」あり、フィードバックフォームか DM 由来と推定)
• コミットメッセージ: Fix: [Server][Streams/VideoEncodingTask] MP4 形式の録画再生時、〜 (Close #246) → 対象 (Issue #246 を gh issue view 246 で確認し、ユーザー報告であれば感謝表記を添える)
• コミットメッセージ: Refactor: [Server][Streams/LiveEncodingTask] 型ヒントを厳密化 → 対象外 (内部リファクタで報告由来ではない)

実行手順

Step 0: バージョン番号の確認

ユーザーに「今回リリースするバージョン番号は何ですか？」と確認する。 例: v0.14.0 / v0.14.1

ただし、バージョン番号は単なる開始トリガーであり、書き分けの判定材料ではない (詳細は上の「リリースの粒度判定と書き分け」セクションを参照)。 書き分け (目玉ありリリース / 目玉なしリリース) の判定はバージョン番号からは行えず、Step 1 でコミット一覧を取得して内容を読み込んで初めて確定する。 このため、Step 0 の段階では判定を保留し、Step 1 → Step 3 を経てコミットの実態を把握してから判別する。 判別結果は以降の全工程に影響する ため、Step 3 完了時点で曖昧なら、その場でユーザーに確認すること。

Step 1: 前回リリースタグの特定とコミット一覧の取得

# 前回リリースタグ (最新のリリースタグ) を取得
PREV_TAG=$(gh release list --limit 1 --json tagName -q '.[0].tagName')

# 前回リリースタグ以降のコミット一覧 (ハッシュ・サブジェクト) を取得
git log --format='%H %s' "$PREV_TAG"..HEAD

コミット読解の徹底ルール

リリースノートの品質は コミットをどれだけ丁寧に読み解いたか に直結する。以下のルールを厳守すること。

• 全コミットのコミットメッセージを必ず通読する。 grep やキーワードフィルタで拾うのではなく、コンテキストウィンドウに全コミットのメッセージを読み込んで判断する
• コミットメッセージのサブジェクトだけでは判断できない場合、git show --stat や git log --format='%b' でコミット body・変更ファイル一覧を確認する。 特に以下のケースでは必ず確認する:
  • 複数のコミットが同一機能に関連しているかの判断
  • バグ修正が新機能のマッチポンプか、既存機能のバグ修正かの判断
  • CI/ワークフロー系のコミットがユーザーに影響する重要な変更かどうかの判断
• CI/ワークフロー系のコミットも必ず目を通す。 [GitHub][workflows] スコープのコミットは大半がスキップ対象だが、中にはサードパーティーライブラリ自体のバグをパッチで修正するような、ユーザー影響が非常に大きい変更が含まれることがある (例: Arrow Lake 環境での Intel Media Driver のハードウェアデインタレース機能のバグを Intel Media Driver にパッチを当てることで修正する等)。これらを見落とさないこと
• 1つの問題に対して試行錯誤が繰り返されている場合 (「〜の改善を試みる①②③④」等)、最終的にどう解決されたかを把握した上で、1つの箇条書き項目にまとめる

Step 1.5: 前回リリースの付箋ブロック (NOTE/WARNING/TIP/IMPORTANT) を引き継ぐ

前回リリースのリリースノート本文を取得し、> [!NOTE] / > [!WARNING] / > [!TIP] / > [!IMPORTANT] で始まる GitHub Alerts ブロックをすべて抽出する。

gh release view "$PREV_TAG" --json body -q .body

これらの付箋ブロックは ダウンロード前にユーザーに読んでほしい注意書き として毎回のリリースに意図的に掲載されているもので、基本的にリリース間で内容を引き継いでいく。 具体的には以下のような定型的な内容が含まれる。

• アップデータの動作状況と再インストール推奨の案内 (WARNING)
• 録画を TS のまま保存しておくことの推奨 (IMPORTANT)
• tsreplace の紹介 (IMPORTANT)
• Twitter 連携に関する注意 (WARNING/IMPORTANT)
• EDCB バージョンに関する案内 (NOTE)
• その他、直近のリリースで新たに追加された注意事項

引き継ぎ時の判断基準:

• 前回リリースの付箋をそのまま出力に含める。ただし、今回のリリースで状況が変わった付箋は内容を更新する
  • 例: バージョン番号の参照 (0.12.0 → 0.13.0 など) は今回のバージョンに合わせて更新する
  • 例: アップデータの対応バージョン範囲が変わっていれば反映する
• 今回のリリースで明らかに不要になった付箋 (該当する問題が完全に解消された等) は削除候補として HTML コメントで <!-- この付箋は今回不要？ --> を付けておき、ユーザーの判断に委ねる
• 今回のリリースで新たに追加すべき注意事項があれば、付箋ブロックとして追加する

Step 2: マージ済み PR の取得 (外部コントリビューター分のみ)

Dependabot 以外の外部コントリビューターによる PR を取得する。 これは箇条書き本文に盛り込む際の参考情報として使う (PR 一覧自体は出力しない)。

PREV_DATE=$(gh release view "$PREV_TAG" --json publishedAt -q .publishedAt)
gh pr list --state merged --limit 200 --json number,title,author,mergedAt \
  --jq ".[] | select(.mergedAt > \"$PREV_DATE\") | select(.author.login != \"app/dependabot\") | \"\(.number) | \(.author.login) | \(.title)\""

Step 3: コミットの分類

全コミットをメッセージの prefix (Add:, Fix:, Update:, Refactor:, Remove:, Revert:, Build(deps) など) と内容を読み取り、以下のカテゴリに分類する。

機能追加の重要度順と配置ルール:

機能追加の箇条書きは 重要度の高いものを上 に配置する。重要度の判断基準はコミット数や差分の大きさではなく、プロジェクトにとっての意味合い で決める。

1. コア機能のミッシングピース — 長らく未実装だったがプロジェクトの本質に関わる機能がようやく実装された場合、最上位に置く
   • 例: 番組検索機能はテレビ視聴アプリのコア機能であり長年の懸案だった → Bluesky 連携 (補助的な SNS 連携) よりも上
2. 大型の新機能 — 新しいプラットフォーム対応、大規模な UI 追加など
3. 既存機能の拡張 — 新しいモード追加、新しい設定項目など
4. 小規模な機能追加 — UI の微調整、コンテキストメニュー追加など

さらに、機能的に近い項目は隣接して配置する。 重要度が離れていても、関連する機能同士はまとめて並べる方がユーザーにとって読みやすい。

• 例: Bluesky 連携とリプライツリー実況は SNS 連携カテゴリとして近いので、片方が重要度上位なら、もう片方もその直下に置く
• 例: 録画予約プリセット選択と即時録画ボタンは録画系機能として近いのでまとめて並べる

分類時の重要なポイント:

• コミットメッセージは Type: [Scope][Component] 説明 という形式で書かれている
  • [Client] はフロントエンド、[Server] はバックエンド
  • [Client][Panel/Twitter] のようにサブコンポーネントまで示されることもある
• 1つの機能に関連する複数のコミットは 1つの箇条書き項目にまとめる
  • 例: Bluesky 対応のコミットが20個あっても、リリースノートでは1-2項目にまとめる
• Revert と対応する元コミットは相殺して無視する
• Merge pull request #XXX のマージコミットは集計から除外し、PR の内容はコミットの方から読み取る
• Fix: [Server] 細かな修正 のような漠然としたコミットは基本的にスキップしてよい

バグ修正の掲載基準 (極めて重要):

リリースノートは 前回リリースとの差分のスナップショット である。リリースノートに載せるバグ修正は 前回リリース時点で既に存在していた機能やバグに対する修正のみ に限定する。

• 今回のリリースで新たに追加した機能の実装過程で発生・修正したバグは、リリースノートに記載してはならない
  • 例: HEVC 10bit 再生が今回のリリースで追加された新機能であるなら、「iOS Safari で HEVC 10bit 再生に対応しているのに HEVC 8bit で再生されてしまう問題を修正」は記載しない。これはその新機能の実装過程で潰されたバグであり、前リリースのユーザーには関係しない
  • 例: Bluesky 連携が今回の新機能であるなら、Bluesky のタイムラインのページング不具合修正は記載しない
  • 判断基準: そのバグが前回リリース (v0.X.0) のユーザーにも影響していたかどうか。前回リリースには存在しなかった機能に紐づくバグ修正はマッチポンプであり、ユーザーから見ると「最初から正しく動作している新機能」として見えるべき
• 前回リリースから存在していた機能に対するバグ修正 のみ記載する
  • 例: Twitter 連携は以前から存在する機能なので、Twitter の仕様変更による不具合修正は記載する
  • 例: ライブ視聴は以前から存在する機能なので、チャンネル切り替え時のプロセスリーク修正は記載する
• この判断を正しく行うには、各コミットが どの機能に紐づいているか を正確に理解する必要がある。コミットメッセージの prefix やスコープだけでなく、前後のコミットの文脈や変更内容を確認して判断すること

バグ修正の重要度順:

バグ修正の箇条書きは 重要度の高いものを上、低いものを下 に配置する。重要度の判断基準:

1. 致命的なバグ — リソースリーク、クラッシュ、データ消失、再生不能など
2. 影響範囲が広いバグ — 全ユーザーに影響する、特定の主要環境で再現するなど
3. 特定条件下のバグ — 特殊な環境・エッジケースでのみ発生するバグ
4. 軽微なバグ — UI の表示崩れなど

また、修正に大きな労力がかかったもの (例: サードパーティーライブラリ自体のバグを特定してパッチを当てて解決したケースなど) は、その苦労の経緯を含めて手厚く記述する。過去リリースでも「文句は〜サイドへどうぞ」「原因を特定するのに苦労した」のように経緯に言及する傾向がある

Step 4: 各コミット/コミット群の説明文を作成

分類されたコミットそれぞれについて、以下の情報を使って説明文を作成する。

• コミットメッセージのサブジェクト (日本語で書かれていることが多い)
• 必要に応じて git show --stat <hash> や git log --format='%b' <hash> でコミットの body や変更ファイルを確認する
• 外部 PR の場合は PR タイトル・作者名

説明文の文体ルール (過去のリリースノートから抽出):

• 日本語で記述する
• 文末は体言止め or 「〜に対応」「〜を修正」「〜を改善」「〜を追加」「〜を実装」のような動詞終わりが基本
• 句点（。）は使わない
• 「〜するようにした」「〜できるようにした」の表現もよく使われる
• 自然なカジュアルめの文体 (公式ドキュメントほど硬くない)
• 重要度が高い項目ほど説明が詳しい (サブリスト - で補足説明を追加)
• 個人的な所感を添えることもある（「地味に使いやすくなっていると思います」など）が、下書き段階では事実のみでよい

Step 5: リリースノートの組み立て

過去のリリースノートの構成に従い、以下の構造で Markdown ファイルを組み立てる。
箇条書き部分の実例は past-release-notes-examples.md を参照。

出力ファイルは上から順に以下の3パートで構成する。

パート A: 冒頭のリリース告知文

画像/動画の配置場所を示す TODO コメントの後に、今回のリリースの 概要紹介文 (1〜3段落) を生成する。

<!-- TODO: 冒頭にスクリーンショットや動画を貼る -->

(ここにリリース告知文を記述)

告知文の書き方 (過去リリースから抽出したパターン):

• 今回のリリースで一番大きな目玉機能を冒頭で強調する (太字・下線など)
• 前回リリースからの期間が長い場合は「お待たせしました」のような言及をする
• 目玉機能の後に、その他の注目点を1〜2文で簡潔に紹介する
• ベータ版である旨の定型文 (正式版が公開されるまでのリリースはあくまで〜) を含める
• カジュアルで親しみやすいトーン。過去リリースの文体を踏襲する
• 下書きなので、ユーザーの個人的な所感やエモい表現 (「…！！」「🎉🎊」など) は含めず、事実ベースで書く。 ユーザーが後から味付けする
• 能動態で書く。 「〜を実装しました」「〜を追加しました」「〜に対応しました」のように、開発者自身が主体であるかのような能動態を使う。「〜が追加されました」「〜が実装されました」のような受動態は、他人事のような印象を与えるので避ける。過去リリースの告知文も一貫して能動態で書かれている
• ユーザーに不要なメタ情報を含めない。 「前回はリリースノートを省略していたが今回は整理した」「コミット数が X だった」などのリリースノート作成プロセスに関する情報はユーザーにとってノイズでしかないので、一切含めない。告知文はあくまでリリース内容の紹介に徹する
• 改行と空行で視覚的なリズムを作る。 GitHub Releases では単一の改行が <br> として表示される。これを活用して、文の途中で折り返されて読みにくくなる前に、意味のまとまりで意図的に改行を入れる。具体的には:
  • 太字の見出し文は単独の行にする (「〜を実装しました！」の後に同じ行で説明を続けない)
  • 1文ごとに改行する のが基本。ただし短い2文が意味的に密接なら同一行でよい
  • 話題が変わるところでは空行を入れる (番組検索の話 → Bluesky の話 → その他の話、のように)
  • GitHub Releases のコンテンツ幅 (PC で約 900px) を想定し、全角で約45〜55文字程度を超えそうな行は適切な位置で改行する
  • 過去リリースの実例を見ると、詰め詰めに文字を並べるのではなく、適度に空白を設けて読みやすさを確保している

過去の告知文の実例は past-intro-examples.md を参照。

パート B: 付箋ブロック

Step 1.5 で引き継いだ NOTE/WARNING/TIP/IMPORTANT ブロックをここに配置する。 バージョン番号の参照は今回のリリースに合わせて更新済みの状態で出力する。

パート C: What's Changed セクション

## What's Changed

<!-- === 機能追加 (重要度順) === -->
* **項目タイトル**
  - 補足説明1
  - 補足説明2
* **項目タイトル**

<!-- === 重要な改善 === -->
* **項目タイトル**

<!-- === バグ修正 === -->
* **項目タイトル (Close #XX)**
* **項目タイトル**

<!-- === その他 === -->
* その他大量のバグ修正、依存ライブラリの更新など

<!-- ここから下は GitHub の「Generate release notes」ボタンで自動生成される部分。
     ユーザーが手動でマージするため、このスキルでは出力不要 -->

箇条書きの書式ルール:

• 機能追加/改善/バグ修正項目は * **タイトル** の太字形式
• コミット URL やツイート URL へのリンクは、意味のある場合のみ [テキスト](URL) で含める
  • コミット1つだけに対応する項目: コミット URL をリンクとして貼る場合がある
  • PR に対応する項目: PR URL をリンクとして貼る
• Issue を Close する修正は (Close #XX) を末尾に付ける
• 重要な機能追加には先頭に 🎉 絵文字を付けることがある (過去リリースに倣う)
• サブリスト (- ) は2スペースインデントで記述
• 外部コントリビューターの PR で特筆すべきものがあれば、箇条書き本文内に (thanks @author) の形で言及する

Step 6: ファイル出力

完成した下書きを /tmp/konomi-tv-release-notes-draft.md に出力する。 出力後、ユーザーにファイルパスを伝え、中身の要約も併せて報告する。

分類の判断が難しい場合

コミットの影響範囲が不明確な場合は、変更されたファイルとコミット本文を確認した上で判断する。
それでも迷う場合は 含める側 に倒す（ユーザーが後から削除する方が、書き漏らしを後から追加するより楽なため）。

量が多い場合の方針

前回リリースからのコミット数が 200 を超える場合:

• 全コミットをカテゴリ分類はするが、リリースノートに載せるのは ユーザー影響のある変更のみ
• 内部リファクタ、CI 修正、コメント修正、定型的なビルド更新は積極的に省略する
• 末尾に「その他大量のバグ修正、依存ライブラリの更新など」を含めて網羅性を示す