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:

1. CHANGELOG.md ⭐ START HERE
2. Sphinx Documentation (docs/source/)
3. Config Documentation (massgen/configs/README.md)
4. Case Studies (docs/source/examples/case_studies/)
5. README.md
6. README_PYPI.md (auto-synced via pre-commit)
7. 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:

1. Recent Achievements (move old to Previous Achievements)
2. Case Studies section
3. 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:

1. Pre-commit hook runs automatically
2. README_PYPI.md gets synced
3. 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):

1. ✅ CHANGELOG.md
2. ✅ docs/source/index.rst (Recent Releases)
3. ✅ docs/source/user_guide/ (if user-facing feature)
4. ✅ README.md (Recent Achievements)
5. ✅ massgen/configs/ (example configs)
6. ✅ 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:

1. Always read the release checklist first: docs/dev_notes/release_checklist.md
2. Follow the order strictly: CHANGELOG → Sphinx → README → Roadmap
3. Build docs after changes: cd docs && make html && make linkcheck
4. Test all new configs before committing
5. 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.