mikeyobrien/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

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