Release Documenter

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

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.

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

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.

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!

Quick Reference Workflow

Phase 1: CHANGELOG.md (Required First Step)

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

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.

Phase 2: Sphinx Documentation

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:

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

See docs/dev_notes/release_checklist.md section 3.2 for complete requirements.

Phase 3: Config Documentation

• Update massgen/configs/README.md

• Create example configs in appropriate category

• Test all new configs

Phase 4: Case Studies

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.

Phase 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.

Phase 6: README_PYPI.md (Automated)

✅ 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:

uv run python scripts/sync_readme_pypi.py

Phase 7: Roadmap

• 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)

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.

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

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.

Commit and Release Workflow

Commit Message Template

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

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)

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.

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

Tips for Agents

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.