/release-changelog

name: release-changelog
description: Keep CHANGELOG.md idiomatic (Keep a Changelog) and cut a tag-based GitHub release that triggers npm publish CI.
kind: sop

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

5. Commit release metadata

Commit version/changelog updates before tagging.

**Constraints:**

• You MUST stage only intended release files (at minimum `CHANGELOG.md`, plus version bumps)
• You MUST use a conventional release commit message, recommended:
• `chore(release): v{version}`
• You MUST verify commit succeeds before continuing

6. Create tag

Create the release tag from the release commit.

**Constraints:**

• You MUST create annotated tag `v{version}`
• You MUST verify tag points to the release commit (`git show v{version} --no-patch`)

7. Push and create GitHub release

Push release artifacts and create release notes from changelog.

**Constraints:**

• You MUST ask for explicit confirmation before push/release actions
• If `{push_tag_and_branch}=true`, you MUST push branch and tag to origin
• If `{create_github_release}=true`, you MUST create GitHub Release with notes from `{version}` changelog section
• You MUST ensure release title matches tag (`v{version}`)
• You SHOULD use `--verify-tag` when creating the GitHub Release

Suggested command shape:

gh release create "v{version}" \
  --title "v{version}" \
  --notes-file /tmp/release-notes-v{version}.md \
  --verify-tag

8. Post-release verification

Confirm CI and package publication status.

**Constraints:**

• You MUST verify GitHub release exists for `v{version}`
• You MUST verify Publish workflow started/completed
• You SHOULD verify npm version after publish:
• `npm view @rhobot-dev/rho version`
• You MUST report final status with links to tag, release, and workflow run

Output

When complete, report:

• released version/tag
• commit hash
• changelog path updated
• GitHub release URL
• publish workflow URL/status
• npm version observed

Troubleshooting

• **`package.json` mismatch with tag**: update version and re-commit before creating release
• **Tag already exists**: stop and decide whether to bump version or intentionally re-release
• **Release created but npm not published**: check `publish.yml` run logs and npm environment permissions
• **Empty release notes**: extract notes from the matching `## [{version}]` section only