write-release-note

# リリースノート作成ガイド このドキュメントは、直近のタグ以降のコンテンツ更新をまとめたリリースノートを作成するAIエージェント向けの指示書です。 ## 1. 目的 読者に向けて、前回のリリース以降にどんなコンテンツの追加・更新があったかを分かりやすく伝えるリリースノートを作成します。技術書の更新情報として、読者が「今回はこんな内容が充実した」「このトピックを読んでみよう」と思えるような記事を目指します。 ## 2. 情報収集プロセス ### 2.1. 対象期間の特定 直近の `YYYY-MM-DD` 形式のタグを基準として、それ以降のコミットを対象とします。 ```bash # 直近のYYYY-MM-DD形式のタグを取得 git tag --list --sort=-creatordate | grep -E '^[0-9]{4}-[0-9]{2}-[0-9]{2}$' | head -1 # 今日の日付を確認 date "+%Y-%m-%d" ``` リリースノートのファイル名は `docs/releasenotes/YYYY-MM-DD.md` の形式です（例: `2026-01-10.md`）。 今日の日付をファイル名として使用してください。 ### 2.2. コミットログの取得 直近のタグ以降のコミットを確認します： ```bash # 直近のYYYY-MM-DD形式タグを変数に格納 LAST_TAG=$(git tag --list --sort=-creatordate | grep -E '^[0-9]{4}-[0-9]{2}-[0-9]{2}$' | head -1) echo "対象期間: $LAST_TAG 以降" # タグ以降のコミットログを取得（詳細版） git log ${LAST_TAG}..HEAD --no-merges --pretty=format:"%h %s" # PRマージのみを確認したい場合 git log ${LAST_TAG}..HEAD --merges --pretty=format:"%h %s" ``` ### 2.3. 各コミットの差分確認 重要なコミットについては、具体的な変更内容を確認します： ```bash # 特定のコミットの差分を確認 git show <commit-hash> --stat git diff <commit-hash>^..<commit-hash> -- docs/ ``` 特に `docs/` フォルダ配下の変更に注目してください。 ### 2.4. GitHub Issue/PRの確認 コミットメッセージに `(#数字)` がある場合、関連するIssue/PRを確認します： ```bash # GitHub CLIでIssue/PRの詳細を確認 gh issue view <issue-number> gh pr view <pr-number> ``` ### 2.5. コントリビューターの確認 PRの作者情報を確認して、コントリビューター一覧を作成します： ```bash # PRの作者を確認 gh pr view <pr-number> --json author --jq '.author.login' ``` ## 3. リリースノートの作成 ### 3.1. 出力先 ``` docs/releasenotes/YYYY-MM-DD.md ``` 例: `docs/releasenotes/2026-01-10.md` ### 3.2. タイトルの付け方 タイトルは以下の形式で、読者の興味を引く主要トピックを含めてください： - **主要な更新が1つの場合**: `YYYY-MM-DD [主要トピック]` - **主要な更新が複数ある場合**: `YYYY-MM-DD [主要トピック]など` 例： - `2026-01-10 Prettierチュートリアルを改善` - `2026-01-10 プロジェクト参照チュートリアルをnpmに移行など` ### 3.3. フォーマット ```markdown --- date: YYYY-MM-DD --- # YYYY-MM-DD [主要トピック] YYYY年M月D日の更新内容をお届けします。 ## ✨ ハイライト <!-- 新規ページの追加、既存ページの大幅な加筆など、大きな更新を紹介 --> ### [更新タイトル] [読者目線で、この更新がなぜ嬉しいか、何が学べるかを300字程度で説明]（[#PR番号] by [@username]） [ページタイトル](リンク) ### 修正・改善 <!-- 誤字脱字、コードの修正、説明の明確化など --> - [ページタイトル](リンク) - 修正内容（[#PR番号] by [@username]） ## 👥 コントリビューター 今回のアップデートに貢献してくださった方々です。ありがとうございます！ - [@username1] - [@username2] --- いつもサバイバルTypeScriptをご利用いただきありがとうございます。 ご意見・ご要望は [GitHub Issues](https://github.com/yytypescript/book/issues) までお寄せください。 <!-- PR参照リンク --> [#1234]: https://github.com/yytypescript/book/pull/1234 [#1235]: https://github.com/yytypescript/book/pull/1235 <!-- コントリビューター参照リンク --> [@username1]: https://github.com/username1 [@username2]: https://github.com/username2 ``` ### 3.4. PRリンクの記載方法 PRはMarkdownの参照リンク形式で管理します： 1. **本文中での表記**: `[#PR番号]` の形式で記載（例: `[#1234]`） 2. **ファイル末尾に参照定義**: `[#PR番号]: https://github.com/yytypescript/book/pull/PR番号` を追加 例： ```markdown - [Prettierチュートリアル](/tutorials/prettier) - EditorConfigの説明を追加（[#1063]） <!-- PR参照リンク --> [#1063]: https://github.com/yytypescript/book/pull/1063 ``` ### 3.5. コントリビューターの記載方法 コントリビューターはMarkdownの参照リンク形式で管理します： 1. **本文中での表記**: `[@username]` の形式で記載 2. **ファイル末尾に参照定義**: `[@username]: https://github.com/username` を追加 例： ```markdown ## 👥 コントリビューター - [@suin] - [@example-user] <!-- コントリビューター参照リンク --> [@suin]: https://github.com/suin [@example-user]: https://github.com/example-user ``` ## 4. 執筆のポイント ### 4.1. 読者目線を意識する - ❌ 「XxxPageを更新しました」（開発者視点） - ✅ 「型エイリアスとインターフェースの違いがより分かりやすくなりました」（読者視点） ### 4.2. 変更の価値を伝える 単なる変更リストではなく、その変更が読者にとってどんなメリットがあるかを説明してください： - 「初心者がつまずきやすいポイントに補足説明を追加」 - 「最新のTypeScript 5.x に対応したコード例に更新」 - 「実務でよく使うパターンの解説を追加」 ### 4.3. カテゴリ分けのガイドライン | 変更の種類 | カテゴリ | | ------------------------ | -------------- | | 新しいページの追加 | 新規コンテンツ | | 既存ページへの大幅な加筆 | 内容の充実 | | 説明の明確化、例の追加 | 内容の充実 | | 誤字脱字、コードの修正 | 修正・改善 | ### 4.4. リリースノートに含めない項目 以下の読者に直接関係ない変更は、リリースノートに含めないでください： - 依存パッケージの更新 - CI/CD、ビルド設定の変更 - 開発環境の改善 - 内部的なリファクタリング - フォーマットのみの変更 - 単純な誤字修正（まとめて「細かな誤字を修正しました」程度でOK） ## 5. 作業フロー 1. **情報収集**: 直近タグの特定、コミットログ、diff、Issue/PRを確認 2. **コントリビューター確認**: PRの作者を確認してリストアップ 3. **分類**: 変更内容をカテゴリごとに整理 4. **ハイライト選定**: 読者にとって価値の高い更新をピックアップ 5. **タイトル決定**: 主要トピックを含む魅力的なタイトルを作成 6. **執筆**: 読者目線で分かりやすい文章を作成 7. **確認**: リンク（ページ、PR、コントリビューター）が正しいか確認 8. **保存**: `docs/releasenotes/YYYY-MM-DD.md` に保存 ## 6. 補足 ### releasenotes フォルダが存在しない場合 初回実行時は `docs/releasenotes/` ディレクトリを作成してください。 ### タグが存在しない場合 `YYYY-MM-DD` 形式のタグが見つからない場合は、過去1週間のコミットを対象としてください： ```bash git log --since="1 week ago" --no-merges --pretty=format:"%h %s" ``` ### 更新が少ない場合 更新が少ない場合は無理にリリースノートを作成する必要はありません。「大きな更新はありませんでした」と記載するか、次回にまとめても構いません。