massgen-release-documenter

Release 文档编写指南

此技能为编写 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（见阶段 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、归档

此顺序至关重要——切勿跳步！

工作流速查

阶段 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 的各个章节中）。更新其标题、“概述”、延期功能的“从……延期”范围，并将刚发布的版本添加到“相关开发路线”列表中。

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__ 仍是上一个版本号，说明初始化步骤被跳过了——请在编写版本发布文档前完成此操作。

阶段 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 节。

阶段 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 节。

阶段 3：配置文档

• 更新 massgen/configs/README.md
• 在合适的类别中创建示例配置
• 测试所有新配置

阶段 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 hook 自动同步！

提交 README.md 更改时：

1. Pre-commit hook 会自动运行
2. README_PYPI.md 会同步更新
3. 如果 hook 显示“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/ 中的三项内容：

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（简短、按表情符号分节的 GitHub Releases 正文，日期格式为 (YYYY-MM-DD)）。

   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（近期成就 + 最新功能 + TOC 锚点）
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

给 Agent 的提示

准备发布文档时：

1. 务必先阅读发布清单：docs/dev_notes/release_checklist.md
2. 严格遵循顺序：CHANGELOG → Sphinx → README → 路线图
3. 修改后构建文档：cd docs && make html && make linkcheck
4. 提交前测试所有新配置
5. 如有疑问，请查阅 docs/dev_notes/release_checklist.md 获取完整指导

本技能是一份快速参考指南。如需全面的分步说明，请务必参阅官方发布清单文档。