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:

Fresh-branch bootstrap (once, at branch creation) — version bump + rename ROADMAP_v0.1.X.md → ROADMAP_v0.1.X+1.md (see Phase 0)
CHANGELOG.md ⭐ START HERE
Version bump (massgen/__init__.py __version__)
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)
Announcements (docs/announcements/) — current-release.md, github-release-vX.md, archive

This order is critical - never skip ahead!

Quick Reference Workflow

Phase 0: Fresh Release Branch Bootstrap (do this when the branch is created)

⚠️ Easy to miss — this happens once, at the start of a new dev/v0.1.X branch, not at doc-writing time. When dev/v0.1.X is branched (right after the previous release merges in), a small bootstrap commit (feat: v0.1.X) sets the branch up:

Bump the version: massgen/__init__.py __version__ = "0.1.X" (pyproject.toml reads it dynamically).
Roll the forward-looking roadmap file: rename ROADMAP_v0.1.X.md → ROADMAP_v0.1.X+1.md and rewrite its content to plan the next release. This file always names the version after the one currently in development (the in-development version is tracked in the main ROADMAP.md sections). Update its title, "Overview", the deferred-feature "Deferred from …" range, and add the just-shipped version(s) to its "Related Tracks" list.

git mv ROADMAP_v0.1.X.md ROADMAP_v0.1.X+1.md
# then edit __version__ and the renamed roadmap file

If you arrive mid-branch and find ROADMAP_v0.1.X.md (matching the in-dev version) still present, or __version__ still on the previous release, the bootstrap was skipped — do it now before the release docs.

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)

Phase 8: Announcements (`docs/announcements/`)

⚠️ Easy to miss — not auto-generated. Each release rotates three things in docs/announcements/:

Archive the outgoing announcement: copy the current current-release.md to archive/v0.1.X-1.md (the version it currently describes).
```
cp docs/announcements/current-release.md docs/announcements/archive/v0.1.X-1.md
```
Rewrite current-release.md for the new version: update the title, Release Summary, Install version, release-notes link, "Suggested image" version, and the full LinkedIn announcement body (Key Improvements bullets). This is the long-form social/LinkedIn copy.
Replace the GitHub-release highlights file: delete github-release-v0.1.X-1.md and create github-release-v0.1.X.md (the short, emoji-sectioned GitHub Releases body dated (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 and README.md in that directory are general (not per-version) — leave them unless the highlights changed.

Use the just-archived previous version's files as templates so the structure/sections stay consistent. Keep [TO BE ADDED AFTER POSTING] placeholders for the X/LinkedIn links.

Don't forget the version bump (massgen/__init__.py __version__ = "0.1.X") — pyproject.toml reads the version dynamically from there.

Quick Validation Checklist

Must Update (every release): 0. ✅ Fresh-branch bootstrap done? (__version__ bumped + ROADMAP_v0.1.X.md → ROADMAP_v0.1.X+1.md renamed — see Phase 0)

✅ CHANGELOG.md
✅ massgen/__init__.py (__version__ bump)
✅ docs/source/index.rst (Recent Releases)
✅ README.md (Recent Achievements + Latest Features + TOC anchors)
✅ ROADMAP.md (Current Version, completed section, table)
✅ docs/announcements/ (archive old, rewrite current-release.md, swap github-release-vX.md)
⚠️ docs/source/user_guide/ (if user-facing feature)
⚠️ massgen/configs/ (example configs, if any)
⚠️ Case study (skip for internal-quality/no-user-facing-feature releases)

Should Update (if applicable): 10. ⚠️ massgen/config_builder.py (if config params added) 11. ⚠️ massgen/backend/capabilities.py (if backend changes) 12. ✅ README_PYPI.md (auto-synced from README.md via pre-commit)

Build & Verify: 13. 🔨 cd docs && make html && make linkcheck 14. 🔨 Test new config files 15. 🔨 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.