macalbert/envilder/release-coherence

Release Coherence

Ensures all documentation surfaces stay aligned when releasing a new version of any component: CLI, GitHub Action, or SDK (any runtime).

When to Use

• Bumping a version of CLI, GHA, or any SDK
• After merging a feature/fix that warrants a changelog entry
• Before tagging a release to verify nothing was missed
• When asked to "prepare the release" for a component

Components & Their Artifacts

Workflow

Step 1: Bump Version

Update the canonical version source file for the component.

Step 2: Changelog Entry

Add entry to docs/changelogs/{component}.md following doc-maintenance skill format (categories: Added/Changed/Fixed/Documentation/Dependencies/Security).

Step 3: ROADMAP Update (if applicable)

Check ROADMAP.md for related items:

• Move completed features to appropriate status
• Update version references if roadmap tracks versions
• Skip if the release has no roadmap-tracked features

Step 4: Website Updates

For SDKs (delegate to sdk-release-checklist if new SDK)

• [ ] Version badge auto-updates via astro.config.mjs (verify build picks it up)
• [ ] Update DocsContent.astro if API changed (new methods, flags, options)
• [ ] Update Sdks.astro card if install command changed
• [ ] Update i18n keys if new strings added (types.ts + en.ts, ca.ts, es.ts)
• [ ] Changelog page sidebar already wired (no action for existing SDKs)

For CLI

• [ ] Update DocsContent.astro CLI section if new flags/options added
• [ ] Update docs/pull-command.md or docs/push-command.md if behavior changed
• [ ] Update root README.md if install or quick-start changed

For GHA

• [ ] Update DocsContent.astro GHA section if inputs changed
• [ ] Update github-action/action.yml description/inputs
• [ ] Update github-action/README.md and docs/github-action.md

Step 5: Cross-Reference Check

• [ ] Root README.md reflects current capabilities
• [ ] Examples in examples/sdk/{runtime}/ match current API
• [ ] SDK README (src/sdks/{runtime}/README.md) matches current API

Step 6: Validate

# Build website: verifies versions resolve and pages render
cd src/website && pnpm build
 
# Run doc-sync skill for comprehensive drift detection
# (or manually verify key surfaces)

Delegate to doc-sync skill for full cross-surface audit if uncertain.

Quick Reference: Minimum Actions Per Component

CLI / GHA release (no API change)

1. Bump version in package.json
2. Add changelog entry
3. Done (website picks up version dynamically)

CLI / GHA release (with new flag/input)

1. Bump version in package.json
2. Add changelog entry
3. Update docs (command reference, DocsContent)
4. Update README
5. Run doc-sync

SDK release (no API change)

1. Bump version in source file
2. Add changelog entry
3. Done (badge auto-updates via website build)

SDK release (with new API)

1. Bump version in source file
2. Add changelog entry
3. Update SDK README
4. Update examples
5. Update DocsContent.astro section
6. Update i18n if new strings
7. Run doc-sync

Delegation Map

Anti-Patterns