ruby-gem-release 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb0d582f2aa91a4b7e06e0ca416a6e27a3eb12640ffe11d10f833eb6c2652ca0
-  data.tar.gz: cf2c4a04e05ae5f4d148ff2d24fc1ff723e38e2abfb41bf0cd9ade68619ea271
+  metadata.gz: 1babfa3cbf929529a6e8d82e20d3caff5a890c65169dd9db841421e1b2e64057
+  data.tar.gz: 90a8b9b0f759a590d3ca2282d02e84aea20c9edc145af3019ee824fc6f2a05c2
 SHA512:
-  metadata.gz: 1d1a8f271c218dbcac3b94cebfb0259559f817f7e64e6581bb51352c3aaa38fd95de13336098d4501aab8ec114d3ec04cfc56861ada30a5bbe6a16b1bfd8ce0a
-  data.tar.gz: 2f1f8a38fa8de16d07cd5e9968b298114ae78ab478494b5d452fdbd4202e94be18f797fb27986f4f07e88772f4447d1d61b8899928a1214d7c210d6a411aba26
+  metadata.gz: 110cdc78d668d1fe44efdff779514d26bbdc83a4d1905bbb920fa9d8edaed02f1bb683694170141714363177f20b73b515629badea8179708e86fe00a3e4bc2a
+  data.tar.gz: e48613def1a278613a88e99575552425c3d6b1e8a6674e4b5f08010489ae5a608e730b09e0e9e46600b9543028c72ebf101528d1b4032e916458057e517c5773

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0 (2026/11/08)
+
+- [#24](https://github.com/dblock/ruby-gem-release/pull/24): Reject empty release notes in both built-in changelog formats before writing release updates, ignoring placeholders, category headings, comments, and reference definitions - [@dblock](https://github.com/dblock).
+- [#25](https://github.com/dblock/ruby-gem-release/pull/25): Reject existing RubyGems versions before release publication, stop on version lookup failures, and highlight release safeguards, recovery files, and timezone support in README - [@dblock](https://github.com/dblock).
+- [#26](https://github.com/dblock/ruby-gem-release/pull/26): Select a release version with the existing version input, update it through the configured version object before preparation, and replace the version setter API with `set!` (breaking change) - [@dblock](https://github.com/dblock).
+- [#27](https://github.com/dblock/ruby-gem-release/pull/27): Document maintainer-approved publication with protected GitHub environments and clarify dispatch permissions - [@dblock](https://github.com/dblock).
+
 ## 0.3.1 (2026/11/07)
 
 - [#23](https://github.com/dblock/ruby-gem-release/pull/23): Reject dirty checkouts after dependency installation and commit only staged release preparation changes, preventing generated Bundler artifacts and unrelated files from entering releases - [@dblock](https://github.com/dblock).

data/README.md

@@ -9,8 +9,13 @@
 Update your changelog, validate and publish your gem, create its GitHub Release, and prepare the next development iteration with one workflow dispatch. Choose your version and changelog formats; the standard workflow handles the release sequence.
 
 - **No stored RubyGems API key:** Authenticate with RubyGems Trusted Publishing using OpenID Connect (OIDC).
-- **Let collaborators release:** After one-time setup, collaborators with write access, including on personal repositories, can dispatch releases without repository admin access or their own RubyGems credentials.
+- **Let collaborators request releases:** After one-time setup, collaborators with write access, including on personal repositories, can dispatch releases without repository admin access or their own RubyGems credentials. [Environment protection](RELEASING.md#maintainer-approved-publication) can require approval from a release maintainer before publication.
 - **Keep your conventions:** Use the standard workflow or compose Ruby objects and callbacks for custom releases.
+- **Choose the release version:** Release the checked-in version or [select a different version](docs/actions/release.md#release-version) when dispatching, without a separate version-bump commit.
+- **Catch release mistakes:** [Check for already published RubyGems versions](docs/package/ruby_gem.md#check-version), reject existing tags, and [require actual release notes](docs/changelog/base.md#release) in both built-in changelog formats.
+- **Keep dependency files out of release commits:** [Reject dirty checkouts after dependency installation](docs/source_control/git.md) and unexpected working tree or index changes after preparation, instead of staging unrelated files during publication.
+- **Build once and retain recovery files:** Publish the same verified gem artifact to RubyGems and attach it to the GitHub Release. Preserve available gem, checksum manifest, and Git recovery bundle files for [recovery after failures](docs/actions/release.md#recovery-artifacts).
+- **Use your release timezone:** [Configure release dates](docs/actions/release.md#timezone) with a named timezone such as `America/New_York`, including daylight saving changes; UTC is the default.
 
 Requires Ruby 3.3+, GitHub Actions, and RubyGems Trusted Publishing.
 
@@ -42,6 +47,10 @@ name: Release
 on:
   workflow_dispatch:
     inputs:
+      version:
+        description: Optional release version overriding the checked-in version.
+        type: string
+        required: false
       rubygems-owner:
         description: RubyGems account ID for first publication; omit for an existing gem.
         type: string
@@ -53,9 +62,10 @@ permissions:
 
 jobs:
   release:
-    uses: dblock/ruby-gem-release/.github/workflows/release.yml@v0.3.0
+    uses: dblock/ruby-gem-release/.github/workflows/release.yml@v0.3.1
     with:
       ruby-version: '3.3'
+      version: ${{ inputs.version }}
       rubygems-owner: ${{ inputs.rubygems-owner }}
 ```
 
@@ -67,13 +77,11 @@ In your GitHub repository, open **Settings → Environments** and create an envi
 gh api --method PUT repos/{owner}/{repo}/environments/release
 ```
 
-On [RubyGems.org](https://rubygems.org), open your gem's **Trusted publishers** page and create a [trusted publisher](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows). Set the repository fields to your gem's repository, the workflow filename to `release.yml`, and the environment to `release`. Set the separate workflow repository fields to `dblock` and `ruby-gem-release`; these identify the reusable workflow RubyGems verifies in the OIDC token. For a new gem, use the [pending trusted publishers page](https://rubygems.org/profile/oidc/pending_trusted_publishers) instead.
-
-For example, the trusted publishers page for a gem named `example` is `https://rubygems.org/gems/example/trusted_publishers`.
+For a new gem, open the [pending trusted publishers page](https://rubygems.org/profile/oidc/pending_trusted_publishers). For an existing gem, open your existing gem's **Trusted publishers** page (e.g. `https://rubygems.org/gems/example/trusted_publishers`). Create a [trusted publisher](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows). Set the repository fields to your gem's repository, the workflow filename to `release.yml`, and the environment to `release`. Set the separate workflow repository fields to `dblock` and `ruby-gem-release`; these identify the reusable workflow RubyGems verifies in the OIDC token.
 
 ### 4. Make a Release
 
-Your branch rules must permit release commits and tags to be pushed; see [branch permissions](RELEASING.md#one-time-setup). Dispatching the workflow publishes the gem. Run your project's tests and build checks, review the changes, and dispatch from your default branch:
+Your branch rules must permit release commits and tags to be pushed; see [branch permissions](RELEASING.md#one-time-setup). Dispatching starts a publishing run; when required reviewers are configured, the release job waits for approval from a designated maintainer. Run your project's tests and build checks, review the changes, and dispatch from your default branch:
 
 **First release:** Pass the numeric RubyGems account ID shown on the Pending Trusted Publishers page as `rubygems-owner`. This declares the account that will own the gem on its first publication. Replace `YOUR_ACCOUNT_ID` below with that ID:
 
@@ -87,6 +95,8 @@ gh workflow run release.yml -f rubygems-owner=YOUR_ACCOUNT_ID
 gh workflow run release.yml
 ```
 
+To release a different version, select it in the dispatch form or pass `-f version=1.2.3`. The standard workflow updates the configured version file before preparing the changelog, then starts the next development iteration from the selected release version.
+
 For a real-world example of adding release automation to an existing gem, see [ruby-link-checker #26](https://github.com/dblock/ruby-link-checker/pull/26). It adds the dependency, Rake tasks, reusable workflow, and release instructions while preserving the existing changelog format.
 
 ## Configuration
@@ -95,6 +105,10 @@ See [Detailed Usage](docs/usage.md#configuration) for workflow customization, ca
 
 For step-based integration, see the [Composite Action](docs/actions/action.md).
 
+### Release Access
+
+Creating the environment without protection rules does not restrict release access. For maintainer-only publication, configure **Settings → Environments → release** with required maintainer reviewers, self-review and administrator-bypass rules, and deployment branches restricted to `main` (or your actual default branch), as described in [Maintainer-Approved Publication](RELEASING.md#maintainer-approved-publication). Other repository writers can still dispatch, but publication waits for a designated maintainer to approve; environments do not provide a workflow-dispatch allow list.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md), [DESIGN.md](DESIGN.md), [CHANGELOG.md](CHANGELOG.md), and [RELEASING.md](RELEASING.md).

data/lib/ruby-gem-release/changelog/base.rb

@@ -44,6 +44,32 @@ module RubyGemRelease
         content[position, 6][/\A#+/]
       end
 
+      def section_end_position(content, position, level)
+        heading_positions(content, /\A\#{1,6} /, max_level: level).find { |offset| offset > position } || content.length
+      end
+
+      def line_end(content, position, separator)
+        content.index(separator, position) || raise(ArgumentError, "heading must end with a newline in #{@path}")
+      end
+
+      def check_release_notes(content, position, separator, version)
+        section_end = section_end_position(content, position, heading_prefix(content, position).length)
+        check_notes(content[line_end(content, position, separator)...section_end], version)
+      end
+
+      def check_notes(section, version)
+        return section if notes?(document(section))
+
+        raise ArgumentError, "cannot release #{version}: empty release notes in #{@path}; add release notes before retrying"
+      end
+
+      def notes?(node)
+        return false if %i[heading html_block html_inline].include?(node.type)
+        return !node.string_content.strip.empty? if %i[text code code_block].include?(node.type)
+
+        node.each.any? { |child| notes?(child) }
+      end
+
       def editable_lines(content)
         excluded = excluded_lines(content)
         offset = 0

data/lib/ruby-gem-release/changelog/intridea.rb

@@ -24,7 +24,7 @@ module RubyGemRelease
         check_release_absent(content, version)
         section_end = section_end_position(content, position, prefix.length)
         content[position...section_end] = "#{prefix} #{version} (#{date.strftime('%Y/%m/%d')})" +
-                                          remove_placeholder(content[line_end(content, position, separator)...section_end], separator)
+                                          release_notes(content[line_end(content, position, separator)...section_end], separator, version)
         File.write(@path, content)
       end
 
@@ -45,22 +45,14 @@ module RubyGemRelease
         check_absent(content, %r{\A\#{1,6} #{Regexp.escape(version)} \(\d{4}/\d{2}/\d{2}\)\z}, 'release heading already exists')
       end
 
-      def line_end(content, position, separator)
-        content.index(separator, position) || raise(ArgumentError, "heading must end with a newline in #{@path}")
-      end
-
-      def section_end_position(content, position, level)
-        heading_positions(content, /\A\#{1,6} /, max_level: level).find { |offset| offset > position } || content.length
-      end
-
-      def remove_placeholder(section, separator)
+      def release_notes(section, separator, version)
         positions = []
         editable_lines(section) { |line, offset| positions << offset if line.chomp == @placeholder }
         raise ArgumentError, "expected exactly one placeholder in #{@path}" unless positions.one?
 
         position = positions.first
         section.slice!(position, placeholder_length(section, position, separator))
-        section
+        check_notes(section, version)
       end
 
       def placeholder_length(section, position, separator)

data/lib/ruby-gem-release/changelog/keep_a_changelog.rb

@@ -13,11 +13,9 @@ module RubyGemRelease
         separator = newline(content)
         position = heading(content, UNRELEASED)
         check_absent(content, /\A\#{1,6} \[#{Regexp.escape(version)}\] - \d{4}-\d{2}-\d{2}\z/, 'release heading already exists')
-        line_end = content.index(separator, position)
-        raise ArgumentError, "heading must end with a newline in #{@path}" unless line_end
-
-        content[position...line_end] = "#{heading_prefix(content, position)} [#{version}] - #{date.strftime('%Y-%m-%d')}"
+        content[position...line_end(content, position, separator)] = "#{heading_prefix(content, position)} [#{version}] - #{date.strftime('%Y-%m-%d')}"
         release_references(content, version, separator)
+        check_release_notes(content, position, separator, version)
         File.write(@path, content)
       end
 

data/lib/ruby-gem-release/package/ruby_gem.rb

@@ -6,6 +6,8 @@ require 'json'
 require 'digest'
 require 'fileutils'
 require 'tmpdir'
+require 'net/http'
+require 'uri'
 
 module RubyGemRelease
   module Package
@@ -18,8 +20,14 @@ module RubyGemRelease
       end
 
       def version
-        script = 'spec = Gem::Specification.load(ARGV.fetch(0)); abort "Cannot load gemspec" unless spec; puts spec.version'
-        run(Gem.ruby, '-rrubygems', '-e', script, @gemspec).strip
+        specification.fetch('version')
+      end
+
+      def check_version!(version)
+        name = specification.fetch('name')
+        raise 'Invalid package name' unless name.is_a?(String) && /\A[A-Za-z0-9][A-Za-z0-9_.-]*\z/.match?(name)
+
+        check_published_version(name, version)
       end
 
       def build!(release)
@@ -41,11 +49,32 @@ module RubyGemRelease
 
       def publish!(release)
         path = artifact(release)
+        check_published_version(verified_manifest(release).fetch('name'), release.version)
         run(Gem.ruby, '-S', 'gem', 'push', path)
       end
 
       private
 
+      def specification
+        script = 'spec = Gem::Specification.load(ARGV.fetch(0)); abort "Cannot load gemspec" unless spec; puts JSON.generate(name: spec.name, version: spec.version.to_s)'
+        JSON.parse(run(Gem.ruby, '-rrubygems', '-rjson', '-e', script, @gemspec))
+      end
+
+      def check_published_version(name, version)
+        response = version_response(name, version)
+        raise "#{name} #{version} is already published on RubyGems; do not republish it, see RELEASING.md for recovery" if response.code == '200'
+        return if response.code == '404'
+
+        raise "Cannot check RubyGems for #{name} #{version} (HTTP #{response.code}); verify RubyGems availability before retrying"
+      end
+
+      def version_response(name, version)
+        uri = URI("https://rubygems.org/api/v2/rubygems/#{URI.encode_www_form_component(name)}/versions/#{URI.encode_www_form_component(version)}.json")
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30, max_retries: 0) { |http| http.get(uri.request_uri) }
+      rescue Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+        raise "Cannot check RubyGems for #{name} #{version}: #{e.message}; verify connectivity before retrying"
+      end
+
       def build_manifest(release)
         spec = Gem::Package.new(archive).spec
         raise "Built version #{spec.version} does not match #{release.version}" unless spec.version.to_s == release.version

data/lib/ruby-gem-release/tasks.rb

@@ -78,7 +78,7 @@ module RubyGemRelease
 
     def context(before_release: false)
       previous_version = ENV.fetch('RELEASE_PREVIOUS_VERSION')
-      version = before_release ? previous_version : ENV.fetch('RELEASE_VERSION')
+      version = before_release ? preparation_version(previous_version) : ENV.fetch('RELEASE_VERSION')
       date = ENV.fetch('RELEASE_DATE')
       validate_context_versions(version, previous_version)
       raise ArgumentError, 'release date is required in YYYY-MM-DD format' unless date.match?(/\A\d{4}-\d{2}-\d{2}\z/)
@@ -86,6 +86,11 @@ module RubyGemRelease
       Release.new(version: version, previous_version: previous_version, date: Date.iso8601(date))
     end
 
+    def preparation_version(previous_version)
+      selected = ENV.fetch('INPUT_VERSION', '')
+      selected.empty? ? previous_version : selected
+    end
+
     def validate_context_versions(*versions)
       pattern = Version::RubyConstant::PATTERN
       versions.compact.each do |value|

data/lib/ruby-gem-release/version/ruby_constant.rb

@@ -18,7 +18,7 @@ module RubyGemRelease
         value
       end
 
-      def set(value)
+      def set!(value)
         parse(value)
         content = File.read(@path)
         match = assignment(content)
@@ -34,7 +34,7 @@ module RubyGemRelease
         end
         parts[index] += 1
         ((index + 1)...parts.size).each { |i| parts[i] = 0 }
-        set(parts.join('.'))
+        set!(parts.join('.'))
       end
 
       private

data/lib/ruby-gem-release/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyGemRelease
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

data/lib/ruby-gem-release/workflow/context.rb

@@ -28,19 +28,26 @@ module RubyGemRelease
       end
 
       def resolve!
-        version = Package::RubyGem.new.version
-        validate_version(version)
-        expected = ENV.fetch('INPUT_VERSION', '')
-        raise "Prepared version #{version} does not match expected version #{expected}" unless expected.empty? || version == expected
-
+        package = Package::RubyGem.new
+        version = prepared_version(package)
         git = SourceControl::Git.new
         git.check_tag!(version)
+        package.check_version!(version)
         git.stage_changes!
         export('RELEASE_VERSION' => version)
       end
 
       private
 
+      def prepared_version(package)
+        version = package.version
+        validate_version(version)
+        selected = ENV.fetch('INPUT_VERSION', '')
+        raise "Prepared version #{version} does not match selected version #{selected}" unless selected.empty? || version == selected
+
+        version
+      end
+
       def initial_release(package)
         version = package.version
         validate_version(version)

data/lib/ruby-gem-release/workflow/ruby_gem.rb

@@ -28,11 +28,19 @@ module RubyGemRelease
 
       def prepare_release(release)
         @git.stage_changes! do
+          select_version!(release.version) unless ENV.fetch('INPUT_VERSION', '').empty?
           @changelog&.release!(release.with_version(@version.read))
         end
       end
 
+      def select_version!(version)
+        raise ArgumentError, 'version object must implement set! when selecting a release version' unless @version.respond_to?(:set!)
+
+        @version.set!(version)
+      end
+
       def publish(release)
+        @package.check_version!(release.version)
         @git.commit!(release)
         @package.build!(release)
         @git.tag!(release)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-gem-release
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Daniel Doubrovkine