release_ceremony 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e73ee4ce1ed15cf0e500cf1599d8cd2c288ca37cffd4ef8c5f2267dcfb9f9653
+  data.tar.gz: 87d220e6796d3acd7455651f4340215e7b0f5e4ad6927f8343dd373b8ca84b74
+SHA512:
+  metadata.gz: 797b5474be23312a9d7f430338a57744f525e5c2226a7122a98dedc5c48fff62af7cc4a9132e7ff3edf67ef1c4777066300181b06e46312105990a18ad0cc708
+  data.tar.gz: d9dba2117e6ba35a3ec8060c036e58f22eee3ffed0d56492b7708b8ff50e34998566c93db23a65bf6d0cf0da146eae94fdce190bf1f35af46475fb189b459b2d

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-07-25
+
+### Added
+
+- `release_ceremony prepare VERSION`: update the version file and changelog on
+  the `release-vVERSION` branch and run the verification commands, without
+  committing or pushing. Extracted from `url_canonicalize`'s
+  `bin/release/prepare`.
+- `release_ceremony publish VERSION`: validate the merged release pull
+  request, tag its merge commit, watch the tag-triggered release workflow, and
+  confirm the gem appears on RubyGems. Extracted from `url_canonicalize`'s
+  `bin/release/publish`.
+- Project auto-detection from the repository's gemspec, with optional
+  overrides in `.release_ceremony.yml` (release file paths, verification
+  commands, workflow file, default branch, and remote).
+
+[Unreleased]: https://github.com/dominicsayers/release_ceremony/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/dominicsayers/release_ceremony/compare/v0.0.0...v1.0.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Sayers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# release_ceremony
+
+A strict, verified release ceremony for RubyGems projects hosted on GitHub.
+
+`release_ceremony` provides two commands:
+
+- **`release_ceremony prepare VERSION`** — on the `release-vVERSION` branch,
+  updates the version file, moves the changelog's Unreleased notes under a
+  dated release heading, rewrites the comparison links, and runs the
+  verification commands. It never commits or pushes.
+- **`release_ceremony publish VERSION`** — after the release pull request has
+  merged, validates the merge commit, tags it `vVERSION`, pushes the tag,
+  watches the tag-triggered GitHub Actions release workflow, and confirms the
+  new version appears on RubyGems.
+
+Both commands validate aggressively and fail loudly: every transformation is
+exact-match, file writes are transactional, and nothing is tagged or pushed
+until you type the confirmation phrase.
+
+## The ceremony
+
+```sh
+git switch -c release-v1.2.3
+release_ceremony prepare 1.2.3
+# inspect the changes, then commit and push the branch
+# open the pull request and merge it
+release_ceremony publish 1.2.3
+```
+
+Publication itself happens in CI: the pushed tag triggers your release
+workflow, which should publish to RubyGems (for example with
+[Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) and the
+`rubygems/release-gem` action). `publish` only tags, watches, and verifies.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+group :build do
+  gem 'release_ceremony', require: false
+end
+```
+
+## What it assumes
+
+- The gem's version lives in `lib/<gem_name>/version.rb` as exactly one
+  single-quoted `VERSION = 'X.Y.Z'` assignment.
+- `CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/):
+  exactly one `## [Unreleased]` heading with notes, dated release headings,
+  and reference-style comparison links at the bottom.
+- Versions are strict `X.Y.Z` semantic versions (no prereleases), tagged
+  `vX.Y.Z`.
+- Release work happens on a branch named `release-vX.Y.Z`, merged to `main`
+  on the `origin` remote via exactly one pull request.
+- The repository is on GitHub, with the `gh` CLI installed and authenticated,
+  and has a `release.yml` workflow triggered by pushing the tag.
+
+The gem name and repository URL are read from the repository's gemspec
+(`metadata['source_code_uri']`, falling back to `homepage`). Everything else
+above is a convention that `.release_ceremony.yml` can override.
+
+## Configuration
+
+Create `.release_ceremony.yml` in the repository root to override any of the
+defaults:
+
+```yaml
+gem_name: my_gem                    # default: the gemspec's name
+repo_url: https://github.com/acme/my_gem # default: the gemspec's source_code_uri or homepage
+version_file: lib/my_gem/version.rb # default: lib/<gem_name>/version.rb
+changelog_file: CHANGELOG.md        # default: CHANGELOG.md
+workflow_file: release.yml          # default: release.yml
+default_branch: main                # default: main
+remote: origin                      # default: origin
+verification_commands:              # default: the four commands below
+  - bundle install
+  - bundle exec rspec
+  - bundle exec rubocop
+  - bundle exec rake build
+```
+
+`verification_commands` are split shell-style into words and run directly
+(no shell), in order, from the repository root. A project that manages its
+toolchain with [mise](https://mise.jdx.dev/), for example, would use
+`mise exec -- bundle exec rspec`.
+
+## Comparison with create_github_release
+
+[`create_github_release`](https://github.com/main-branch/create_github_release)
+automates the same job — releasing a gem hosted on GitHub through a release
+branch and pull request — but makes the opposite choice at almost every step:
+
+| | `release_ceremony` | `create_github_release` |
+| --- | --- | --- |
+| Committing and pushing | You commit, push, and open the PR yourself | One command commits, tags, pushes, and opens the PR |
+| Tag timing | Tags the merge commit after the PR merges, validating it first | Tags the release branch before merging, requiring a manual fast-forward merge |
+| Changelog | Promotes your curated Keep a Changelog `Unreleased` notes | Generates release notes from the commit list |
+| Verification | Runs configurable verification commands during `prepare` | None |
+| Publishing | Tag-triggered CI publishes; `publish` watches the workflow and confirms the version on RubyGems | Manual `rake release:rubygem_push` from your machine |
+| Version | Explicit `X.Y.Z` only | Computes major/minor/patch bumps, supports pre-releases |
+| GitHub release object | Not created | Created |
+
+Choose `create_github_release` if you want the release automated away in one
+command. Choose `release_ceremony` if you want curated release notes, a
+human inspecting and merging the release pull request, publication only from
+CI, and verification at every step.
+
+## Development
+
+```sh
+mise install
+bundle install
+bundle exec rspec    # tests
+bundle exec rubocop  # static code analysis
+```
+
+## License
+
+[MIT](LICENSE)

data/exe/release_ceremony

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'release_ceremony'
+
+begin
+  ReleaseCeremony::CLI.run(ARGV)
+rescue ReleaseCeremony::Error => e
+  warn "Error: #{e.message}"
+  exit 1
+end

data/lib/release_ceremony/changelog.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ReleaseCeremony
+  # Transforms a Keep a Changelog file for a release: the Unreleased notes
+  # move under a new dated heading and the comparison links are rewritten.
+  class Changelog
+    UNRELEASED_HEADING = /^## \[Unreleased\][ \t]*$/
+    VERSION_HEADING = /^## \[[^\]]+\].*$/
+    REFERENCE_DEFINITION = /^\[[^\]]+\]:[ \t]+.*$/
+    ANY_UNRELEASED_LINK = /^\[Unreleased\]:.*$/
+
+    def initialize(contents:, current_version:, version:, today:, compare_base:, changelog_file:)
+      @contents = contents
+      @current_version = current_version
+      @version = version
+      @today = today
+      @compare_base = compare_base
+      @changelog_file = changelog_file
+    end
+
+    def transform
+      heading = unreleased_heading
+      ensure_unreleased_notes!(heading)
+      ensure_requested_version_absent!
+      link = unreleased_link
+      ensure_previous_version_matches!(link)
+
+      insert_release_heading(heading).sub(link[0], replacement_links)
+    end
+
+    private
+
+    attr_reader :changelog_file, :compare_base, :contents, :current_version, :today, :version
+
+    def unreleased_link_pattern
+      /^\[Unreleased\]: #{Regexp.escape(compare_base)}v(?<previous>\d+\.\d+\.\d+)\.\.\.HEAD[ \t]*$/
+    end
+
+    def unreleased_heading
+      headings = contents.to_enum(:scan, UNRELEASED_HEADING).map { Regexp.last_match.dup }
+      raise Error, "#{changelog_file} must contain exactly one Unreleased heading" unless headings.one?
+
+      headings.first
+    end
+
+    def ensure_unreleased_notes!(heading)
+      following_text = contents[heading.end(0)..]
+      boundary = [VERSION_HEADING, REFERENCE_DEFINITION]
+                 .filter_map { |pattern| following_text.match(pattern) }
+                 .min_by { |match| match.begin(0) }
+      notes = boundary ? following_text[0...boundary.begin(0)] : following_text
+      raise Error, "#{changelog_file} Unreleased section has no notes" if notes.strip.empty?
+    end
+
+    def ensure_requested_version_absent!
+      heading_pattern = /^## \[#{Regexp.escape(version.to_s)}\].*$/
+      link_pattern = /^\[#{Regexp.escape(version.to_s)}\]:.*$/
+      raise Error, "#{changelog_file} heading for #{version} already exists" if contents.match?(heading_pattern)
+      raise Error, "#{changelog_file} comparison link for #{version} already exists" if contents.match?(link_pattern)
+    end
+
+    def unreleased_link
+      pattern = unreleased_link_pattern
+      candidates = contents.to_enum(:scan, ANY_UNRELEASED_LINK).map { Regexp.last_match.dup }
+      valid = candidates.select { |candidate| pattern.match?(candidate[0]) }
+      unless candidates.one? && valid.one?
+        raise Error, "#{changelog_file} must contain exactly one Unreleased comparison link"
+      end
+
+      pattern.match(valid.first[0])
+    end
+
+    def ensure_previous_version_matches!(link)
+      return if link[:previous] == current_version.to_s
+
+      raise Error,
+            "#{changelog_file} Unreleased link compares from v#{link[:previous]}, but VERSION is #{current_version}"
+    end
+
+    def insert_release_heading(heading)
+      release_heading = "#{heading[0]}\n\n## [#{version}] - #{today.strftime('%Y-%m-%d')}"
+      contents.sub(heading[0], release_heading)
+    end
+
+    def replacement_links
+      unreleased = "[Unreleased]: #{compare_base}v#{version}...HEAD"
+      release = "[#{version}]: #{compare_base}v#{current_version}...v#{version}"
+      "#{unreleased}\n#{release}"
+    end
+  end
+end

data/lib/release_ceremony/cli.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ReleaseCeremony
+  # Command-line entry point that dispatches to the ceremony commands.
+  class CLI
+    USAGE = 'Usage: release_ceremony prepare|publish VERSION'
+    HELP = <<~TEXT.freeze
+      #{USAGE}
+
+      Commands:
+        prepare VERSION  Update the release files on the release branch and run the checks.
+        publish VERSION  Tag the merged release pull request and watch the release workflow.
+
+      Run release_ceremony COMMAND --help for details of each command.
+    TEXT
+    COMMANDS = { 'prepare' => Prepare, 'publish' => Publish }.freeze
+
+    def self.run(arguments, runner: Runner.new, **options)
+      command, *command_arguments = arguments
+      if command == '--help'
+        runner.puts(HELP)
+        return true
+      end
+
+      handler = COMMANDS.fetch(command) do
+        raise Error, command ? "Unknown command #{command.inspect}\n#{USAGE}" : USAGE
+      end
+      handler.run(command_arguments, runner: runner, **options)
+    end
+  end
+end

data/lib/release_ceremony/command.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ReleaseCeremony
+  # Shared entry point behaviour for the ceremony commands: --help handling
+  # and strict VERSION argument parsing.
+  module Command
+    def run(arguments, runner: Runner.new, **options)
+      if arguments == ['--help']
+        runner.puts(self::HELP)
+        return true
+      end
+
+      new(version: parse_version(arguments), runner: runner, **options).call
+    end
+
+    private
+
+    def parse_version(arguments)
+      raise Error, self::USAGE unless arguments.length == 1
+
+      Semver.parse(arguments.first)
+    rescue Error => e
+      raise if e.message == self::USAGE
+
+      raise Error, "#{e.message}\n#{self::USAGE}"
+    end
+  end
+end

data/lib/release_ceremony/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ReleaseCeremony
+  class Error < StandardError; end
+end

data/lib/release_ceremony/prepare.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'shellwords'
+
+module ReleaseCeremony
+  # Prepares a release on its release-vVERSION branch: updates the version
+  # file, dates the changelog, and runs the verification commands. Never
+  # commits or pushes.
+  class Prepare
+    extend Command
+
+    USAGE = 'Usage: release_ceremony prepare VERSION'
+    HELP = <<~TEXT.freeze
+      #{USAGE}
+
+      Prepare VERSION on its release-vVERSION branch, update the release files,
+      and run the release checks. This command does not commit or push changes.
+    TEXT
+    VERSION_DECLARATION = /^[ \t]*VERSION[ \t]*=/
+    VERSION_ASSIGNMENT = /^(?<indent>[ \t]*)VERSION = '(?<current>[^'\r\n]+)'[ \t]*$/
+
+    def initialize(version:, runner:, project: nil, today: Date.today, writer: TransactionalWriter.new)
+      @version = version
+      @runner = runner
+      @project = project || Project.discover(runner: runner)
+      @today = today
+      @writer = writer
+    end
+
+    def call
+      Dir.chdir(project.root) { prepare_release }
+      print_next_steps
+      true
+    rescue SystemCallError => e
+      raise Error, e.message
+    end
+
+    private
+
+    attr_reader :project, :runner, :today, :version, :writer
+
+    def prepare_release
+      announce('Checking the release branch and working tree')
+      guard_repository!
+      announce("Updating #{project.version_file} and #{project.changelog_file}")
+      version_contents, current_version = transformed_version_file
+      write_release_files(version_contents, transformed_changelog(current_version))
+      run_verification_commands
+    end
+
+    def announce(message)
+      runner.puts("#{message}...")
+    end
+
+    def guard_repository!
+      branch = runner.capture('git', 'symbolic-ref', '--quiet', '--short', 'HEAD').strip
+      expected_branch = "release-v#{version}"
+      raise Error, "Current branch must be #{expected_branch}, not #{branch}" unless branch == expected_branch
+
+      status = runner.capture('git', 'status', '--porcelain=v1')
+      raise Error, 'Working tree must be clean before preparing a release' unless status.empty?
+    end
+
+    def transformed_version_file
+      contents = File.binread(project.version_file)
+      assignment = version_assignment(contents)
+      current_version = parse_current_version(assignment[:current])
+      raise Error, "Version #{version} must be greater than #{current_version}" unless version > current_version
+
+      replacement = "#{assignment[:indent]}VERSION = '#{version}'"
+      [contents.sub(VERSION_ASSIGNMENT, replacement), current_version]
+    end
+
+    def version_assignment(contents)
+      declarations = contents.lines.grep(VERSION_DECLARATION)
+      assignment = VERSION_ASSIGNMENT.match(declarations.first.to_s)
+      message = "#{project.version_file} must contain exactly one VERSION assignment"
+      raise Error, message unless declarations.one? && assignment
+
+      assignment
+    end
+
+    def parse_current_version(value)
+      Semver.parse(value)
+    rescue Error
+      raise Error, "Current VERSION must use the X.Y.Z format, not #{value.inspect}"
+    end
+
+    def transformed_changelog(current_version)
+      Changelog.new(
+        contents: File.binread(project.changelog_file),
+        current_version: current_version,
+        version: version,
+        today: today,
+        compare_base: project.compare_base,
+        changelog_file: project.changelog_file
+      ).transform
+    end
+
+    def write_release_files(version_contents, changelog_contents)
+      writer.write(project.version_file => version_contents, project.changelog_file => changelog_contents)
+    end
+
+    def run_verification_commands
+      project.verification_commands.each do |command|
+        announce("Running: #{Shellwords.join(command)}")
+        runner.run(*command)
+      end
+    end
+
+    def print_next_steps
+      runner.puts("Prepared version #{version} and completed the release checks.")
+      runner.puts('Inspect the changes, then commit and push the release branch.')
+      runner.puts("Open and merge the pull request before running release_ceremony publish #{version}.")
+    end
+  end
+end

data/lib/release_ceremony/project.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require 'yaml'
+
+module ReleaseCeremony
+  # The repository-specific facts the release ceremony needs: the gem name,
+  # the release file paths, the GitHub repository URL, and the verification
+  # commands. Project.load reads overrides from .release_ceremony.yml and
+  # falls back to the repository's gemspec and conventional defaults.
+  class Project
+    CONFIG_FILE = '.release_ceremony.yml'
+    CONFIG_KEYS = %w[gem_name repo_url version_file changelog_file verification_commands
+                     workflow_file default_branch remote].freeze
+    REPO_URL_PATTERN = %r{\Ahttps://github\.com/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+\z}
+    DEFAULT_VERIFICATION_COMMANDS = [
+      %w[bundle install],
+      %w[bundle exec rspec],
+      %w[bundle exec rubocop],
+      %w[bundle exec rake build]
+    ].freeze
+
+    attr_reader :root, :gem_name, :repo_url, :version_file, :changelog_file,
+                :verification_commands, :workflow_file, :default_branch, :remote
+
+    class << self
+      def discover(runner: Runner.new)
+        load(root: runner.capture('git', 'rev-parse', '--show-toplevel').strip)
+      end
+
+      def load(root:)
+        config = Config.read(root)
+        gemspec = GemspecFacts.new(root)
+        overrides = config.slice('version_file', 'changelog_file', 'verification_commands',
+                                 'workflow_file', 'default_branch', 'remote').transform_keys(&:to_sym)
+        new(
+          root: root,
+          gem_name: config.fetch('gem_name') { gemspec.name },
+          repo_url: config.fetch('repo_url') { gemspec.repo_url },
+          **overrides
+        )
+      end
+    end
+
+    def initialize(root:, gem_name:, repo_url:, version_file: nil, changelog_file: nil,
+                   verification_commands: nil, workflow_file: nil, default_branch: nil, remote: nil)
+      @root = validated_string(:root, root)
+      @gem_name = validated_string(:gem_name, gem_name)
+      @repo_url = validated_repo_url(repo_url)
+      @version_file = validated_string(:version_file, version_file || default_version_file)
+      @changelog_file = validated_string(:changelog_file, changelog_file || 'CHANGELOG.md')
+      @verification_commands = validated_commands(verification_commands || DEFAULT_VERIFICATION_COMMANDS)
+      @workflow_file = validated_string(:workflow_file, workflow_file || 'release.yml')
+      @default_branch = validated_string(:default_branch, default_branch || 'main')
+      @remote = validated_string(:remote, remote || 'origin')
+    end
+
+    def compare_base
+      "#{repo_url}/compare/"
+    end
+
+    def actions_run_url(run_id)
+      "#{repo_url}/actions/runs/#{run_id}"
+    end
+
+    private
+
+    def default_version_file
+      "lib/#{gem_name.tr('-', '/')}/version.rb"
+    end
+
+    def validated_string(name, value)
+      raise Error, "Project #{name} must be a non-empty string" unless value.is_a?(String) && !value.empty?
+
+      value
+    end
+
+    def validated_repo_url(value)
+      validated_string(:repo_url, value)
+      unless REPO_URL_PATTERN.match?(value)
+        raise Error, "Project repo_url must look like https://github.com/OWNER/REPO, not #{value.inspect}"
+      end
+
+      value
+    end
+
+    def validated_commands(commands)
+      valid = commands.is_a?(Array) && !commands.empty? &&
+              commands.all? { |command| command.is_a?(Array) && !command.empty? && command.all?(String) }
+      raise Error, 'Project verification_commands must be a list of commands, each a list of strings' unless valid
+
+      commands
+    end
+
+    # Reads and validates the optional .release_ceremony.yml overrides.
+    module Config
+      extend self
+
+      def read(root)
+        path = File.join(root, CONFIG_FILE)
+        return {} unless File.exist?(path)
+
+        config = parse(path)
+        unknown = config.keys - CONFIG_KEYS
+        raise Error, "#{CONFIG_FILE} has unknown keys: #{unknown.join(', ')}" unless unknown.empty?
+
+        parse_verification_commands(config)
+      end
+
+      private
+
+      def parse(path)
+        config = YAML.safe_load_file(path)
+        raise Error, "#{CONFIG_FILE} must contain a YAML mapping" unless config.is_a?(Hash)
+
+        config
+      rescue Psych::Exception => e
+        raise Error, "#{CONFIG_FILE} is not valid YAML: #{e.message}"
+      end
+
+      def parse_verification_commands(config)
+        return config unless config.key?('verification_commands')
+
+        commands = config['verification_commands']
+        valid = commands.is_a?(Array) && commands.all?(String)
+        raise Error, "#{CONFIG_FILE} verification_commands must be a list of command strings" unless valid
+
+        config.merge('verification_commands' => commands.map { |command| split_command(command) })
+      end
+
+      def split_command(command)
+        Shellwords.split(command)
+      rescue ArgumentError => e
+        raise Error, "#{CONFIG_FILE} verification_commands entry #{command.inspect} is invalid: #{e.message}"
+      end
+    end
+
+    # Lazily extracts facts from the repository's gemspec, so a fully
+    # configured project never needs to load it.
+    class GemspecFacts
+      def initialize(root)
+        @root = root
+      end
+
+      def name
+        specification.name
+      end
+
+      def repo_url
+        url = specification.metadata['source_code_uri'] || specification.homepage
+        url.to_s.chomp('/')
+      end
+
+      private
+
+      def specification
+        @specification ||= load_specification
+      end
+
+      def load_specification
+        path = gemspec_path
+        Gem::Specification.load(path) || raise(Error, "Could not load the gemspec at #{path}")
+      end
+
+      def gemspec_path
+        paths = Dir.glob('*.gemspec', base: @root).sort
+        raise Error, "Expected exactly one gemspec in #{@root}; found #{paths.length}" unless paths.one?
+
+        File.join(@root, paths.first)
+      end
+    end
+  end
+end