Create a Ruby-only release process aligned with control-plane-flow and Shakapacker

Start with rakelib/release.rake and the existing RSpec and RuboCop setup; compare the referenced control-plane-flow and Shakapacker release tasks and specs, adapting only the Ruby release behavior. Map the current release flow and its tests before tackling the requested safety gates, dry-run isolation, publication, and recovery paths. Done means the documented Ruby-only release and notes-sync tasks satisfy the acceptance criteria; linked pull request #38 indicates work is already underway.

Goal

Create a documented, tested Ruby-only release process for UberTask aligned with the release conventions in control-plane-flow and Shakapacker. Use control-plane-flow as the closest implementation reference and adopt Shakapacker's applicable safety and recovery behavior. Do not introduce Node.js, npm, Yarn, npx, release-it, package.json, or a second package registry.

Current gaps

rakelib/release.rake currently:

• Defaults to a patch bump instead of resolving a prepared changelog version.
• Runs git pull --rebase, bumps the version, and updates the lockfile even in dry-run mode, changing the caller's checkout.
• Uses broad git add -A, pushes the current branch and all tags, and has no release-commit CI gate.
• Interpolates the version and OTP into shell command strings and retries arbitrary failures.
• Leaves GitHub release creation as a manual follow-up and has no separate notes-sync recovery task.

The project already has gem-release, RSpec, RuboCop, a version file, and CHANGELOG.md. Extend or replace the existing task rather than adding a competing release entry point.

Proposed scope

Changelog-first version selection

• Support bundle exec rake release, explicit stable/prerelease RubyGems versions, patch/minor/major, and a dry-run argument.
• Prefer the latest versioned changelog entry for argument-less releases. Specify and test the fallback policy; never automatically promote a prerelease to stable through a patch fallback.
• Validate version syntax, monotonic ordering against release tags, and bump policy against changelog headings. Any policy override must be explicit and reported.
• Support UberTask's existing ### [version] changelog headings, or deliberately migrate and document the format; do not silently copy reference parsers that expect different headings.
• Use RubyGems version syntax throughout, including prereleases such as 0.2.0.rc.1; document one consistent tag convention.

Safe preparation and publication

• Preflight a clean checkout, expected repository/remote, branch eligibility, Bundler/gem-release availability, and GitHub authentication/write access before release mutations.
• Prepare version/changelog/lockfile changes on a feature branch and merge them through a PR. Do not copy the reference scripts' direct pushes to main.
• Require stable releases to originate from merged main; define the permitted prerelease branch policy.
• Gate publication on passing RSpec and RuboCop checks for the exact commit being tagged, after any refresh/rebase. Missing, pending, or failed checks must block release; document any narrowly scoped, explicit override policy.
• Stage only intended release files, publish only the intended tag, and never overwrite an existing tag pointing to another commit.
• Make dry runs unattended and isolated in a temporary checkout/worktree: leave the caller's tracked files, index, branch, and tags unchanged; do not push, publish to RubyGems, or create/edit GitHub releases. Exercise version resolution, preparation, and gem build validation.
• Use argument-array subprocess calls and redact secrets. Retain RubyGems MFA/OTP support, obtain a fresh OTP when appropriate, and bound retries to recoverable publication failures.

GitHub releases and recovery

• After successful RubyGems publication, create or update the GitHub release from the matching committed changelog section; set prerelease status correctly and verify the existing tag.
• Add bundle exec rake "sync_github_release[VERSION]" plus dry-run support for notes-only recovery without another version bump or gem publication.
• Clearly report which steps succeeded when tagging, gem publication, or GitHub notes synchronization fails. Document how to resume the same version safely, verify already-published artifacts, and avoid duplicate publication or an accidental new patch release.
• Document behavior for missing/empty changelog sections and require actionable output.

Acceptance criteria

• One Ruby-only release entry point and a separate GitHub-notes sync task are available and documented with stable, prerelease, dry-run, and recovery examples.
• Release preparation follows the feature-branch/PR workflow; publication tags the exact validated merged commit for stable releases.
• RSpec covers version/changelog resolution, branch and CI gates, scoped staging/tag pushes, OTP handling, tag conflicts, and partial-failure recovery without real external publication.
• An integration-style dry-run test proves the caller's checkout/index/tags remain unchanged and no remote write occurs, including on failure.
• GitHub notes synchronization is repeatable and does not republish the gem.
• Existing RSpec and RuboCop checks pass; no JavaScript package-management dependency is added.

References

• UberTask release task
• control-plane-flow Ruby-only release task and release specs
• Shakapacker release task and release specs

Adapt the shared behavior, rather than porting Shakapacker's npm publication/version-conversion machinery or control-plane-flow-specific downstream deployment reminders.