Generate reviewable patches for release setup updates

Author: samuel-williams-shopify

.github/releasing.md

@@ -13,3 +13,5 @@ If a publishing job fails, use **Re-run all jobs** on that same workflow run, or
 Verify both the downloaded gem and `release.json` with `gh attestation verify`, enforcing the publishing workflow's certificate identity and default branch ref. Then check the signed receipt's source commit and gem digest; follow the companion gem's setup guide for the complete commands. `--source-digest` checks the workflow revision, which can differ from the release commit. Release assets include the gem, RubyGems Sigstore bundle, GitHub provenance bundle, and signed source/digest receipt.
 
 The initial implementation supports public repositories, a single gemspec, stable patch/minor/major versions, and merge/squash commits. Keep rebase merges and merge queues disabled. Generation hooks must be repeatable from the same source and version. Run setup and account recovery checks before enabling publishing; see the companion gem's setup guide.
+
+After upgrading `bake-gem-github`, run `bundle exec bake gem:github:setup:update` to write `pkg/release-setup.patch`. Review every hunk, including differences from local customizations, then apply the desired changes and open a PR. The task does not modify repository files or remote settings.

bake/gem/github/setup.rb

@@ -13,3 +13,9 @@ def apply
 	require_relative "../../../lib/bake/gem/github/project"
 	Bake::Gem::GitHub::Project.new(context.root).apply
 end
+
+# Write a reviewable update patch using config/release.yaml and the installed templates.
+def update
+	require_relative "../../../lib/bake/gem/github/setup"
+	Bake::Gem::GitHub::Setup.new(context.root).update
+end

context/getting-started.md

@@ -18,7 +18,19 @@ bundle exec bake agent:context:install
 bundle exec bake gem:github:setup:plan
 ```
 
-Setup adds three pinned workflows, `config/release.yaml`, native ruleset payloads, and `.github/releasing.md`. Identical reruns do nothing; conflicting existing files stop before any file is written. For later policy changes, edit the configuration and review the generated workflow/policy changes explicitly. Setup does not replace other publishers: remove conflicting release workflows during migration.
+Setup adds three pinned workflows, `config/release.yaml`, native ruleset payloads, and `.github/releasing.md`. Identical reruns do nothing; conflicting existing files stop before any file is written. Setup does not replace other publishers: remove conflicting release workflows during migration.
+
+To adopt template fixes after upgrading the gem, or change policy, edit `config/release.yaml` as needed and generate an update patch:
+
+``` bash
+bundle exec bake gem:github:setup:update
+cat pkg/release-setup.patch
+git apply --check pkg/release-setup.patch
+git apply pkg/release-setup.patch
+git diff
+```
+
+The task leaves repository files untouched and writes only `pkg/release-setup.patch`. The patch proposes the current templates, policy payloads, configuration formatting, and maintainer instructions. It includes any differences from repository customizations: inspect every hunk, remove unwanted hunks or apply selected changes manually, then commit the result through a PR. Repeating the task after applying all changes produces an empty patch. Intentionally retained customizations remain visible on later updates. Apply remote rulesets only after the corresponding workflows are merged and their checks are running.
 
 The default is two approvals with explicit administrator bypass, dismissed stale reviews, approval of the last push, strict up-to-date CI, and immutable default-branch history/release tags. These branch rules affect **all PRs** into the default branch. Ordinary administrator reviews count as one review. A human who dispatches a bot-authored PR is not its author under GitHub's native rules.
 

guides/getting-started/readme.md

@@ -18,7 +18,19 @@ bundle exec bake agent:context:install
 bundle exec bake gem:github:setup:plan
 ```
 
-Setup adds three pinned workflows, `config/release.yaml`, native ruleset payloads, and `.github/releasing.md`. Identical reruns do nothing; conflicting existing files stop before any file is written. For later policy changes, edit the configuration and review the generated workflow/policy changes explicitly. Setup does not replace other publishers: remove conflicting release workflows during migration.
+Setup adds three pinned workflows, `config/release.yaml`, native ruleset payloads, and `.github/releasing.md`. Identical reruns do nothing; conflicting existing files stop before any file is written. Setup does not replace other publishers: remove conflicting release workflows during migration.
+
+To adopt template fixes after upgrading the gem, or change policy, edit `config/release.yaml` as needed and generate an update patch:
+
+``` bash
+bundle exec bake gem:github:setup:update
+cat pkg/release-setup.patch
+git apply --check pkg/release-setup.patch
+git apply pkg/release-setup.patch
+git diff
+```
+
+The task leaves repository files untouched and writes only `pkg/release-setup.patch`. The patch proposes the current templates, policy payloads, configuration formatting, and maintainer instructions. It includes any differences from repository customizations: inspect every hunk, remove unwanted hunks or apply selected changes manually, then commit the result through a PR. Repeating the task after applying all changes produces an empty patch. Intentionally retained customizations remain visible on later updates. Apply remote rulesets only after the corresponding workflows are merged and their checks are running.
 
 The default is two approvals with explicit administrator bypass, dismissed stale reviews, approval of the last push, strict up-to-date CI, and immutable default-branch history/release tags. These branch rules affect **all PRs** into the default branch. Ordinary administrator reviews count as one review. A human who dispatches a bot-authored PR is not its author under GitHub's native rules.
 

lib/bake/gem/github/setup.rb

@@ -7,6 +7,7 @@
 require "yaml"
 require "json"
 require "fileutils"
+require "tempfile"
 
 module Bake
 	module Gem
@@ -25,15 +26,7 @@ def generate(repository:, branch: "main", checks:, approvals: 2, signing: File.f
 					raise "Select the required CI check names." if checks.empty?
 					raise "Review count must be between 1 and 6." unless (1..6).include?(approvals)
 					config = {"schema" => 1, "repository" => repository, "branch" => branch, "checks" => (checks + ["Release validation"]).uniq, "approvals" => approvals, "signing" => signing, "ruby" => ruby, "environment" => "rubygems"}
-					templates = File.expand_path("../../../../templates", __dir__)
-					files = {"config/release.yaml" => YAML.dump(config)}
-					Dir.glob("*.erb", base: templates).each do |name|
-						files[".github/workflows/#{name.delete_suffix('.erb')}"] = ERB.new(File.read(File.join(templates, name)), trim_mode: "-").result(binding)
-					end
-					self.class.rules(config).each do |name, rule|
-						files[".github/release-rules/#{name}.json"] = JSON.pretty_generate(rule) + "\n"
-					end
-					files[".github/releasing.md"] = File.read(File.join(templates, "releasing.md"))
+					files = render(config)
 					conflicts = files.keys.select{|name| File.exist?(File.join(@root, name)) && File.read(File.join(@root, name)) != files[name]}
 					raise "Existing files differ; review them before regenerating: #{conflicts.join(', ')}" unless conflicts.empty?
 					files.each do |name, content|
@@ -44,6 +37,27 @@ def generate(repository:, branch: "main", checks:, approvals: 2, signing: File.f
 					files.keys
 				end
 
+				# Write a patch proposing updates from the existing configuration, without replacing repository files.
+				def update
+					config = YAML.safe_load_file(File.join(@root, "config/release.yaml"))
+					raise "Unsupported release configuration." unless config.fetch("schema") == 1
+					patch = render(config).map do |name, content|
+						path = File.join(@root, name)
+						Tempfile.create("release-update") do |file|
+							file.write(content)
+							file.flush
+							exists = File.exist?(path)
+							diff = IO.popen(["diff", "-u", "--label", exists ? "a/#{name}" : "/dev/null", "--label", "b/#{name}", exists ? path : File::NULL, file.path], &:read)
+							raise "Unable to compare #{name}." unless [0, 1].include?($?.exitstatus)
+							diff
+						end
+					end.join
+					path = File.join(@root, "pkg/release-setup.patch")
+					FileUtils.mkdir_p(File.dirname(path))
+					File.write(path, patch)
+					path
+				end
+				
 				# Native review/check rules allow PR-only administrator bypass; history rules have no bypass.
 				def self.rules(config)
 					conditions = {ref_name: {include: ["refs/heads/#{config.fetch('branch')}"], exclude: []}}
@@ -56,6 +70,24 @@ def self.rules(config)
 						"tags" => {name: "Gem release tags", target: "tag", enforcement: "active", bypass_actors: [], conditions: {ref_name: {include: ["refs/tags/v*"], exclude: []}}, rules: [{type: "deletion"}, {type: "non_fast_forward"}]}
 					}
 				end
+				
+				private
+				
+				def render(config)
+					branch = config.fetch("branch")
+					ruby = config.fetch("ruby")
+					signing = config.fetch("signing")
+					templates = File.expand_path("../../../../templates", __dir__)
+					files = {"config/release.yaml" => YAML.dump(config)}
+					Dir.glob("*.erb", base: templates).each do |name|
+						files[".github/workflows/#{name.delete_suffix('.erb')}"] = ERB.new(File.read(File.join(templates, name)), trim_mode: "-").result(binding)
+					end
+					self.class.rules(config).each do |name, rule|
+						files[".github/release-rules/#{name}.json"] = JSON.pretty_generate(rule) + "\n"
+					end
+					files[".github/releasing.md"] = File.read(File.join(templates, "releasing.md"))
+					files
+				end
 			end
 		end
 	end

releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Generate reviewable setup updates with `gem:github:setup:update`.
+
 ## v0.0.5
 
   - Preserve and recover release files even when GitHub's release list is stale.

templates/releasing.md

@@ -13,3 +13,5 @@ If a publishing job fails, use **Re-run all jobs** on that same workflow run, or
 Verify both the downloaded gem and `release.json` with `gh attestation verify`, enforcing the publishing workflow's certificate identity and default branch ref. Then check the signed receipt's source commit and gem digest; follow the companion gem's setup guide for the complete commands. `--source-digest` checks the workflow revision, which can differ from the release commit. Release assets include the gem, RubyGems Sigstore bundle, GitHub provenance bundle, and signed source/digest receipt.
 
 The initial implementation supports public repositories, a single gemspec, stable patch/minor/major versions, and merge/squash commits. Keep rebase merges and merge queues disabled. Generation hooks must be repeatable from the same source and version. Run setup and account recovery checks before enabling publishing; see the companion gem's setup guide.
+
+After upgrading `bake-gem-github`, run `bundle exec bake gem:github:setup:update` to write `pkg/release-setup.patch`. Review every hunk, including differences from local customizations, then apply the desired changes and open a PR. The task does not modify repository files or remote settings.

test/setup_update.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "bake/gem/github/setup"
+require "bake/context"
+require "sus/fixtures/temporary_directory_context"
+
+describe Bake::Gem::GitHub::Setup do
+	include Sus::Fixtures::TemporaryDirectoryContext
+	
+	let(:setup) {subject.new(root)}
+	
+	before do
+		setup.generate(repository: "socketry/example", checks: ["Tests"], signing: false)
+	end
+	
+	it "proposes configuration changes and customizations without overwriting them" do
+		path = File.join(root, "config/release.yaml")
+		config = YAML.safe_load_file(path)
+		config["approvals"] = 3
+		config["checks"] << "New check"
+		File.write(path, YAML.dump(config))
+		workflow = File.join(root, ".github/workflows/release-validate.yaml")
+		File.write(workflow, "# Custom workflow\n" + File.read(workflow))
+		before = Dir.glob("{config,.github}/**/*", File::FNM_DOTMATCH, base: root).select{|name| File.file?(File.join(root, name))}.to_h{|name| [name, File.read(File.join(root, name))]}
+		registry = Bake::Registry::Aggregate.new
+		registry.append_path(File.expand_path("..", __dir__))
+		patch = Bake::Context.new(registry, root).call("gem:github:setup:update")
+		expect(File.read(patch)).to be(:include?, "-# Custom workflow")
+		expect(File.read(patch)).to be(:include?, '+            "context": "New check"')
+		before.each do |name, content|
+			expect(File.read(File.join(root, name))).to be == content
+		end
+		expect(system("git", "apply", "--check", patch, chdir: root)).to be == true
+		expect(system("git", "apply", patch, chdir: root)).to be == true
+		expect(File.read(setup.update)).to be == ""
+		expect(YAML.safe_load_file(path)).to be == config
+	end
+	
+	it "restores missing generated files through the patch" do
+		path = File.join(root, ".github/releasing.md")
+		original = File.read(path)
+		File.unlink(path)
+		patch = setup.update
+		expect(File.exist?(path)).to be == false
+		expect(system("git", "apply", patch, chdir: root)).to be == true
+		expect(File.read(path)).to be == original
+		expect(File.read(setup.update)).to be == ""
+	end
+	
+	it "refuses unsupported configuration schemas" do
+		File.write(File.join(root, "config/release.yaml"), YAML.dump("schema" => 2))
+		expect{setup.update}.to raise_exception(RuntimeError, message: be =~ /Unsupported release configuration/)
+	end
+end