massgen-release-documenter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release Documenter

发布文档处理技能

This skill provides guidance for documenting MassGen releases following the established workflow and conventions.

该技能可指导你遵循既定工作流和规范完成MassGen版本的文档记录工作。

Purpose

用途

The release-documenter skill ensures consistent, complete release documentation by guiding you through the full release documentation workflow: CHANGELOG → Sphinx Documentation → README → Roadmap updates.

release-documenter 技能可引导你完成完整的发布文档工作流：CHANGELOG → Sphinx 文档 → README → 路线图更新，从而确保发布文档的一致性和完整性。

When to Use This Skill

何时使用该技能

Use the release-documenter skill when you need to:

Prepare documentation for a new release
Update CHANGELOG.md with new features and fixes
Write or update Sphinx documentation
Create case studies for major features
Update README.md and roadmap documents
Follow the release checklist process

当你需要完成以下操作时可使用release-documenter技能：

为新版本准备发布文档
用新功能和修复内容更新CHANGELOG.md
编写或更新Sphinx文档
为核心功能编写案例研究
更新README.md和路线图文档
遵循发布检查清单流程

Authoritative Documentation

权威文档

IMPORTANT: The primary source of truth for release documentation is:

📋
docs/dev_notes/release_checklist.md

This file contains:

Complete phase-by-phase release workflow
Detailed documentation update requirements
Validation checklists
Commit and tag workflow
Automation tool information
All current conventions and rules

Always consult this document for the complete release process.

重要提示： 发布文档的首要权威来源是：

📋
docs/dev_notes/release_checklist.md

该文件包含：

分阶段的完整发布工作流
详细的文档更新要求
校验检查清单
提交和标签工作流
自动化工具信息
所有现行规范和规则

请始终参考该文档获取完整的发布流程说明。

Critical Documentation Order

文档更新优先级顺序

Always follow this order:

CHANGELOG.md ⭐ START HERE
Sphinx Documentation (docs/source/)
Config Documentation (massgen/configs/README.md)
Case Studies (docs/source/examples/case_studies/)
README.md
README_PYPI.md (auto-synced via pre-commit)
Roadmap (ROADMAP.md)

This order is critical - never skip ahead!

必须严格遵循以下顺序，切勿跳步：

CHANGELOG.md ⭐ 从这里开始
Sphinx 文档 (docs/source/)
配置文档 (massgen/configs/README.md)
案例研究 (docs/source/examples/case_studies/)
README.md
README_PYPI.md (通过pre-commit自动同步)
路线图 (ROADMAP.md)

该顺序非常重要，绝对不能提前跳过前面的步骤！

Quick Reference Workflow

快速参考工作流

Phase 1: CHANGELOG.md (Required First Step)

阶段1：CHANGELOG.md（必填首步）

Document all changes under these categories:

Added - New features
Changed - Modified behavior
Fixed - Bug fixes
Documentations, Configurations and Resources - New docs/configs
Technical Details - Contributors, focus areas

bash

undefined

将所有变更归入以下类别：

新增 - 新功能
变更 - 修改的功能行为
修复 - Bug修复
文档、配置与资源 - 新增文档/配置
技术细节 - 贡献者、重点优化方向

bash

undefined

Get changes since last release

获取上一个版本以来的变更

git log v0.1.X-1..HEAD --oneline gh pr list --base dev/v0.1.X --state merged


See `docs/dev_notes/release_checklist.md` sections 3.1 for detailed format.

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 Documentation

阶段2：Sphinx 文档

Update as needed:

```
docs/source/index.rst
```
- Recent Releases section (keep latest 3)
```
docs/source/user_guide/
```
- New feature guides
```
docs/source/reference/yaml_schema.rst
```
- New YAML parameters

docs/source/reference/supported_models.rst

- New models

Build and verify:

bash

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

See

docs/dev_notes/release_checklist.md

section 3.2 for complete requirements.

根据需要更新以下内容：

```
docs/source/index.rst
```
- 最新版本板块（保留最近3个版本）
```
docs/source/user_guide/
```
- 新功能使用指南
```
docs/source/reference/yaml_schema.rst
```
- 新增YAML参数

docs/source/reference/supported_models.rst

- 新增支持的模型

构建并校验：

bash

cd docs && make html
make linkcheck  # 校验无无效链接

完整要求请参考

docs/dev_notes/release_checklist.md

的3.2章节。

Phase 3: Config Documentation

阶段3：配置文档

Update
```
massgen/configs/README.md
```
Create example configs in appropriate category
Test all new configs

更新
```
massgen/configs/README.md
```
在对应分类下创建示例配置
测试所有新增配置

Phase 4: Case Studies

阶段4：案例研究

bash

undefined

bash

undefined

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


See `docs/dev_notes/release_checklist.md` section 3.4.

vim docs/source/examples/case_studies.rst


参考`docs/dev_notes/release_checklist.md`的3.4章节。

Phase 5: README.md

阶段5：README.md

Update these sections:

Recent Achievements (move old to Previous Achievements)
Case Studies section
Configuration Files (if structure changed)

Copy format from CHANGELOG.md and expand.

更新以下板块：

近期进展（旧内容移至往期进展）
案例研究板块
配置文件板块（如果结构发生变更）

沿用CHANGELOG.md的格式并补充内容。

Phase 6: README_PYPI.md (Automated)

阶段6：README_PYPI.md（自动化）

✅ Auto-synced via pre-commit hook!

When you commit README.md changes:

Pre-commit hook runs automatically
README_PYPI.md gets synced
If hook shows "Failed - files were modified", run
```
git commit
```
again

Manual sync if needed:

bash

uv run python scripts/sync_readme_pypi.py

✅ 通过pre-commit钩子自动同步！

当你提交README.md的变更时：

Pre-commit钩子会自动运行
README_PYPI.md会自动同步
如果钩子提示「Failed - files were modified」，重新运行
```
git commit
```
即可

如需手动同步：

bash

uv run python scripts/sync_readme_pypi.py

Phase 7: Roadmap

阶段7：路线图

Mark completed features as ✅ in
```
ROADMAP.md
```
Update
```
ROADMAP_v0.1.X+1.md
```
for next release
Do NOT edit
```
docs/source/development/roadmap.rst
```
(auto-generated)

在
```
ROADMAP.md
```
中将已完成功能标记为✅
更新
```
ROADMAP_v0.1.X+1.md
```
为下个版本的路线图
不要编辑
```
docs/source/development/roadmap.rst
```
（该文件为自动生成）

Quick Validation Checklist

快速校验清单

Must Update (every release):

✅ CHANGELOG.md
✅ docs/source/index.rst (Recent Releases)
✅ docs/source/user_guide/ (if user-facing feature)
✅ README.md (Recent Achievements)
✅ massgen/configs/ (example configs)
✅ Case study

Should Update (if applicable): 7. ⚠️ massgen/config_builder.py (if config params added) 8. ⚠️ massgen/backend/capabilities.py (if backend changes) 9. ✅ README_PYPI.md (auto-synced) 10. ⚠️ ROADMAP.md

Build & Verify: 11. 🔨

cd docs && make html && make linkcheck

12. 🔨 Test new config files 13. 🔨 Verify all links work

See

docs/dev_notes/release_checklist.md

section "Quick Reference Checklist" for complete list.

每次版本发布必须更新：

✅ CHANGELOG.md
✅ docs/source/index.rst（最新版本板块）
✅ docs/source/user_guide/（如果有面向用户的功能）
✅ README.md（近期进展板块）
✅ massgen/configs/（示例配置）
✅ 案例研究

按需更新（如适用）： 7. ⚠️ massgen/config_builder.py（如果新增了配置参数） 8. ⚠️ massgen/backend/capabilities.py（如果后端发生变更） 9. ✅ README_PYPI.md（自动同步） 10. ⚠️ ROADMAP.md

构建与校验： 11. 🔨

cd docs && make html && make linkcheck

12. 🔨 测试新配置文件 13. 🔨 校验所有链接可正常访问

完整清单请参考

docs/dev_notes/release_checklist.md

的「快速参考清单」章节。

Backend Updates (When Needed)

后端更新（按需执行）

Config Builder

配置构建器

If new YAML parameters were added, update

massgen/config_builder.py

Add parameters to interactive wizard
Update validation
Add help text
Test with
```
massgen --config-builder
```

如果新增了YAML参数，更新

massgen/config_builder.py

：

在交互式向导中添加对应参数
更新校验逻辑
添加帮助文本
用
```
massgen --config-builder
```
测试

Backend Capabilities

后端能力

If backend capabilities changed, update

massgen/backend/capabilities.py

Document which backends support new features
Update capability matrix
Add new capability flags

See

docs/dev_notes/release_checklist.md

section 2.1-2.2.

如果后端能力发生变更，更新

massgen/backend/capabilities.py

：

记录哪些后端支持新功能
更新能力矩阵
添加新的能力标识

参考

docs/dev_notes/release_checklist.md

的2.1-2.2章节。

Commit and Release Workflow

提交与发布工作流

Commit Message Template

提交信息模板

bash

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
"

bash

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
"

Create PR

创建PR

bash

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"

bash

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"

Tag Release (After Merge)

打版本标签（合并后）

bash

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

See

docs/dev_notes/release_checklist.md

section 7 for complete workflow.

bash

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章节。

Reference Files

参考文件

Primary Documentation:

Release checklist:
```
docs/dev_notes/release_checklist.md
```
⭐ START HERE

Writing configs:

docs/source/development/writing_configs.rst

Scripts:

README sync:
```
scripts/sync_readme_pypi.py
```
Config validation:
```
scripts/precommit_validate_configs.py
```
Backend tables:
```
docs/scripts/generate_backend_tables.py
```

Templates:

Case study template:

docs/source/examples/case_studies/case-study-template.md

核心文档：

发布检查清单:
```
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

Tips for Agents

给Agent的使用提示

When preparing release documentation:

Always read the release checklist first:
```
docs/dev_notes/release_checklist.md
```
Follow the order strictly: CHANGELOG → Sphinx → README → Roadmap
Build docs after changes:
```
cd docs && make html && make linkcheck
```
Test all new configs before committing
When in doubt, consult
```
docs/dev_notes/release_checklist.md
```
for complete guidance

This skill is a quick reference guide. For comprehensive, step-by-step instructions, always refer to the official release checklist document.

准备发布文档时：

始终先阅读发布检查清单:
```
docs/dev_notes/release_checklist.md
```
严格遵循更新顺序: CHANGELOG → Sphinx → README → 路线图
变更后构建文档校验:
```
cd docs && make html && make linkcheck
```
提交前测试所有新增配置
有疑问时，参考
```
docs/dev_notes/release_checklist.md
```
获取完整指引

该技能为快速参考指南。如需全面的分步说明，请始终参考官方发布检查清单文档。