release_flow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c7b889dd512fd0e5aa6af560b92a2f6fe0e58d1c087c4731738405204e903037
+  data.tar.gz: 03a63137a76d8b4f030814e740cce67498b0a94a8c2c5c259df445eaab1339b2
+SHA512:
+  metadata.gz: 98fc8c51ed01ba688cfbabfbe47ddd4aa44ed484200000fef5329a726150086db3942c608a32f6b78198259f207e10d1180b68ad05a196ae58d52a5b1300371b
+  data.tar.gz: 28a47976be60cfacc64414f4d56f9285dff442520bd951ae5ca928da474ab27ff38243a326cfee5c4cf9776707f5ddf9a380977a78b95c91ff549e3587c368f6

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## 0.1.0
+
+- First release: `bin/release prepare`, `cut`, `ship`, `merge-back` and `check`, extracted from ModelRails; `release_flow init` installs the binstub, the release workflow, the release PR template and the `changelog.d/` README.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dave Chmura
+
+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,145 @@
+# release_flow
+
+Release a GitHub repository through review on staging, so production always
+runs a commit someone checked, tagged and ready to roll back to.
+
+```text
+your branch ──merge──▶ next ──cut──▶ release/<name> ──ship──▶ main
+  you test it         CI checks it    staging; people review it   production; tagged
+                         ▲                                           │
+                         └──────────────── merge-back ───────────────┘
+```
+
+- **Changelog entries never conflict.** Each PR adds its entry as a file of
+  its own in `changelog.d/`. A release gathers them into `CHANGELOG.md`.
+- **A release is exactly what its notes say.** `cut` takes the integration
+  branch as it stood the last time no entry was waiting, so work merged
+  after the release was named waits for the next one.
+- **Production runs the reviewed commit.** `ship` finds the release PR and
+  the commit staging last deployed, asks before shipping, and merges with
+  GitHub's head-commit check. If the branch moved since, nothing ships.
+- **One release at a time**, with a GitHub Release and tag for each.
+
+It runs on `git` and the [GitHub CLI](https://cli.github.com) (`gh`), and
+has no dependencies beyond Ruby 3.3. Rails isn't required.
+
+## Install
+
+```bash
+bundle add release_flow --group development
+bundle exec release_flow init
+```
+
+`init` writes these files, and keeps any that already exist:
+
+| File | What it's for |
+| --- | --- |
+| `bin/release` | the command you run |
+| `.github/workflows/next_release.yml` | starts releases on its own, once switched on |
+| `.github/PULL_REQUEST_TEMPLATE/release.md` | the release PR's body |
+| `changelog.d/README.md` | how a PR adds its changelog entry |
+| `CHANGELOG.md` | started with an `## [Unreleased]` section if you have none |
+
+Then:
+
+1. Add `bin/release check` to your CI workflow. It fails a PR that edits the
+   notes of a release already shipped.
+2. Ask for a changelog file in your PR template, for example
+   "a file of its own in `changelog.d/`".
+3. Create the `next` branch from `main`, and make it the branch PRs target.
+4. Deploy `release/**` pushes to staging and `main` pushes to production.
+   `ship` reads your staging workflow's runs to find the commit staging ran.
+5. Protect `next`, `release/*` and `main` so changes arrive by PR with
+   passing checks, and turn on "Automatically delete head branches":
+   `bin/release` tells that a release is under way by its branch existing.
+
+## Settings
+
+Everything defaults to the names above. To use others, add a
+`.release_flow.yml` at the repository's root, then run `init` (or edit the
+files it wrote):
+
+```yaml
+integration_branch: develop   # default: next
+production_branch: trunk      # default: main
+ci_workflow: test.yml         # default: ci.yml, the workflow cut waits on
+staging_workflow: staging.yml # default: deploy.yml, whose deploys ship reads
+guide: https://example.com/releasing   # where --help and the templates point
+template: me/template         # the GitHub repository this one forks, if any
+```
+
+A setting it doesn't know stops `bin/release` with the list of those it does.
+
+## Release
+
+```bash
+bin/release prepare   # name the release: gather changelog.d/ into CHANGELOG.md, by PR into next
+bin/release cut       # push release/<name>, which deploys staging, and open its PR into main
+bin/release ship      # merge the reviewed commit, publish v<name>, merge main back into next
+```
+
+Every command takes `--dry-run`. A release is named for the day,
+`2026.11.02`, and a second that day is `2026.11.02-2`.
+
+**Review on staging.** The release PR's "What ships" is its changelog
+section; work through each PR in it on staging. A fix found in review goes
+into the release branch by PR, with its changelog line under that release's
+`## v<name>` section, not in `changelog.d/`, which would wait for the next
+release.
+
+**Hold back a PR** by reverting it on the release branch, by PR, and
+deleting its changelog line. To bring it back later, revert the revert on
+`next` and add its entry to `changelog.d/` again.
+
+**Ship.** `bin/release ship` shows the PR and the commit it found and asks
+`Ship abc1234? [y/N]`. With no terminal, as in CI, name both:
+`bin/release ship <PR> <commit>`. If any step stops partway, run it again; it
+skips what's done.
+
+**Hotfix.** A fix production can't wait for goes to `main` by PR, with its
+entry in `changelog.d/`. Then run `bin/release merge-back`.
+
+## Starting releases on their own
+
+With the workflow switched on, a release is named whenever a PR merges into
+`next` and none is under way, and cut once CI passes there. If CI fails
+where it would cut, the run fails and says so. Shipping stays a person's
+call.
+
+### Set up the release token
+
+GitHub runs no checks on a PR opened with a workflow's built-in token, so
+the changelog PR would never merge. The workflow needs a token of its own:
+
+1. On GitHub, open **Settings → Developer settings → Personal access tokens →
+   Fine-grained tokens → Generate new token**.
+2. Under **Repository access**, choose **Only select repositories** and pick
+   this repository.
+3. Under **Permissions**, set **Contents** and **Pull requests** to **Read and
+   write**.
+4. Choose an expiry, and note it: once it expires, releases stop starting on
+   their own until you replace it.
+5. Store it as a secret. The command prompts for it, so it stays out of your
+   shell history:
+
+   ```bash
+   gh secret set RELEASE_TOKEN --repo <owner>/<repo>
+   ```
+
+6. Switch the workflow on:
+
+   ```bash
+   gh variable set AUTO_RELEASE --body true --repo <owner>/<repo>
+   ```
+
+## A changelog of your own
+
+`ReleaseFlow::Changelog` holds the changelog format and the release-name
+convention, and `bin/release` reads them only through its public methods. A
+project that keeps its changelog another way can reopen that module in
+`bin/release`, after `require "release_flow"`, keeping the method
+signatures.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/exe/release_flow

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "release_flow"
+
+exit ReleaseFlow::Installer.start(ARGV, root: Dir.pwd)

data/lib/release_flow/candidate.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ReleaseFlow
+  # The release PR bin/release ship finds when it isn't named one, and the commit it would ship.
+  module Candidate
+    class Error < ReleaseFlow::Error; end
+
+    BRANCH = %r{\Arelease/(#{Changelog::NAME})\z}
+
+    module_function
+
+    # prs: gh pr list's number, headRefName, state and headRefOid; shipped: whether a release name was published.
+    def waiting(prs, usage:, &shipped)
+      waiting = prs.select do |pr|
+        name = pr["headRefName"][BRANCH, 1]
+        name && (pr["state"] == "OPEN" || (pr["state"] == "MERGED" && !shipped.call(name)))
+      end
+      raise Error, "No release PR is waiting to ship: bin/release cut opens one" if waiting.empty?
+      raise Error, "#{waiting.map { |pr| "##{pr["number"]}" }.join(" and ")} are waiting to ship: name one, #{usage}" if waiting.size > 1
+
+      waiting.first
+    end
+
+    # runs: gh run list's headSha and conclusion for the release branch's staging deploys, newest first.
+    def found(pr, runs)
+      head = pr["headRefOid"]
+      deployed = runs.find { |run| run["conclusion"] == "success" }&.dig("headSha")
+      return "the branch's head; no successful staging deploy found for it" unless deployed
+      return "the commit staging's last deploy ran" if deployed == head
+
+      raise Error, "staging last ran #{deployed[0, 7]}, but #{pr["headRefName"]} is at #{head[0, 7]}: review its deploy, " \
+                   "or name the commit you reviewed, bin/release ship #{pr["number"]} <commit>"
+    end
+
+    def confirmed?(pr, head)
+      raise Error, "No terminal to confirm on: name the PR and commit, bin/release ship #{pr} #{head[0, 7]}" unless $stdin.tty?
+
+      print("Ship #{head[0, 7]}? [y/N] ")
+      $stdin.gets.to_s.strip.casecmp?("y")
+    end
+  end
+end

data/lib/release_flow/changelog.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ReleaseFlow
+  # The changelog, its changelog.d fragments, and the release-name convention bin/release reads through this module.
+  # A project that keeps its changelog another way reopens this module and keeps the signatures.
+  module Changelog
+    class Error < ReleaseFlow::Error; end
+
+    NAME = '\d{4}\.\d{2}\.\d{2}(?:-\d+)?'
+    UNRELEASED = "## [Unreleased]\n"
+    FRAGMENTS = "changelog.d"
+
+    module_function
+
+    def names(today)
+      date = today.strftime("%Y.%m.%d")
+      (1..).lazy.map { |n| (n == 1) ? date : "#{date}-#{n}" }
+    end
+
+    def name_release(text, name, fragments = [])
+      head, rest = text.split(UNRELEASED, 2)
+      raise Error, "CHANGELOG.md has no #{UNRELEASED.strip} section" if rest.nil?
+
+      body, tail = rest.split(/^(?=## )/, 2)
+      sections = fold([body, *fragments])
+      raise Error, "no entries under #{UNRELEASED.strip} or in #{FRAGMENTS}/; there is nothing to release" if sections.empty?
+
+      released = sections.map { |title, lines| "### #{title}\n\n#{lines.join("\n")}\n" }.join("\n")
+      "#{head}#{UNRELEASED}\n## v#{name}\n\n#{released}\n#{tail}"
+    end
+
+    def fragment?(path) = path.match?(%r{\A#{FRAGMENTS}/[^/]+\.md\z}o) && File.basename(path) != "README.md"
+    def fragment(title, entries) = "### #{title}\n\n#{entries.join("\n")}\n"
+
+    def named_release(text)
+      text[/^## \[Unreleased\]\n.*?^## v(#{NAME})$/mo, 1]
+    end
+
+    def unreleased(text, fragments = [])
+      body = text.split(UNRELEASED, 2).last.to_s.split(/^(?=## )/, 2).first.to_s
+      fold([body, *fragments]).values.flatten
+    end
+
+    def section(text, name)
+      text[/^## v#{Regexp.escape(name)}\n(.*?)(?=^## |\z)/m, 1]&.strip
+    end
+
+    # tagged: each shipped release's name and the CHANGELOG.md it was tagged with.
+    def changed_releases(text, tagged)
+      tagged.filter_map do |name, at_tag|
+        shipped, now = [at_tag, text].map { |t| section(t, name)&.lines(chomp: true) }
+        next unless shipped && now && now != shipped
+
+        lines = {"added" => now - shipped, "removed" => shipped - now}.flat_map { |how, ls| ls.map { |l| "  #{how}: #{l}" } }
+        "v#{name} has shipped, so its notes in CHANGELOG.md stay as tagged:\n#{lines.join("\n")}\nA new entry belongs in #{FRAGMENTS}/."
+      end
+    end
+
+    def fold(bodies)
+      bodies.each_with_object({}) do |body, sections|
+        current = "Changed"
+        body.each_line(chomp: true) do |line|
+          if (title = line[/\A### (.+)/, 1])
+            current = title
+          elsif !line.strip.empty?
+            (sections[current] ||= []) << line
+          end
+        end
+      end
+    end
+    private_class_method :fold
+  end
+end

data/lib/release_flow/cli.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module ReleaseFlow
+  # What bin/release runs: parses its options and hands the command to Release.
+  module CLI
+    module_function
+
+    def start(argv, root:)
+      config = Config.load(root)
+      options = {}
+      args = OptionParser.new do |o|
+        o.banner = "#{Release::USAGE}   (see #{config.guide})"
+        o.on("--dry-run", "Print the plan without changing anything") { options[:dry_run] = true }
+        o.on("--if-needed", "prepare, cut: when there's nothing to do yet, say so and stop without failing") { options[:if_needed] = true }
+      end.parse(argv)
+      Release.new(options, root: root, config: config).run(*args)
+      0
+    rescue Error, OptionParser::ParseError => e
+      warn("bin/release: #{e.message}")
+      1
+    end
+  end
+end

data/lib/release_flow/config.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module ReleaseFlow
+  FILE = ".release_flow.yml"
+  DEFAULTS = {integration_branch: "next", production_branch: "main", ci_workflow: "ci.yml",
+              staging_workflow: "deploy.yml", guide: "https://github.com/dschmura/release_flow#readme", template: nil}.freeze
+
+  # The names the flow reads from an optional .release_flow.yml at the repository's root.
+  Config = Data.define(*DEFAULTS.keys) do
+    def self.load(root)
+      path = File.join(root, FILE)
+      settings = File.exist?(path) ? YAML.safe_load_file(path).to_h.transform_keys(&:to_sym) : {}
+      unknown = settings.keys - members
+      raise Error, "#{FILE} has no setting #{unknown.join(", ")}; it takes #{members.join(", ")}" if unknown.any?
+
+      new(**DEFAULTS, **settings)
+    end
+  end
+end

data/lib/release_flow/git_env.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Cleared before every git spawn: a hook's GIT_DIR beats `git -C`.
+module ReleaseFlow
+  module GitEnv
+    HASH = {
+      "GIT_DIR" => nil,
+      "GIT_WORK_TREE" => nil,
+      "GIT_INDEX_FILE" => nil,
+      "GIT_COMMON_DIR" => nil,
+      "GIT_OBJECT_DIRECTORY" => nil,
+      "GIT_NAMESPACE" => nil,
+      "GIT_CONFIG" => nil,
+      "GIT_CONFIG_GLOBAL" => nil,
+      "GIT_CONFIG_SYSTEM" => nil,
+      "GIT_CONFIG_COUNT" => nil
+    }.freeze
+  end
+end

data/lib/release_flow/github_origin.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module ReleaseFlow
+  # The GitHub repository a checkout's origin names. gh prefers a remote called upstream,
+  # so the flow asks for origin by name instead.
+  module GithubOrigin
+    URL = %r{github\.com[:/](?<repo>[^/\s]+/[^/\s]+?)(?:\.git)?/?\z}
+
+    module_function
+
+    def repo(root)
+      url, status = Open3.capture2(GitEnv::HASH, "git", "-C", root, "config", "--get", "remote.origin.url", err: File::NULL)
+      url.strip[URL, :repo] if status.success?
+    end
+  end
+end

data/lib/release_flow/installer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require "yaml"
+
+module ReleaseFlow
+  # release_flow init: writes the files the flow runs on, keeping any that already exist.
+  class Installer
+    TEMPLATES = File.expand_path("../../templates", __dir__)
+    FILES = {
+      "bin/release" => 0o755,
+      ".github/workflows/next_release.yml" => 0o644,
+      ".github/PULL_REQUEST_TEMPLATE/release.md" => 0o644,
+      "changelog.d/README.md" => 0o644
+    }.freeze
+    CHANGELOG = "# Changelog\n\n#{Changelog::UNRELEASED}"
+
+    def self.start(argv, root:, out: $stdout)
+      raise Error, "usage: release_flow init" unless argv == ["init"]
+
+      new(root, out: out).install
+      0
+    rescue Error => e
+      warn("release_flow: #{e.message}")
+      1
+    end
+
+    def self.render(path, config, ci_name: "CI")
+      ERB.new(File.read(File.join(TEMPLATES, "#{path}.erb")), trim_mode: "-").result_with_hash(config: config, ci_name: ci_name)
+    end
+
+    def initialize(root, out: $stdout)
+      @root = root
+      @out = out
+      @config = Config.load(root)
+    end
+
+    def install
+      ci_name = ci_workflow_name
+      FILES.each { |path, mode| write(path, mode) { self.class.render(path, @config, ci_name: ci_name) } }
+      write("CHANGELOG.md", 0o644) { CHANGELOG }
+      unless File.read(File.join(@root, "CHANGELOG.md")).include?(Changelog::UNRELEASED)
+        @out.puts("  ! CHANGELOG.md has no #{Changelog::UNRELEASED.strip} heading; add one above your first release")
+      end
+      @out.puts(<<~NEXT)
+        Then: add `bin/release check` to #{@config.ci_workflow}, and to start releases on their own,
+        a RELEASE_TOKEN secret and an AUTO_RELEASE variable set to true (#{@config.guide}).
+      NEXT
+    end
+
+    private
+
+    def ci_workflow_name
+      path = File.join(@root, ".github/workflows", @config.ci_workflow)
+      unless File.exist?(path)
+        raise Error, "no .github/workflows/#{@config.ci_workflow}: set ci_workflow in #{FILE} to the workflow that runs your checks"
+      end
+
+      YAML.safe_load_file(path).to_h.fetch("name") { raise Error, "#{@config.ci_workflow} has no name: for the release workflow to wait on" }
+    end
+
+    def write(path, mode)
+      target = File.join(@root, path)
+      return @out.puts("  kept #{path}, which already exists") if File.exist?(target)
+
+      FileUtils.mkdir_p(File.dirname(target))
+      File.write(target, yield)
+      File.chmod(mode, target)
+      @out.puts("  wrote #{path}")
+    end
+  end
+end

data/lib/release_flow/release.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+require "json"
+require "open3"
+require "tmpdir"
+
+# Walks a release from the integration branch to production. Commits through a temporary index,
+# so the checkout and working tree are never touched.
+module ReleaseFlow
+  class Release
+    class Error < ReleaseFlow::Error; end
+
+    CLEAN_GIT_ENV = GitEnv::HASH
+    TEMPLATE = ".github/PULL_REQUEST_TEMPLATE/release.md"
+    SHIP_USAGE = "bin/release ship [<PR> <commit reviewed on staging>]"
+    USAGE = "usage: bin/release prepare | cut | #{SHIP_USAGE.delete_prefix("bin/release ")} | merge-back | check"
+    ONCE_READY = "once its checks pass and any required approval is given"
+    BODY_LIMIT = 60_000
+
+    def initialize(options, root: Dir.pwd, config: nil)
+      @opts = options
+      @root = File.expand_path(root)
+      @config = config || Config.load(@root)
+    end
+
+    def run(command, *args)
+      @repo = GithubOrigin.repo(@root) or raise Error, "origin isn't a GitHub repository, so there's no telling which one to act on"
+      case command
+      when "prepare" then prepare
+      when "cut" then cut
+      when "ship" then ship(*args)
+      when "merge-back" then merge_back_after_hotfix
+      when "check" then check
+      else raise Error, USAGE
+      end
+    end
+
+    def prepare
+      fetch
+      changelog = next_changelog
+      fragments = fragments_at("origin/#{integration}")
+      if (under_way = release_under_way(changelog))
+        return say("#{under_way}, so the next release waits for it.") if @opts[:if_needed]
+
+        raise Error, "#{under_way}: finish that release before starting another"
+      end
+      return say("No changelog entries are waiting on #{integration}, so no release to start.") if @opts[:if_needed] && Changelog.unreleased(changelog, fragments.values).empty?
+
+      name = Changelog.names(@opts.fetch(:today) { Date.today })
+        .find { |n| !tagged?(n) && !template_tags.key?(n) && !branch?("release/#{n}") }
+      say("== Prepare v#{name} in #{@repo} ==")
+      return dry("push changelog/#{name} (CHANGELOG.md naming v#{name}) and queue its PR into #{integration}") if dry_run?
+
+      named = Changelog.name_release(changelog + "\n", name, fragments.values)
+      commit = commit_on("origin/#{integration}", {"CHANGELOG.md" => named, **fragments.transform_values { nil }},
+        message: "The changelog names release #{name}")
+      url = propose("changelog/#{name}", at: commit, base: integration, title: "Changelog for release #{name}",
+        body: "Gathers `changelog.d/` and `[Unreleased]` into v#{name} so `bin/release cut` can cut it.\n", auto_merge: true)
+      say("  → #{url}, merging into #{integration} #{ONCE_READY}")
+      say("Then: bin/release cut, once it has merged.")
+    end
+
+    def cut
+      fetch
+      changelog = next_changelog
+      name = Changelog.named_release(changelog)
+      return say("Nothing to cut: #{integration} names no release waiting to be cut.") if @opts[:if_needed] && !waiting_to_cut?(name)
+      raise Error, "#{integration}'s CHANGELOG.md names no release yet: run bin/release prepare and let its PR merge" unless name
+      raise Error, "v#{name} already shipped: run bin/release prepare for the next one" if shipped?(name)
+
+      branch = "release/#{name}"
+      open = remote_refs.find { |ref| ref.start_with?("refs/heads/release/") && ref != "refs/heads/#{branch}" }
+      raise Error, "#{open.delete_prefix("refs/heads/")} is still open: ship it or delete it before cutting another" if open
+      commit, waiting = cut_point(name)
+      raise Error, "#{production} isn't in #{integration} yet: merge the open merge-back PR first" unless ancestor?("origin/#{production}", commit)
+      require_passing_ci(commit, name)
+
+      say("== Cut #{branch} in #{@repo} ==")
+      say("  at #{commit[0, 7]}; #{waiting} later commit#{"s" unless waiting == 1} on next wait#{"s" if waiting == 1} for the next release") if waiting.positive?
+      return dry("push #{branch} at #{commit[0, 7]} and open its PR into #{production}") if dry_run?
+
+      url = propose(branch, at: commit, base: production, title: "Release #{name}",
+        body: release_body(branch, Changelog.section(git("show", "#{commit}:CHANGELOG.md"), name)))
+      say("  → #{url}")
+      say("Then: review it on staging, and run bin/release ship.")
+    end
+
+    def ship(pr = nil, sha = nil)
+      raise Error, "usage: #{SHIP_USAGE}" if pr.nil? != sha.nil? || (sha && !sha.match?(/\A\h{7,40}\z/))
+
+      pr, sha, found = waiting_release unless pr
+      info = pr_info(pr)
+      name = release_name(info)
+      head = info["headRefOid"]
+      say("== Ship v#{name} in #{@repo} ==")
+      say("  PR ##{pr}, #{info["headRefName"]} into #{production}, at #{head[0, 7]}: #{found}") if found
+      return dry("merge PR #{pr} at #{head[0, 7]}, publish release v#{name}, and queue the merge-back into #{integration}") if dry_run?
+      return say("Not shipped.") if found && !Candidate.confirmed?(pr, head)
+      raise Error, "PR #{pr} #{(info["state"] == "MERGED") ? "was merged" : "is"} at #{head[0, 7]}, not #{sha}, the commit reviewed on staging" unless head.start_with?(sha)
+
+      if info["state"] == "MERGED"
+        say("  ✓ PR #{pr} already merged")
+      else
+        gh("pr", "merge", pr, "--merge", "--match-head-commit", head)
+        info = pr_info(pr)
+      end
+      publish(name, info.dig("mergeCommit", "oid"))
+      merge_back(name, after: "release #{name}")
+    end
+
+    def merge_back_after_hotfix
+      fetch
+      merge_back("#{production}-#{git("rev-parse", "--short=7", "origin/#{production}")}", after: "a hotfix")
+    end
+
+    def merge_back(label, after:)
+      fetch
+      branch = "merge-back/#{label}"
+      say("== Merge #{production} back into #{integration} in #{@repo} ==")
+      return dry("push #{branch} at #{production} and queue its PR into #{integration}") if dry_run?
+
+      url = propose(branch, at: git("rev-parse", "origin/#{production}"), base: integration, title: "Merge #{production} back into #{integration} after #{after}",
+        body: "Brings `#{production}` back into `#{integration}` after #{after}. Merge with a merge commit.\n", auto_merge: true)
+      out, updated = gh("api", "-X", "PUT", "repos/{owner}/{repo}/pulls/#{url.split("/").last}/update-branch", status: true)
+      already_current = out.include?("no new commits on the base branch")
+      say("  ! GitHub couldn't bring #{url} up to date; press Update branch on it") unless updated || already_current
+      say("  → #{url}, merging into #{integration} #{ONCE_READY}")
+    end
+
+    private
+
+    def check
+      tagged = git("tag", "--list", "v*").lines(chomp: true).filter_map { |tag| tag[/\Av(#{Changelog::NAME})\z/o, 1] }
+      changed = Changelog.changed_releases(git("show", "HEAD:CHANGELOG.md"), tagged.to_h { |name| [name, git("show", "v#{name}:CHANGELOG.md")] })
+      raise Error, changed.join("\n\n") if changed.any?
+
+      say("Shipped release notes are unchanged.")
+    end
+
+    def dry_run? = @opts[:dry_run]
+    def say(msg) = puts(msg)
+    def dry(msg) = say("  [dry-run] would #{msg}")
+    def next_changelog = git("show", "origin/#{integration}:CHANGELOG.md")
+    def integration = @config.integration_branch
+    def production = @config.production_branch
+
+    def fragments_at(commit)
+      git("ls-tree", "--name-only", commit, "#{Changelog::FRAGMENTS}/").lines(chomp: true)
+        .select { |path| Changelog.fragment?(path) }.to_h { |path| [path, git("show", "#{commit}:#{path}")] }
+    end
+
+    def tagged?(name) = remote_refs.include?("refs/tags/v#{name}")
+    def branch?(name) = remote_refs.include?("refs/heads/#{name}")
+    def remote_refs = @remote_refs ||= git("ls-remote", "--heads", "--tags", "origin").lines.map { |l| l.split.last }
+
+    # A fork's changelog carries the template's releases, which only the template tagged.
+    def shipped?(name) = tagged?(name) || template_tags[name]&.then { |commit| ancestor?(commit, "origin/#{integration}") }
+
+    def template_tags
+      @template_tags ||= if (template = template_repo)
+        out, err, status = Open3.capture3(CLEAN_GIT_ENV, "git", "-C", @root, "ls-remote", "--tags", "https://github.com/#{template}.git")
+        raise Error, "can't read the tags of #{template}, the template this repository forks: #{err.strip}" unless status.success?
+
+        out.lines.to_h { |line| line.split.reverse }.transform_keys { |ref| ref[%r{\Arefs/tags/v(.+?)(?:\^\{\})?\z}, 1] }
+      else
+        {}
+      end
+    end
+
+    def template_repo = @config.template
+    def pr_info(pr) = JSON.parse(gh("pr", "view", pr, "--json", "state,headRefName,headRefOid,baseRefName,mergeCommit"))
+
+    def release_under_way(changelog)
+      named = Changelog.named_release(changelog)
+      return "v#{named} is named but hasn't shipped" if named && !shipped?(named)
+
+      changelog_branch = remote_refs.find { |ref| ref.start_with?("refs/heads/changelog/") }
+      "#{changelog_branch.delete_prefix("refs/heads/")} hasn't merged" if changelog_branch
+    end
+
+    def waiting_to_cut?(name) = name && !shipped?(name) && !branch?("release/#{name}")
+
+    def require_passing_ci(commit, name)
+      runs = JSON.parse(gh("run", "list", "--workflow", @config.ci_workflow, "--commit", commit, "--event", "push", "--json", "status,conclusion"))
+      unless runs.any? && runs.all? { |run| run["status"] == "completed" }
+        raise Error, "CI hasn't passed on #{commit[0, 7]} yet: run cut again once it has"
+      end
+      return if runs.all? { |run| run["conclusion"] == "success" }
+
+      raise Error, "CI failed on #{commit[0, 7]}, where v#{name} would be cut. If it was a flake, re-run its failed jobs; otherwise " \
+                   "fix it by a PR into #{integration}, its changelog line under ## v#{name}. Then cut again (AUTO_RELEASE does once CI passes)"
+    end
+
+    def fetch
+      @remote_refs = nil
+      git("fetch", "-q", "--prune", "--tags", "origin")
+    end
+
+    def cut_point(name)
+      since_named = []
+      git("rev-list", "--first-parent", "origin/#{integration}").each_line(chomp: true) do |commit|
+        changelog = git("show", "#{commit}:CHANGELOG.md")
+        break unless Changelog.named_release(changelog) == name
+
+        since_named << [commit, Changelog.unreleased(changelog, fragments_at(commit).values)]
+      end
+      later = since_named.index { |_, unreleased| unreleased.empty? }
+      return [since_named[later].first, later] if later
+
+      raise Error, "these changelog entries landed before v#{name} was named, so they'd ship without a line in " \
+                   "What ships:\n#{since_named.first.last.join("\n")}\nMove them under ## v#{name} by a PR into #{integration}, then run cut again"
+    end
+
+    def waiting_release
+      pr = Candidate.waiting(JSON.parse(gh("pr", "list", "--base", production, "--state", "all", "--limit", "30", "--json", "number,headRefName,state,headRefOid")), usage: SHIP_USAGE) { |name| tagged?(name) }
+      runs, listed = gh("run", "list", "--workflow", @config.staging_workflow, "--branch", pr["headRefName"], "--event", "push",
+        "--json", "headSha,conclusion", status: true)
+      [pr["number"].to_s, pr["headRefOid"], Candidate.found(pr, listed ? JSON.parse(runs) : [])]
+    end
+
+    def release_name(info)
+      name = info["headRefName"].to_s[Candidate::BRANCH, 1]
+      raise Error, "that PR is not a release/* branch into #{production}" unless name && info["baseRefName"] == production
+
+      name
+    end
+
+    def publish(name, commit)
+      raise Error, "GitHub reports no merge commit for release #{name}; check its PR" unless commit
+
+      fetch
+      return say("  ✓ v#{name} already published") if tagged?(name)
+
+      notes = fit(Changelog.section(git("show", "#{commit}:CHANGELOG.md"), name).to_s,
+        BODY_LIMIT, "the full list is in CHANGELOG.md at v#{name}")
+      gh("release", "create", "v#{name}", "--target", commit, "--title", "Release #{name}", "--notes-file", "-", stdin: notes)
+      say("  → merged and published v#{name}")
+    end
+
+    # Pushes the branch unless a stopped run already did, then opens its PR or finds the open one.
+    def propose(branch, at:, base:, title:, body:, auto_merge: false)
+      push(at, branch) unless branch?(branch)
+      url, created = gh("pr", "create", "--base", base, "--head", branch, "--title", title, "--body-file", "-",
+        stdin: body, status: true)
+      raise Error, "gh pr create failed: #{url}" unless created || url.include?("already exists")
+
+      url = gh("pr", "view", branch, "--json", "url", "--jq", ".url") unless created
+      gh("pr", "merge", url, "--auto", "--merge") if auto_merge
+      url
+    end
+
+    # A commit already on origin passed CI's required checks on its way there; the hook adds nothing.
+    def push(at, branch)
+      ref = "#{at}:refs/heads/#{branch}"
+      return git("push", "-q", "--no-verify", "origin", ref) unless git("for-each-ref", "--contains", at, "refs/remotes/origin").empty?
+
+      say("  pushing #{branch}; the pre-push hook checks it first, which can take a few minutes") if pre_push_hook?
+      out, err, status = Open3.capture3(CLEAN_GIT_ENV, "git", "-C", @root, "push", "-q", "origin", ref)
+      return if status.success?
+
+      output = "#{out}#{err}".gsub(/\e\[[\d;]*m/, "")
+      log = File.join(@root, "tmp/release-push.log")
+      FileUtils.mkdir_p(File.dirname(log))
+      File.write(log, output)
+      raise Error, "git push of #{branch} failed. The end of what it said:\n#{output.lines.last(15).join.rstrip}\n" \
+                   "All of it is in #{log.delete_prefix("#{@root}/")}"
+    end
+
+    def pre_push_hook? = File.executable?(File.expand_path(git("rev-parse", "--git-path", "hooks/pre-push"), @root))
+
+    def release_body(branch, section)
+      template = File.read(File.join(@root, TEMPLATE)).sub("`release/YYYY.MM.DD`", "`#{branch}`")
+      room = BODY_LIMIT - template.length
+      template.sub(/(## What ships\n\n)<!--.*?-->/m) { "#{$1}#{fit(section, room, "the full list is in CHANGELOG.md on #{branch}")}" }
+    end
+
+    def fit(text, limit, rest)
+      note = "\n\n…and more: #{rest}."
+      return text if text.length <= limit
+
+      text[0, limit - note.length].sub(/\n[^\n]*\z/, "") + note
+    end
+
+    def commit_on(parent, files, message:)
+      Dir.mktmpdir do |dir|
+        env = CLEAN_GIT_ENV.merge("GIT_INDEX_FILE" => File.join(dir, "index"))
+        git("read-tree", parent, env: env)
+        files.each do |path, content|
+          next git("update-index", "--force-remove", path, env: env) if content.nil?
+
+          git("update-index", "--add", "--cacheinfo", "100644,#{git("hash-object", "-w", "--stdin", stdin: content)},#{path}", env: env)
+        end
+        git("commit-tree", git("write-tree", env: env), "-p", parent, "-m", message)
+      end
+    end
+
+    def ancestor?(older, newer)
+      _, _, status = Open3.capture3(CLEAN_GIT_ENV, "git", "-C", @root, "merge-base", "--is-ancestor", older, newer)
+      status.success?
+    end
+
+    def git(*args, env: CLEAN_GIT_ENV, stdin: nil)
+      out, err, status = Open3.capture3(env, "git", "-C", @root, *args, stdin_data: stdin.to_s)
+      raise Error, "git #{args.first} failed: #{err.strip}" unless status.success?
+
+      out.strip
+    end
+
+    def gh(*args, stdin: nil, status: false)
+      out, err, result = Open3.capture3(CLEAN_GIT_ENV.merge("GH_REPO" => @repo), "gh", *args, stdin_data: stdin.to_s, chdir: @root)
+      return [result.success? ? out.strip : err.strip, result.success?] if status
+      raise Error, "gh #{args.first(2).join(" ")} failed: #{err.strip}" unless result.success?
+
+      out.strip
+    rescue Errno::ENOENT
+      raise Error, "bin/release needs the GitHub CLI (gh), signed in"
+    end
+  end
+end

data/lib/release_flow/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ReleaseFlow
+  VERSION = "0.1.0"
+end

data/lib/release_flow.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ReleaseFlow
+  class Error < StandardError; end
+end
+
+require_relative "release_flow/version"
+require_relative "release_flow/git_env"
+require_relative "release_flow/config"
+require_relative "release_flow/github_origin"
+require_relative "release_flow/changelog"
+require_relative "release_flow/candidate"
+require_relative "release_flow/release"
+require_relative "release_flow/installer"
+require_relative "release_flow/cli"

data/templates/.github/PULL_REQUEST_TEMPLATE/release.md.erb

@@ -0,0 +1,22 @@
+<!-- A release/<name> branch into <%= config.production_branch %>. The guide: <%= config.guide %> -->
+
+## Release
+
+- Branch: `release/YYYY.MM.DD`
+- Commit reviewed on staging: <!-- the full SHA from the staging deployment record -->
+
+## What ships
+
+<!-- bin/release cut fills this with the release's CHANGELOG.md section. -->
+
+## Held back
+
+<!-- PRs reverted on this branch, each with its revert commit, so <%= config.integration_branch %> can restore them after the merge-back. Delete if none. -->
+
+## Ship it
+
+The merge button doesn't check what was reviewed. This does: it finds this PR and the commit staging last deployed, asks before shipping, refuses if the branch moved since, then publishes the release and merges `<%= config.production_branch %>` back into `<%= config.integration_branch %>`:
+
+```bash
+bin/release ship
+```

data/templates/.github/workflows/next_release.yml.erb

@@ -0,0 +1,98 @@
+name: Next release
+
+# Starts the next release when staging is free: <%= config.guide %>
+on:
+  pull_request:
+    types: [ closed ]
+    branches: [ <%= config.integration_branch %> ]
+  # Safe: cut acts only on a push to <%= config.integration_branch %>, checks it out by name, and reads only the run's event and result.
+  workflow_run: # jactionlint ignore=dangerous-triggers
+    workflows: [ <%= ci_name %> ]
+    types: [ completed ]
+    branches: [ <%= config.integration_branch %> ]
+
+permissions:
+  contents: read
+
+jobs:
+  prepare:
+    if: >-
+      vars.AUTO_RELEASE == 'true' &&
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.merged &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    concurrency:
+      group: next-release-prepare
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Require the release token
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          if [ -z "$RELEASE_TOKEN" ]; then
+            echo "::error title=RELEASE_TOKEN isn't set::AUTO_RELEASE is on, but this repository has no RELEASE_TOKEN secret, so no release can start. Add one as <%= config.guide %> says under \"Set up the release token\", or set AUTO_RELEASE to false."
+            exit 1
+          fi
+
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: <%= config.integration_branch %>
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
+        with:
+          bundler-cache: true
+
+      - name: Name the next release
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          gh auth setup-git
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          bin/release prepare --if-needed
+
+  cut:
+    if: >-
+      vars.AUTO_RELEASE == 'true' &&
+      github.event_name == 'workflow_run' &&
+      github.event.workflow_run.event == 'push' &&
+      (github.event.workflow_run.conclusion == 'success' || github.event.workflow_run.conclusion == 'failure')
+    concurrency:
+      group: next-release-cut
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Require the release token
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          if [ -z "$RELEASE_TOKEN" ]; then
+            echo "::error title=RELEASE_TOKEN isn't set::AUTO_RELEASE is on, but this repository has no RELEASE_TOKEN secret, so no release can start. Add one as <%= config.guide %> says under \"Set up the release token\", or set AUTO_RELEASE to false."
+            exit 1
+          fi
+
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: <%= config.integration_branch %>
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
+        with:
+          bundler-cache: true
+
+      - name: Cut the release
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          gh auth setup-git
+          bin/release cut --if-needed

data/templates/bin/release.erb

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Walks a release from <%= config.integration_branch %> to <%= config.production_branch %>: <%= config.guide %>
+root = File.expand_path("..", __dir__)
+require "bundler/setup" if File.exist?(File.join(root, "Gemfile"))
+require "release_flow"
+
+exit ReleaseFlow::CLI.start(ARGV, root: root)

data/templates/changelog.d/README.md.erb

@@ -0,0 +1,24 @@
+# Changelog entries
+
+Each pull request adds its changelog entry here as a file of its own, such as
+`changelog.d/fix-login.md`. Two PRs never edit the same lines, so their
+entries can't conflict.
+
+Write one line saying what changed for someone using the app, under a heading
+if one fits:
+
+```markdown
+### Fixed
+
+- Signing in no longer loops after a password reset.
+```
+
+An entry without a heading goes under "Changed". `bin/release prepare` gathers
+every file here into the release's section of `CHANGELOG.md` and deletes
+them; this README stays.
+
+A fix for the release under review is the exception: its line goes under that
+release's `## v<name>` section in `CHANGELOG.md`, since a file here would wait
+for the next release.
+
+The full flow: <%= config.guide %>

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: release_flow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dave Chmura
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A next → release/<name> → main release flow on git and the GitHub CLI.
+  Changelog entries live in changelog.d/ so they never conflict; a release is named,
+  cut to staging, reviewed, and shipped as exactly the commit staging ran, tagged
+  with its notes.
+email:
+- dschmura@humbledaisy.com
+executables:
+- release_flow
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/release_flow
+- lib/release_flow.rb
+- lib/release_flow/candidate.rb
+- lib/release_flow/changelog.rb
+- lib/release_flow/cli.rb
+- lib/release_flow/config.rb
+- lib/release_flow/git_env.rb
+- lib/release_flow/github_origin.rb
+- lib/release_flow/installer.rb
+- lib/release_flow/release.rb
+- lib/release_flow/version.rb
+- templates/.github/PULL_REQUEST_TEMPLATE/release.md.erb
+- templates/.github/workflows/next_release.yml.erb
+- templates/bin/release.erb
+- templates/changelog.d/README.md.erb
+homepage: https://github.com/dschmura/release_flow
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dschmura/release_flow
+  changelog_uri: https://github.com/dschmura/release_flow/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Release a GitHub repository through staging review: each release is the
+  commit someone checked'
+test_files: []