bake-gem-github 0.2.0 → 0.3.0

data/lib/bake/gem/github/setup.rb

@@ -18,66 +18,149 @@ module Bake
 					@root = File.expand_path(root)
 				end
 				
-				# Generate workflows, policy payloads, and maintainer instructions. Refuse conflicting existing files.
-				def generate(repository:, branch: "main", checks:, approvals: 2, signing: File.file?(File.join(@root, "release.cert")), ruby: "3.4")
+				# Generate workflows, policy payloads, and configuration. Refuse conflicting existing files.
+				# @parameter repository [String] The canonical GitHub owner and repository name.
+				# @parameter branch [String] The default branch receiving release PRs.
+				# @parameter checks [Array(String)] Required CI job names; release validation is added automatically.
+				# @parameter approvals [Integer] Required approvals, between one and six.
+				# @parameter reviewers [Array(String) | Nil] Publishing environment reviewers, as user logins or organization/team names. Nil leaves environment settings unmanaged.
+				# @parameter signing [Boolean] Whether publishing requires the certificate and matching private key.
+				# @parameter ruby [String] The Ruby version used by release workflows.
+				# @returns [Array(String)] Generated paths relative to the repository root.
+				# @raises [RuntimeError] If configuration is invalid or an existing generated file differs.
+				def generate(repository:, branch: "main", checks:, approvals: 2, reviewers: nil, signing: File.file?(File.join(@root, "release.cert")), ruby: "3.4")
 					raise "Expected owner/repository." unless repository.match?(/\A[\w.-]+\/[\w.-]+\z/)
 					raise "Unsupported branch name." unless branch.match?(/\A[\w.\/-]+\z/)
 					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"}
+					
+					config = {
+						"schema" => 1,
+						"repository" => repository,
+						"branch" => branch,
+						"checks" => (checks + ["Release validation"]).uniq,
+						"approvals" => approvals,
+						"signing" => signing,
+						"ruby" => ruby,
+						"environment" => "rubygems",
+					}
+					config["reviewers"] = reviewers unless reviewers.nil?
+					
 					files = render(config)
-					conflicts = files.keys.select{|name| File.exist?(File.join(@root, name)) && File.read(File.join(@root, name)) != files[name]}
+					conflicts = files.keys.select do |name|
+						path = File.join(@root, name)
+						File.exist?(path) && File.read(path) != files[name]
+					end
+					
 					raise "Existing files differ; review them before regenerating: #{conflicts.join(', ')}" unless conflicts.empty?
+					
 					write(files)
-					files.keys
+					
+					return files.keys
 				end
 				
 				# Update generated files in the working tree using the existing configuration; return changed paths.
+				# @returns [Array(String)] Changed paths relative to the repository root.
+				# @raises [RuntimeError] If the configuration schema is unsupported.
 				def update
 					config = YAML.safe_load_file(File.join(@root, "config/release.yaml"))
 					raise "Unsupported release configuration." unless config.fetch("schema") == 1
-					write(render(config))
+					
+					return write(render(config))
 				end
 				
 				# Native review/check rules allow PR-only administrator bypass; history rules have no bypass.
+				# @parameter config [Hash] Release configuration with string keys: `branch`, `approvals`, and `checks`.
+				# @returns [Hash] Ruleset payloads keyed by `reviews`, `checks`, `history`, and `tags`.
 				def self.rules(config)
 					conditions = {ref_name: {include: ["refs/heads/#{config.fetch('branch')}"], exclude: []}}
 					common = {target: "branch", enforcement: "active", conditions: conditions}
 					bypass = [{actor_id: 5, actor_type: "RepositoryRole", bypass_mode: "pull_request"}]
-					{
-						"reviews" => common.merge(name: "Gem release reviews", bypass_actors: bypass, rules: [{type: "pull_request", parameters: {required_approving_review_count: config.fetch("approvals"), dismiss_stale_reviews_on_push: true, require_last_push_approval: true, required_review_thread_resolution: true, require_code_owner_review: false, allowed_merge_methods: ["merge", "squash"]}}]),
-						"checks" => common.merge(name: "Gem release checks", bypass_actors: bypass, rules: [{type: "required_status_checks", parameters: {strict_required_status_checks_policy: true, do_not_enforce_on_create: false, required_status_checks: config.fetch("checks").map{|name| {context: name}}}}]),
-						"history" => common.merge(name: "Gem release history", bypass_actors: [], rules: [{type: "deletion"}, {type: "non_fast_forward"}]),
-						"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"}]}
+					
+					return {
+						"reviews" => common.merge(
+							name: "Gem release reviews",
+							bypass_actors: bypass,
+							rules: [{
+								type: "pull_request",
+								parameters: {
+									required_approving_review_count: config.fetch("approvals"),
+									dismiss_stale_reviews_on_push: true,
+									require_last_push_approval: true,
+									required_review_thread_resolution: true,
+									require_code_owner_review: false,
+									allowed_merge_methods: ["merge", "squash"],
+								},
+							}],
+						),
+						"checks" => common.merge(
+							name: "Gem release checks",
+							bypass_actors: bypass,
+							rules: [{
+								type: "required_status_checks",
+								parameters: {
+									strict_required_status_checks_policy: true,
+									do_not_enforce_on_create: false,
+									required_status_checks: config.fetch("checks").map{|name| {context: name}},
+								},
+							}],
+						),
+						"history" => common.merge(
+							name: "Gem release history",
+							bypass_actors: [],
+							rules: [{type: "deletion"}, {type: "non_fast_forward"}],
+						),
+						"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
 				
+				# Validate an explicit list of publishing environment reviewers.
+				# @parameter reviewers [Array(String)] One to six user logins or organization/team names.
+				# @raises [ArgumentError] If the list is empty, too long, or contains invalid names.
+				def self.validate_reviewers(reviewers)
+					unless reviewers.is_a?(Array) && (1..6).include?(reviewers.size) && reviewers.all?{|name| name.is_a?(String) && name.match?(/\A[\w-]+(?:\/[\w-]+)?\z/)}
+						raise ArgumentError, "Specify one to six environment reviewers as user logins or organization/team names."
+					end
+				end
+				
 				private
 				
 				def write(files)
 					files.filter_map do |name, content|
 						path = File.join(@root, name)
 						next if File.exist?(path) && File.read(path) == content
+						
 						FileUtils.mkdir_p(File.dirname(path))
 						File.write(path, content)
+						
 						name
 					end
 				end
 				
 				def render(config)
+					self.class.validate_reviewers(config["reviewers"]) if config.key?("reviewers")
 					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
+					
+					return files
 				end
 			end
 		end

data/lib/bake/gem/github/version.rb

@@ -9,7 +9,7 @@ module Bake
 	module Gem
 		# GitHub pull request and release orchestration for bake-gem.
 		module GitHub
-			VERSION = "0.2.0"
+			VERSION = "0.3.0"
 		end
 	end
 end

data/readme.md

@@ -2,11 +2,89 @@
 
 Reviewed GitHub releases for Ruby gems, using `bake-gem` for branch preparation, independent content validation, and clean builds.
 
-- `gem:github:release:patch` / `minor` / `major`: prepare, push and open a release PR.
-- `gem:github:setup`: generate the three workflows and native review/CI policy.
-- `gem:github:setup:plan` / `apply`: inspect and apply the managed GitHub rulesets.
-- `gem:github:release:resume run=ID`: retry with the original artifact.
+[![Development Status](https://github.com/socketry/bake-gem-github/workflows/Test/badge.svg)](https://github.com/socketry/bake-gem-github/actions?workflow=Test)
 
-Read [the setup, release and recovery guide](guides/getting-started/readme.md) before enabling publishing. Context is distributed through `agent-context`. This initial implementation requires `bake-gem` 0.15 or later and a live pilot before wider rollout.
+## Motivation
 
-For this gem's releases, follow [the maintainer instructions](.github/releasing.md). Release workflows use the source checkout through Bundler's `gemspec` dependency, so the first release does not require an already published copy of `bake-gem-github`.
+Maintainers need a shared release process that they can run locally or through GitHub. This gem prepares release pull requests for review, validates their generated content, and publishes the merged release through GitHub Actions using RubyGems Trusted Publishing. Retained artifacts and attestations allow interrupted releases to resume using the original verified bytes.
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/bake-gem-github/) for more details.
+
+  - [Getting Started](https://socketry.github.io/bake-gem-github/guides/getting-started/index) - This guide explains how to configure reviewed Ruby gem releases and prepare the first release PR with `bake-gem-github`.
+
+  - [Preparing Releases](https://socketry.github.io/bake-gem-github/guides/preparing-releases/index) - This guide explains how to request a release PR, resume interrupted preparation, and refresh generated content when the default branch changes.
+
+  - [Verifying Releases](https://socketry.github.io/bake-gem-github/guides/verifying-releases/index) - This guide explains how publishing binds a gem to its reviewed source and how to verify the downloaded artifact and attestations.
+
+  - [Recovering Releases](https://socketry.github.io/bake-gem-github/guides/recovering-releases/index) - This guide explains how to resume an interrupted publishing workflow using the original gem and its verification evidence.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/bake-gem-github/releases/index) for all releases.
+
+### v0.3.0
+
+  - Configure publishing environment reviewers through release setup while preserving existing environment protections.
+  - Stop generating `.github/releasing.md`; release instructions are maintained in the shared guide and agent context.
+  - Resume interrupted release preparation and explicitly refresh stale release PRs while preserving their previous commits.
+  - Preserve all release files in one archive before individual asset uploads, so reruns can recover interrupted drafts.
+
+### v0.2.0
+
+  - Use only the version tag for GitHub release titles.
+
+### v0.1.0
+
+  - Include the version's release notes in GitHub releases using `bake-releases`.
+  - Update generated release files in the working tree with `gem:github:setup:update`.
+
+### v0.0.5
+
+  - Preserve and recover release files even when GitHub's release list is stale.
+
+### v0.0.4
+
+  - Preserve verified release files in a draft GitHub release before uploading to RubyGems, so reruns can recover when Actions artifacts disappear.
+  - Wait for RubyGems registry propagation before finalizing releases.
+
+### v0.0.1
+
+  - Initial implementation.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork the repository.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` bash
+$ bundle exec sus
+```
+
+### Making Releases
+
+To prepare a release branch and open a pull request from an up-to-date `main`:
+
+``` bash
+$ bundle exec bake gem:github:release:patch # or minor or major
+```
+
+See [bake-gem-github](https://github.com/socketry/bake-gem-github) for setup, remote releases, and recovery.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -1,5 +1,12 @@
 # Releases
 
+## v0.3.0
+
+  - Configure publishing environment reviewers through release setup while preserving existing environment protections.
+  - Stop generating `.github/releasing.md`; release instructions are maintained in the shared guide and agent context.
+  - Resume interrupted release preparation and explicitly refresh stale release PRs while preserving their previous commits.
+  - Preserve all release files in one archive before individual asset uploads, so reruns can recover interrupted drafts.
+
 ## v0.2.0
 
   - Use only the version tag for GitHub release titles.

data/templates/release-prepare.yaml.erb

@@ -8,6 +8,10 @@ on:
         required: true
         type: choice
         options: [patch, minor, major]
+      refresh:
+        description: Preserve and regenerate an existing release branch
+        type: boolean
+        default: false
 
 permissions:
   contents: write
@@ -38,10 +42,11 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           BUMP: ${{ inputs.bump }}
+          REFRESH: ${{ inputs.refresh }}
         run: |
           # GitHub.com's shared Actions bot ID; this identity is not for GitHub Enterprise Server.
           # https://github.com/actions/checkout#push-a-commit-using-the-built-in-token
           git config user.name 'github-actions[bot]'
           git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
           case "$BUMP" in patch|minor|major) ;; *) exit 1 ;; esac
-          bundle exec bake "gem:github:release:$BUMP"
+          bundle exec bake "gem:github:release:$BUMP" "refresh=$REFRESH"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bake-gem-github
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -94,14 +94,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- agents.md
 - bake/gem/github.rb
 - bake/gem/github/release.rb
 - bake/gem/github/setup.rb
 - context/getting-started.md
 - context/index.yaml
+- context/preparing-releases.md
+- context/recovering-releases.md
+- context/verifying-releases.md
+- lib/bake/gem/github/backup.rb
 - lib/bake/gem/github/project.rb
 - lib/bake/gem/github/publisher.rb
+- lib/bake/gem/github/registry.rb
 - lib/bake/gem/github/setup.rb
 - lib/bake/gem/github/version.rb
 - license.md
@@ -111,11 +115,14 @@ files:
 - templates/release-prepare.yaml.erb
 - templates/release-publish.yaml.erb
 - templates/release-validate.yaml.erb
-- templates/releasing.md
 homepage: https://github.com/socketry/bake-gem-github
 licenses:
 - MIT
-metadata: {}
+metadata:
+  documentation_uri: https://socketry.github.io/bake-gem-github/
+  bug_tracker_uri: https://github.com/socketry/bake-gem-github/issues
+  changelog_uri: https://github.com/socketry/bake-gem-github/blob/main/releases.md
+  source_code_uri: https://github.com/socketry/bake-gem-github.git
 rdoc_options: []
 require_paths:
 - lib