massgen-release-documenter

name	massgen-release-documenter
description	Guide for following MassGen's release documentation workflow. This skill should be used when preparing release documentation, updating changelogs, writing case studies, or maintaining project documentation across releases.
license	MIT

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.