Release Changelog

Release + CHANGELOG Workflow

Overview

Use this SOP to run a clean release process for rho:

1. maintain an idiomatic CHANGELOG.md (Keep a Changelog + SemVer),
2. ensure package.json version, git tag, and changelog section match,
3. publish a GitHub Release from changelog notes,
4. let CI publish npm from the release event.

This SOP is designed for the existing workflow in .github/workflows/publish.yml (release.published trigger).

Parameters

• version (required): SemVer version without v prefix (example: 0.1.8)
• date (optional, default: current UTC date YYYY-MM-DD): Release date for changelog header
• changelog_path (optional, default: CHANGELOG.md): Path to changelog file
• release_branch (optional, default: main): Branch to release from
• run_tests (optional, default: true): Run validation tests before release
• create_github_release (optional, default: true): Create GitHub Release with notes from changelog
• push_tag_and_branch (optional, default: false): Push branch/tag after explicit confirmation

Steps

1. Gather release inputs

Confirm version/date and whether this is a stable release.

Constraints:

• You MUST validate version as SemVer (X.Y.Z)
• You MUST derive tag as v{version}
• You MUST confirm risky external actions before executing them:
  • pushing to remote
  • creating GitHub Release

2. Preflight repository state

Verify the local repository is safe to release.

Constraints:

• You MUST verify working tree is clean (git status --short)
• You MUST verify current branch matches {release_branch}
• You MUST fetch tags and remote state before release (git fetch --tags origin)
• You MUST fail fast if tag already exists locally or on origin
• You MUST verify gh auth status succeeds before attempting release creation

3. Ensure idiomatic changelog structure

Create/normalize CHANGELOG.md using Keep a Changelog format.

Constraints:

• If {changelog_path} does not exist, you MUST create it with:
  • # Changelog
  • intro lines for Keep a Changelog + SemVer
  • ## [Unreleased]
  • compare-link section at file bottom
• You MUST keep section format exactly:
  • ## [Unreleased]
  • ## [{version}] - {date}
• You SHOULD use standard subsections where applicable:
  • ### Added
  • ### Changed
  • ### Fixed
  • ### Removed
  • ### Security
• You MUST move release-ready content from Unreleased into [{version}]
• You MUST update compare links at bottom:
  • [Unreleased]: ...compare/{tag}...HEAD
  • [{version}]: ...compare/{previous_tag}...{tag} (or repo root page for first release)

4. Validate version contract

Validate the release contract expected by CI.

Constraints:

• You MUST verify package.json version equals {version}
• You MUST verify changelog contains ## [{version}] - {date}
• You MUST verify changelog section for {version} is non-empty
• If {run_tests}=true, you MUST run project test gates before tagging
• You MUST NOT proceed to tag/release when any validation fails