massgen-release-documenter

リリースドキュメント作成

このスキルでは、確立されたワークフローと規約に従って MassGen のリリースをドキュメント化するためのガイダンスを提供します。

目的

release-documenter スキルは、CHANGELOG → Sphinx ドキュメント → README → ロードマップの更新という一連のリリースドキュメント作成ワークフローを案内し、一貫性のある完全なリリースドキュメントの作成を支援します。

このスキルを使用するタイミング

次の作業が必要な場合は、release-documenter スキルを使用してください。

• 新しいリリースのドキュメントを準備する
• 新機能や修正を CHANGELOG.md に反映する
• Sphinx ドキュメントを作成または更新する
• 主要機能のケーススタディを作成する
• README.md とロードマップドキュメントを更新する
• リリースチェックリストの手順に従う

正式なドキュメント

重要： リリースドキュメントの主要な信頼できる情報源は次のとおりです。

📋 docs/dev_notes/release_checklist.md

このファイルには、次の内容が含まれています。

• フェーズごとの完全なリリースワークフロー
• 詳細なドキュメント更新要件
• 検証用チェックリスト
• コミットとタグのワークフロー
• 自動化ツールに関する情報
• 現行のすべての規約とルール

完全なリリース手順については、必ずこのドキュメントを参照してください。

重要なドキュメント作成順序

必ず次の順序に従ってください。

0. 新規ブランチの初期設定（ブランチ作成時に一度だけ）— バージョンの更新と ROADMAP_v0.1.X.md → ROADMAP_v0.1.X+1.md の名前変更（Phase 0 を参照）
1. CHANGELOG.md ⭐ ここから開始
2. バージョンの更新（massgen/__init__.py の __version__）
3. Sphinx ドキュメント（docs/source/）
4. 設定ドキュメント（massgen/configs/README.md）
5. ケーススタディ（docs/source/examples/case_studies/）
6. README.md
7. README_PYPI.md（pre-commit によって自動同期）
8. ロードマップ（ROADMAP.md）
9. お知らせ（docs/announcements/）— current-release.md、github-release-vX.md、アーカイブ

この順序は重要です。先の項目に飛ばないでください。

クイックリファレンス：ワークフロー

Phase 0：新規リリースブランチの初期設定（ブランチ作成時に実施）

⚠️ 見落としやすい点です。ドキュメント作成時ではなく、新しい dev/v0.1.X ブランチの開始時に一度だけ実施します。 dev/v0.1.X を分岐したとき（直前のリリースをマージした直後）、ブランチを設定するための小さな初期設定コミット（feat: v0.1.X）を作成します。

1. バージョンを更新する：massgen/__init__.py の __version__ = "0.1.X"（pyproject.toml はこの値を動的に読み込みます）。
2. 次のリリース用ロードマップファイルを更新する：ROADMAP_v0.1.X.md → ROADMAP_v0.1.X+1.md に名前を変更し、次のリリースを計画する内容に書き換えます。このファイルには、現在開発中のバージョンの次のバージョンを常に記載します（開発中のバージョンはメインの ROADMAP.md の各セクションで管理します）。タイトル、「Overview」、延期された機能の「Deferred from …」の範囲を更新し、リリース済みのバージョンを「Related Tracks」リストに追加します。

git mv ROADMAP_v0.1.X.md ROADMAP_v0.1.X+1.md
# then edit __version__ and the renamed roadmap file

ブランチの途中から作業に参加し、開発中のバージョンと一致する ROADMAP_v0.1.X.md がまだ残っている場合や、__version__ が前回のリリースのままの場合は、初期設定がスキップされています。リリースドキュメントの作成前に、今すぐ実施してください。

Phase 1：CHANGELOG.md（最初に必ず実施）

次のカテゴリに分けて、すべての変更を記録します。

• 追加 - 新機能
• 変更 - 動作の変更
• 修正 - バグ修正
• ドキュメント、設定、リソース - 新しいドキュメントや設定
• 技術的な詳細 - 貢献者、重点分野

# Get changes since last release
git log v0.1.X-1..HEAD --oneline
gh pr list --base dev/v0.1.X --state merged

形式の詳細については、docs/dev_notes/release_checklist.md のセクション 3.1 を参照してください。

Phase 2：Sphinx ドキュメント

必要に応じて、次の項目を更新します。

• docs/source/index.rst - 最近のリリースのセクション（最新の 3 件を保持）
• docs/source/user_guide/ - 新機能のガイド
• docs/source/reference/yaml_schema.rst - 新しい YAML パラメーター
• docs/source/reference/supported_models.rst - 新しいモデル

ビルドして確認する：

cd docs && make html
make linkcheck  # Verify no broken links

要件の全容については、docs/dev_notes/release_checklist.md のセクション 3.2 を参照してください。

Phase 3：設定ドキュメント

• massgen/configs/README.md を更新する
• 適切なカテゴリにサンプル設定を作成する
• 追加した設定をすべてテストする

Phase 4：ケーススタディ

# Use template
cp docs/source/examples/case_studies/case-study-template.md \
   docs/source/examples/case_studies/v0.1.X-feature-name.md

# Update index
vim docs/source/examples/case_studies.rst

docs/dev_notes/release_checklist.md のセクション 3.4 を参照してください。

フェーズ 5：README.md

次のセクションを更新します：

1. 最近の成果（古いものは「以前の成果」に移動）
2. 事例紹介セクション
3. 設定ファイル（構成に変更があった場合）

CHANGELOG.md の形式をコピーし、内容を拡充します。

フェーズ 6：README_PYPI.md（自動）

✅ pre-commit フックによって自動同期されます！

README.md を変更してコミットすると：

1. pre-commit フックが自動実行されます
2. README_PYPI.md が同期されます
3. フックに「Failed - files were modified」と表示された場合は、再度 git commit を実行します

必要に応じて手動で同期します：

uv run python scripts/sync_readme_pypi.py

フェーズ 7：ロードマップ

• 完了した機能に ROADMAP.md で ✅ を付けます
• 次のリリース用に ROADMAP_v0.1.X+1.md を更新します
• docs/source/development/roadmap.rst は編集しないでください（自動生成されます）

フェーズ 8：お知らせ（docs/announcements/）

⚠️ 見落としやすい項目です。自動生成されません。 リリースごとに、docs/announcements/ 内の次の 3 つを更新します：

1. 旧お知らせをアーカイブする：現在の current-release.md を archive/v0.1.X-1.md にコピーします（現在説明されているバージョンです）。

   cp docs/announcements/current-release.md docs/announcements/archive/v0.1.X-1.md
   

2. 新バージョン用に current-release.md を書き換える：タイトル、リリース概要、インストールバージョン、リリースノートへのリンク、「推奨画像」のバージョン、LinkedIn のお知らせ本文全体（主な改善点の箇条書き）を更新します。これは、長文のソーシャルメディア／LinkedIn 用コピーです。
3. GitHub リリースのハイライトファイルを置き換える：github-release-v0.1.X-1.md を削除し、github-release-v0.1.X.md を作成します（日付が (YYYY-MM-DD) 形式の、短く絵文字でセクション分けされた GitHub Releases 用の本文です）。

   git rm docs/announcements/github-release-v0.1.X-1.md
   # then write docs/announcements/github-release-v0.1.X.md
   

feature-highlights.md とそのディレクトリ内の README.md は全バージョン共通です（バージョンごとではありません）。ハイライトに変更がない限り、そのままにしてください。

直前のバージョンをアーカイブしたファイルをテンプレートとして使用し、構成やセクションの一貫性を保ちます。X／LinkedIn のリンク用の [TO BE ADDED AFTER POSTING] プレースホルダーは残してください。

バージョンの更新（massgen/__init__.py の __version__ = "0.1.X"）を忘れないでください。pyproject.toml はここからバージョンを動的に読み込みます。

簡易検証チェックリスト

必ず更新する項目（リリースごと）： 0. ✅ 新規ブランチの準備は完了していますか？（__version__ の更新と ROADMAP_v0.1.X.md から ROADMAP_v0.1.X+1.md への名前変更。フェーズ 0 を参照）

1. ✅ CHANGELOG.md
2. ✅ massgen/__init__.py（__version__ の更新）
3. ✅ docs/source/index.rst（最近のリリース）
4. ✅ README.md（最近の成果＋最新機能＋目次アンカー）
5. ✅ ROADMAP.md（現在のバージョン、完了セクション、表）
6. ✅ docs/announcements/（旧版のアーカイブ、current-release.md の書き換え、github-release-vX.md の入れ替え）
7. ⚠️ docs/source/user_guide/（ユーザー向け機能の場合）
8. ⚠️ massgen/configs/（設定例がある場合）
9. ⚠️ 事例紹介（内部品質のみ／ユーザー向け機能なしのリリースでは省略）

該当する場合に更新する項目： 10. ⚠️ massgen/config_builder.py（設定パラメーターを追加した場合） 11. ⚠️ massgen/backend/capabilities.py（バックエンドに変更がある場合） 12. ✅ README_PYPI.md（pre-commit により README.md から自動同期）

ビルドと検証： 13. 🔨 cd docs && make html && make linkcheck 14. 🔨 新しい設定ファイルをテストします 15. 🔨 すべてのリンクが機能することを確認します

全項目については、docs/dev_notes/release_checklist.md の「簡易リファレンスチェックリスト」セクションを参照してください。

バックエンドの更新（必要な場合）

設定ビルダー

新しい YAML パラメーターを追加した場合は、massgen/config_builder.py を更新します：

• 対話型ウィザードにパラメーターを追加します
• 検証を更新します
• ヘルプテキストを追加します
• massgen --config-builder でテストします

バックエンドの機能

バックエンドの機能に変更があった場合は、massgen/backend/capabilities.py を更新します：

• 新機能をサポートするバックエンドを記載します
• 機能マトリックスを更新します
• 新しい機能フラグを追加します

docs/dev_notes/release_checklist.md のセクション 2.1～2.2 を参照してください。

コミットとリリースのワークフロー

コミットメッセージのテンプレート

git commit -m "docs: Release v0.1.X documentation

- Updated CHANGELOG.md with full release notes
- Added case study: [Feature Name]
- Updated README.md Recent Achievements
- Enhanced Sphinx documentation
- Added example configurations

Major features:
- Feature 1: Description
- Feature 2: Description
"

PR の作成

git push origin dev/v0.1.X

gh pr create --base main --head dev/v0.1.X \
  --title "Release v0.1.X: [Feature Name]" \
  --body "See CHANGELOG.md for full release notes"

リリースにタグを付ける（マージ後）

git checkout main && git pull

git tag -a v0.1.X -m "Release v0.1.X: [Feature Name]

Major features:
- Feature 1
- Feature 2

See CHANGELOG.md for details."

git push origin v0.1.X

ワークフロー全体については、docs/dev_notes/release_checklist.md のセクション 7 を参照してください。

参考ファイル

主なドキュメント：

• リリースチェックリスト：docs/dev_notes/release_checklist.md ⭐ まずはこちらをご確認ください
• 設定ファイルの作成：docs/source/development/writing_configs.rst

スクリプト：

• README の同期：scripts/sync_readme_pypi.py
• 設定の検証：scripts/precommit_validate_configs.py
• バックエンドの表：docs/scripts/generate_backend_tables.py

テンプレート：

• 事例紹介テンプレート：docs/source/examples/case_studies/case-study-template.md

エージェント向けのヒント

リリースドキュメントを準備する際は、以下に従ってください。

1. 必ず最初にリリースチェックリストを読む：docs/dev_notes/release_checklist.md
2. 順序を厳守する：CHANGELOG → Sphinx → README → Roadmap
3. 変更後にドキュメントをビルドする：cd docs && make html && make linkcheck
4. コミット前に新しい設定をすべてテストする
5. 迷った場合は、docs/dev_notes/release_checklist.md で詳しいガイダンスを確認する

このスキルはクイックリファレンスです。詳しい手順については、必ず公式のリリースチェックリストドキュメントを参照してください。