/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:**

0. **Fresh-branch bootstrap** (once, at branch creation) — version bump + rename `ROADMAP_v0.1.X.md` → `ROADMAP_v0.1.X+1.md` (see Phase 0) 1. **CHANGELOG.md** ⭐ START HERE 2. **Version bump** (`massgen/__init__.py` `__version__`) 3. **Sphinx Documentation** (docs/source/) 4. **Config Documentation** (massgen/configs/README.md) 5. **Case Studies** (docs/source/examples/case_studies/) 6. **README.md** 7. **README_PYPI.md** (auto-synced via pre-commit) 8. **Roadmap** (ROADMAP.md) 9. **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:

1. **Bump the version**: `massgen/__init__.py` `__version__ = "0.1.X"` (`pyproject.toml` reads it dynamically). 2. **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: 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)

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

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

1. **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

2. **Rewrite `current-release.md`** for the new version: update the title, Release Sum