kettle-dev 2.5.14 → 2.5.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd42849120d31c48755d543918cd96ea2abb0f61d550983853ae6827940099f6
-  data.tar.gz: 5bfc7a99f63937031b7999db6d6a35aa9583f7fc3547db425196fb18d3819458
+  metadata.gz: 561f0712647c4d27b03caa44fe76613f2d68602b056d2e0ada052c6c13334f51
+  data.tar.gz: 148358784c948bfa8368b36e683834e21636277539ad1b084450829a57721af7
 SHA512:
-  metadata.gz: 91ae2809e3092c93f6feaa5b20f4dbc562497917244f95f388ababfe72403f9af76f924314a561c85dc39f8e0f987ed4d19580675612bb01c117fa1e8f1be58e
-  data.tar.gz: 0c77a71e021fe4657903384d45ecf8da00c136b78bc0a6cb7531ecc584606bb9fa7abd0ad7a683ea844ee6d3a0be59ecfe388c3cdce1dafbf65989a72b4b6063
+  metadata.gz: db47e6daf32deff2da6749a388a8c802e65e492ce63d35f0cd606f8cdc8ddf73ab4fda2d137c0c834bff64043f3739440bae25b567391838f43eaf376c0031d9
+  data.tar.gz: d40265dd3c8eb72654de1cec852753e2f6deaa5f996809ad348b4ae90d00d65ad70a5fb24a82570e30764bd9425ebc23e394bf2bdfee9d47f8939a6efb635559

data/CHANGELOG.md

@@ -30,6 +30,35 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [2.5.15] - 2026-08-01
+
+- TAG: [v2.5.15][2.5.15t]
+- COVERAGE: 91.55% -- 5266/5752 lines in 46 files
+- BRANCH COVERAGE: 75.74% -- 1986/2622 branches in 46 files
+- 50.41% documented
+
+### Added
+
+- Add verified GitHub Release backfill checks and NDJSON support to kettle-gh-release.
+
+- Add a changelog reformat mode for historical release metadata repair.
+
+- Add historical changelog reformat and GitHub release reconciliation checks.
+
+- Add an explicit historical release-section backfill mode for tagged releases.
+
+- Add kettle-gh-release update mode for existing GitHub Release notes.
+
+### Fixed
+
+- Allow the changelog entry writer to add to malformed Unreleased sections with duplicate headings.
+
+- Honor K_CHANGELOG_PATH when adding an Unreleased changelog entry.
+
+- Canonicalize legacy release headings and remove redundant historical placeholders during reformat.
+
+- Roll back unpublished prepared changelog sections when version.rb returns to the published version.
+
 ## [2.5.14] - 2026-07-31
 
 - TAG: [v2.5.14][2.5.14t]
@@ -3173,7 +3202,9 @@ Please file a bug if you notice a violation of semantic versioning.
   - Selecting will run the selected workflow via `act`
   - This may move to its own gem in the future.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.14...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.15...HEAD
+[2.5.15]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.14...v2.5.15
+[2.5.15t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.5.15
 [2.5.14]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.13...v2.5.14
 [2.5.14t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.5.14
 [2.5.13]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.12...v2.5.13

data/README.md

@@ -849,8 +849,8 @@ Thanks for RTFM. ☺️
 [✉️discord-invite-img-ftb]: https://img.shields.io/discord/1373797679469170758?style=for-the-badge&logo=discord
 [✉️ruby-friends-img]: https://img.shields.io/badge/daily.dev-%F0%9F%92%8E_Ruby_Friends-0A0A0A?style=for-the-badge&logo=dailydotdev&logoColor=white
 [✉️ruby-friends]: https://app.daily.dev/squads/rubyfriends
-[✉️ruby-forum-top-img]: https://img.shields.io/discourse/topics?server=https://www.rubyforum.org&style=flat&logo=discourse&label=Ruby%20Users%20Forum
-[✉️ruby-forum-img]: https://img.shields.io/discourse/topics?server=https://www.rubyforum.org&style=for-the-badge&logo=discourse&label=Ruby%20Users%20Forum
+[✉️ruby-forum-top-img]: https://img.shields.io/discourse/topics?server=https%3A%2F%2Fwww.rubyforum.org&style=flat&logo=discourse&label=Ruby%20Users%20Forum
+[✉️ruby-forum-img]: https://img.shields.io/discourse/topics?server=https%3A%2F%2Fwww.rubyforum.org&style=for-the-badge&logo=discourse&label=Ruby%20Users%20Forum
 [✉️ruby-forum]: https://www.rubyforum.org/tag/kettle-dev
 
 [✇bundle-group-pattern]: https://gist.github.com/pboling/4564780
@@ -1005,7 +1005,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.597-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.752-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-dev/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/exe/kettle-changelog

@@ -63,7 +63,7 @@ end
 
 if ARGV.include?("-h") || ARGV.include?("--help")
   puts <<~USAGE
-    Usage: kettle-changelog [--version VERSION] [--yes] [--update-prep] [--pending-release] [--release-state] [--refresh-cache] [--add-unreleased-entry --section SECTION --entry TEXT] [--json|--events[=TYPES]] [--no-strict] [--no-coverage-threshold]
+    Usage: kettle-changelog [--version VERSION] [--yes] [--update-prep|--reformat|--backfill-released-version VERSION] [--pending-release] [--release-state] [--refresh-cache] [--add-unreleased-entry --section SECTION --entry TEXT] [--json|--events[=TYPES]] [--no-strict] [--no-coverage-threshold]
 
     Detects the current version from lib/**/version.rb, the latest live release, and
     the most recent CHANGELOG.md release section, then prompts to confirm the selected plan:
@@ -76,6 +76,9 @@ if ARGV.include?("-h") || ARGV.include?("--help")
       --version VERSION         Use this version instead of detecting VERSION from lib/**/version.rb
       --yes                     Auto-approve the selected release plan
       --update-prep             Force updating the most recent prepared release section in place
+      --reformat                Normalize CHANGELOG.md structure without release-state planning
+      --backfill-released-version VERSION
+                                Add a tagged historical section without moving Unreleased entries
       --pending-release         Query whether the changelog has release work pending; exits 0 for yes, 1 for no
       --release-state,
       --release-status          Print changelog release state, including latest published release and pending sources
@@ -159,6 +162,7 @@ begin
   # Determine if strict mode is enabled (default: true)
   strict_mode = !ARGV.include?("--no-strict") && ENV.fetch("K_CHANGELOG_STRICT", "true").downcase != "false"
   update_prep = ARGV.delete("--update-prep")
+  reformat_only = ARGV.delete("--reformat")
   yes = !!ARGV.delete("--yes")
   pending_release_query = ARGV.delete("--pending-release")
   release_state_query = ARGV.delete("--release-state") || ARGV.delete("--release-status")
@@ -189,6 +193,8 @@ begin
     value
   end
 
+  historical_backfill_version = extract_option_arg!(ARGV, "--backfill-released-version")
+
   if add_unreleased_entry
     section = extract_option_arg!(ARGV, "--section")
     entry = extract_option_arg!(ARGV, "--entry")
@@ -202,7 +208,7 @@ begin
   end
 
   event_stream = events_output ? Kettle::Ndjson.event_stream($stdout, types: event_types) : nil
-  cli = Kettle::Dev::ChangelogCLI.new(strict: strict_mode, enforce_coverage_thresholds: coverage_hard, update_prep: update_prep, version: version_override, refresh_cache: refresh_cache, yes: yes, event_stream: event_stream)
+  cli = Kettle::Dev::ChangelogCLI.new(strict: strict_mode, enforce_coverage_thresholds: coverage_hard, update_prep: update_prep, reformat_only: reformat_only, historical_backfill_version: historical_backfill_version, version: version_override, refresh_cache: refresh_cache, yes: yes, event_stream: event_stream)
   if release_state_query
     state = cli.release_state
     puts(json_output ? JSON.pretty_generate(state) : cli.release_state_table(state))

data/exe/kettle-gh-release

@@ -39,7 +39,7 @@ end
 # Do not guard with __FILE__ == $PROGRAM_NAME because binstubs use Kernel.load.
 if ARGV.include?("-h") || ARGV.include?("--help")
   puts <<~USAGE
-    Usage: #{script_basename} [version=<VERSION>]
+    Usage: #{script_basename} [--release-version VERSION|version=<VERSION>] [--check|--update] [--events] [--allow-unpublished]
 
     Creates a GitHub release for a gem version.
 
@@ -48,29 +48,99 @@ if ARGV.include?("-h") || ARGV.include?("--help")
     failed (e.g., due to token issues or network problems).
 
     Arguments:
-      version=<VERSION>           # Explicit version (e.g., version=1.2.3)
-                                  # If omitted, auto-detects from lib/**/version.rb
+      --release-version VERSION   # Explicit version (e.g., --release-version 1.2.3)
+      version=<VERSION>           # Backward-compatible explicit version form
+      --check                     # Verify RubyGems, remote tag, changelog, and token without creating a release
+      --update                    # Update an existing GitHub Release title/body from CHANGELOG.md
+      --events                    # Emit the final result as one NDJSON event
+      --allow-unpublished         # Skip the RubyGems publication requirement (for intentionally non-RubyGems projects)
 
     Environment:
       GITHUB_TOKEN / GH_TOKEN     # Required; needs repo:public_repo (classic) or contents:write scope
       DEBUG=true                  # Print backtraces on errors
 
     Examples:
-      #{script_basename}                    # auto-detect version, create release
-      #{script_basename} version=2.0.0      # create release for specific version
-      GITHUB_TOKEN=ghp_xxx #{script_basename}  # explicit token
+      #{script_basename} --check --release-version 2.0.0
+      #{script_basename} --release-version 2.0.0
+      #{script_basename} version=2.0.0      # backward-compatible form
   USAGE
   exit 0
 end
 
-# Parse version=<v> from ARGV
-version_arg = ARGV.find { |a| a.start_with?("version=") }
-explicit_version = version_arg ? version_arg.split("=", 2)[1].strip : nil
+check_only = ARGV.delete("--check")
+update_only = ARGV.delete("--update")
+if check_only && update_only
+  warn("#{script_basename}: --check and --update cannot be combined")
+  exit 1
+end
+events = ARGV.delete("--events")
+allow_unpublished = ARGV.delete("--allow-unpublished")
+version_arg = ARGV.find { |arg| arg.start_with?("version=") }
+ARGV.delete(version_arg) if version_arg
+explicit_version = version_arg&.split("=", 2)&.last&.strip
+
+if (index = ARGV.index("--release-version"))
+  explicit_version = ARGV.fetch(index + 1, nil).to_s.strip
+  ARGV.slice!(index, 2)
+end
+
+unless ARGV.empty?
+  warn("#{script_basename}: unexpected argument(s): #{ARGV.join(" ")}")
+  exit 1
+end
+
+if !explicit_version.nil? && explicit_version.empty?
+  warn("#{script_basename}: --release-version requires a version")
+  exit 1
+end
 
 begin
   cli = Kettle::Dev::ReleaseCLI.new(start_step: 18)
   version = explicit_version || cli.send(:detect_version)
-  cli.send(:maybe_create_github_release!, version)
+  result = cli.send(:github_release_backfill_check, version, require_rubygems: !allow_unpublished)
+
+  if events
+    action = if check_only
+      "check"
+    elsif update_only
+      "update"
+    else
+      "create"
+    end
+    puts JSON.generate(
+      event_version: 1,
+      type: "github_release",
+      action: action,
+      status: result.fetch("ok") ? "ok" : "failed",
+      **result
+    )
+  elsif result.fetch("ok")
+    puts "GitHub release prerequisites satisfied for #{result.fetch("tag")}."
+  else
+    warn("GitHub release prerequisites failed for #{result.fetch("tag")}:")
+    result.fetch("diagnostics").each { |diagnostic| warn("  - #{diagnostic}") }
+  end
+
+  exit 1 unless result.fetch("ok")
+  exit 0 if check_only
+
+  created, message = if update_only
+    cli.send(:maybe_update_github_release!, version)
+  else
+    cli.send(:maybe_create_github_release!, version)
+  end
+  if events
+    puts JSON.generate(
+      event_version: 1,
+      type: "github_release",
+      action: update_only ? "update" : "create",
+      status: created ? "ok" : "failed",
+      version: result.fetch("version"),
+      tag: result.fetch("tag"),
+      result: message
+    )
+  end
+  exit(created ? 0 : 1)
 rescue LoadError => e
   warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
   warn(Array(e.backtrace).join("\n")) if ENV["DEBUG"]

data/lib/kettle/dev/changelog_cli.rb

@@ -27,9 +27,11 @@ module Kettle
       # @param strict [Boolean] when true (default), require coverage and yard data; raise errors if unavailable
       # @param enforce_coverage_thresholds [Boolean] when true, fail strict coverage generation below project thresholds
       # @param update_prep [Boolean] when true, update the most recent prepared release section in place
+      # @param reformat_only [Boolean] when true, normalize structure without release-state planning
+      # @param historical_backfill_version [String, nil] tagged release to document without moving Unreleased entries
       # @param version [String, nil] explicit version override for gems without a literal VERSION constant
       # @param yes [Boolean] when true, approve the selected release plan without prompting
-      def initialize(strict: true, enforce_coverage_thresholds: true, update_prep: false, version: nil, root: Kettle::Dev::CIHelpers.project_root, refresh_cache: false, yes: false, event_stream: nil)
+      def initialize(strict: true, enforce_coverage_thresholds: true, update_prep: false, reformat_only: false, historical_backfill_version: nil, version: nil, root: Kettle::Dev::CIHelpers.project_root, refresh_cache: false, yes: false, event_stream: nil)
         @root = root
         @changelog_path = resolved_changelog_path
         @coverage_root = resolved_coverage_root
@@ -37,6 +39,8 @@ module Kettle
         @strict = strict
         @enforce_coverage_thresholds = enforce_coverage_thresholds
         @update_prep = update_prep
+        @reformat_only = reformat_only
+        @historical_backfill_version = Kettle::Dev::Versioning.normalize_explicit_version(historical_backfill_version)
         @version_override = Kettle::Dev::Versioning.normalize_explicit_version(version)
         @refresh_cache = refresh_cache
         @yes = !!yes
@@ -50,6 +54,17 @@ module Kettle
       #
       # @return [void]
       def run
+        if @reformat_only
+          reformat_changelog!(File.read(@changelog_path))
+          emit_changelog_event(action: "reformat", status: "ok", plan: "reformat_only")
+          return
+        end
+
+        if @historical_backfill_version
+          backfill_historical_release!(@historical_backfill_version)
+          return
+        end
+
         version = detect_version
         today = Time.now.strftime("%Y-%m-%d")
         owner, repo = Kettle::Dev::CIHelpers.repo_info
@@ -67,6 +82,12 @@ module Kettle
           return
         end
 
+        if plan.fetch(:action) == :rollback_prepared_release
+          rollback_prepared_release!(changelog, owner, repo, version)
+          emit_changelog_event(action: "rollback", status: "ok", version: plan.fetch(:latest_changelog_version), plan: "rollback_prepared_release")
+          return
+        end
+
         line_cov_line, branch_cov_line = coverage_lines
         yard_line = yard_percent_documented
 
@@ -300,21 +321,23 @@ module Kettle
           abort("Aborting: version.rb (#{version}) is lower than the latest released version for this release line (#{latest_target}).")
         end
 
-        if section_exists && latest_changelog_version != version
+        if latest_target == version && latest_changelog_version && Gem::Version.new(latest_changelog_version) > Gem::Version.new(version)
+          action = :rollback_prepared_release
+        elsif section_exists && latest_changelog_version != version
           abort("Aborting: CHANGELOG.md already contains a #{version} section, but the most recent release section is #{latest_changelog_version || "missing"}.")
-        end
-
-        action = if section_exists && latest_target == version
-          if unreleased_block_has_entries?(unreleased_block)
-            abort("Aborting: version.rb (#{version}) matches the latest released version for this release line (#{latest_target}); bump version.rb before moving Unreleased entries into a release section.")
-          end
-          :reformat_only
-        elsif section_exists
-          :update_prepared_release
-        elsif latest_target == version
-          abort("Aborting: version.rb (#{version}) matches the latest released version, but CHANGELOG.md does not have #{version} as the most recent release section.")
         else
-          :new_release
+          action = if section_exists && latest_target == version
+            if unreleased_block_has_entries?(unreleased_block)
+              abort("Aborting: version.rb (#{version}) matches the latest released version for this release line (#{latest_target}); bump version.rb before moving Unreleased entries into a release section.")
+            end
+            :reformat_only
+          elsif section_exists
+            :update_prepared_release
+          elsif latest_target == version
+            abort("Aborting: version.rb (#{version}) matches the latest released version, but CHANGELOG.md does not have #{version} as the most recent release section.")
+          else
+            :new_release
+          end
         end
 
         {
@@ -396,6 +419,8 @@ module Kettle
 
       def reformat_changelog!(changelog)
         updated = convert_heading_tag_suffix_to_list(changelog)
+        updated = normalize_legacy_release_headings(updated)
+        updated = remove_redundant_historical_placeholders(updated)
         updated = normalize_heading_spacing(updated)
         updated = ensure_footer_spacing(updated)
         updated = updated.rstrip + "\n"
@@ -403,6 +428,86 @@ module Kettle
         puts "CHANGELOG.md reformatted. No new version section added."
       end
 
+      def normalize_legacy_release_headings(changelog)
+        changelog.to_s.lines.map do |line|
+          match = line.match(/^##\s+(?!\[)(v?\d+(?:\.\d+)+(?:[.-][0-9A-Za-z]+)?)(\s+-\s+.*)?\s*$/)
+          next line unless match
+
+          version = match[1].delete_prefix("v")
+          next line unless Gem::Version.correct?(version)
+
+          "## [#{version}]#{match[2]}\n"
+        end.join
+      end
+
+      def remove_redundant_historical_placeholders(changelog)
+        lines = changelog.to_s.lines
+        sections = changelog_release_sections(lines)
+        removals = sections.group_by { |section| section.fetch(:version) }.values.flat_map do |same_version|
+          next [] unless same_version.size > 1
+          next [] unless same_version.any? { |section| !section.fetch(:placeholder) }
+
+          same_version.filter_map do |section|
+            (section.fetch(:start)...section.fetch(:finish)) if section.fetch(:placeholder)
+          end
+        end
+        return changelog if removals.empty?
+
+        lines.each_with_index.reject { |_line, index| removals.any? { |range| range.cover?(index) } }.map(&:first).join
+      end
+
+      def changelog_release_sections(lines)
+        headings = lines.each_index.filter_map do |index|
+          match = lines[index].match(/^## \[(#{CHANGELOG_VERSION_PATTERN_SOURCE})\]/o)
+          {version: match[1], start: index} if match
+        end
+        headings.each_with_index.map do |heading, index|
+          next_heading = headings[index + 1]
+          footer = lines.each_index.find do |line_index|
+            line_index > heading.fetch(:start) && lines[line_index].start_with?(UNRELEASED_SECTION_HEADING)
+          end
+          finish = [next_heading&.fetch(:start), footer, lines.length].compact.min
+          body = lines[heading.fetch(:start)...finish].join
+          heading.merge(finish: finish, placeholder: body.include?("Historical release notes are unavailable in this changelog."))
+        end
+      end
+
+      def backfill_historical_release!(version)
+        changelog = File.read(@changelog_path)
+        abort("CHANGELOG.md already contains a section for #{version}") if release_section_exists?(changelog, version)
+
+        unreleased_block, before, after = extract_unreleased(changelog)
+        abort("Could not find '## [Unreleased]' section in CHANGELOG.md") if unreleased_block.nil?
+
+        date = tagged_release_date(version)
+        owner, repo = Kettle::Dev::CIHelpers.repo_info
+        abort("Could not determine GitHub owner/repo from origin remote") unless owner && repo
+
+        section = <<~MD
+          ## [#{version}] - #{date}
+          - TAG: [v#{version}][#{version}t]
+
+          ### Changed
+
+          - Historical release notes are unavailable in this changelog.
+
+        MD
+        updated = before + "## [Unreleased]\n" + unreleased_block.rstrip + "\n\n" + section + after.to_s
+        updated = update_link_refs(updated, owner, repo, nil, version)
+        updated = normalize_heading_spacing(updated).rstrip + "\n"
+        File.write(@changelog_path, updated)
+        emit_changelog_event(action: "backfill", status: "ok", version: version, plan: "historical_release")
+        puts "CHANGELOG.md backfilled with historical v#{version} section. Unreleased entries were preserved."
+      end
+
+      def tagged_release_date(version)
+        tag = "v#{version}"
+        output, status = Open3.capture2("git", "log", "-1", "--format=%as", tag, chdir: @root)
+        abort("Local git tag #{tag} is required to backfill a historical release section") unless status.success? && !output.strip.empty?
+
+        output.strip
+      end
+
       def release_section_exists?(changelog, version)
         changelog.match?(/^## \[#{Regexp.escape(version)}\]/)
       end
@@ -562,6 +667,25 @@ module Kettle
         puts "CHANGELOG.md updated in place for v#{prepared_version}."
       end
 
+      def rollback_prepared_release!(changelog, owner, repo, published_version)
+        unreleased_block, before, after = extract_unreleased(changelog)
+        release_lines = after.to_s.lines
+        heading = release_lines.first.to_s.match(/\A## \[(#{CHANGELOG_VERSION_PATTERN_SOURCE})\]/o)
+        abort("Could not find a prepared release section after '## [Unreleased]' in CHANGELOG.md") unless heading
+
+        finish = release_lines.each_index.drop(1).find do |index|
+          release_lines[index].start_with?("## [", UNRELEASED_SECTION_HEADING)
+        end || release_lines.length
+        prepared_version = heading[1]
+        merged = merge_release_body_with_unreleased(release_lines[1...finish].join, unreleased_block)
+        unreleased = "## [Unreleased]\n" + merged.rstrip + "\n\n"
+        tail = release_lines[finish, release_lines.length].to_a.reject { |line| line.start_with?("[#{prepared_version}]:", "[#{prepared_version}t]:") }.join
+        updated = before + unreleased + tail
+        updated = update_link_refs(updated, owner, repo, nil, published_version)
+        File.write(@changelog_path, normalize_heading_spacing(updated).rstrip + "\n")
+        puts "CHANGELOG.md rolled back prepared v#{prepared_version} into Unreleased."
+      end
+
       def merge_release_body_with_unreleased(release_body, unreleased_block)
         existing = strip_release_metadata(release_body)
         incoming = filter_unreleased_sections(unreleased_block)

data/lib/kettle/dev/changelog_entry_adder.rb

@@ -9,7 +9,7 @@ module Kettle
         @root = root
         @section = section.to_s
         @entry = normalize_entry(entry)
-        @changelog_path = File.join(@root, "CHANGELOG.md")
+        @changelog_path = ENV.fetch("K_CHANGELOG_PATH", File.join(@root, "CHANGELOG.md"))
       end
 
       def run
@@ -68,7 +68,7 @@ module Kettle
             owner.location.start_line > unreleased.location.start_line &&
             owner.location.end_line <= unreleased.location.end_line
         end
-        raise Error, "expected exactly one #{heading(3, @section)} section under ## [Unreleased] in CHANGELOG.md, found #{matches.length}" unless matches.length == 1
+        raise Error, "expected at least one #{heading(3, @section)} section under ## [Unreleased] in CHANGELOG.md, found none" if matches.empty?
 
         matches.first
       end

data/lib/kettle/dev/release_cli.rb

@@ -436,7 +436,8 @@ module Kettle
         # 18. create GitHub release (optional)
         if run_step?(18)
           version ||= detect_version
-          maybe_create_github_release!(version)
+          created, message = maybe_create_github_release!(version)
+          abort("GitHub release creation failed: #{message}") if github_release_required? && !created
         end
 
         # 19. push tags to remotes (final step)
@@ -2340,24 +2341,27 @@ module Kettle
       # Title: v<version>
       # Body: the CHANGELOG section for this version, followed by the two link references for this version.
       def maybe_create_github_release!(version)
-        token = ENV.fetch("GITHUB_TOKEN", "").strip.to_s
+        token = github_token
         if token.empty?
-          warn("GITHUB_TOKEN not set; skipping GitHub release creation. Set GITHUB_TOKEN with repo:public_repo (classic) or contents:write scope.")
-          return
+          message = "GITHUB_TOKEN or GH_TOKEN is not set; skipping GitHub release creation. Set a token with repo:public_repo (classic) or contents:write scope."
+          warn(message)
+          return [false, message]
         end
 
         gh_remote = preferred_github_remote
         url = remote_url(gh_remote || "origin")
         owner, repo = parse_github_owner_repo(url)
         unless owner && repo
-          warn("GITHUB_TOKEN present but could not determine GitHub owner/repo from remotes. Skipping release creation.")
-          return
+          message = "GitHub token present but could not determine GitHub owner/repo from remotes. Skipping release creation."
+          warn(message)
+          return [false, message]
         end
 
         section, compare_ref, tag_ref = extract_changelog_for_version(version)
         unless section
-          warn("CHANGELOG.md does not contain a section for #{version}. Skipping GitHub release creation.")
-          return
+          message = "CHANGELOG.md does not contain a section for #{version}. Skipping GitHub release creation."
+          warn(message)
+          return [false, message]
         end
 
         body = +""
@@ -2377,6 +2381,97 @@ module Kettle
         else
           warn("GitHub release creation skipped/failed: #{msg}")
         end
+        [ok, msg]
+      end
+
+      def maybe_update_github_release!(version)
+        token = github_token
+        return [false, "GITHUB_TOKEN or GH_TOKEN is not set"] if token.empty?
+
+        owner, repo = parse_github_owner_repo(remote_url(preferred_github_remote || "origin"))
+        return [false, "could not determine GitHub owner/repo from remotes"] unless owner && repo
+
+        body = github_release_body(version)
+        return [false, "CHANGELOG.md does not contain a section for #{version}"] unless body
+
+        github_update_release(owner: owner, repo: repo, token: token, tag: "v#{version}", title: "v#{version}", body: body)
+      end
+
+      def github_release_body(version)
+        section, compare_ref, tag_ref = extract_changelog_for_version(version)
+        return unless section
+
+        body = +section.rstrip
+        body << "\n\n" << compare_ref if compare_ref
+        body << tag_ref if tag_ref
+        footer = extract_release_notes_footer
+        body << "\n" << footer if footer && !footer.strip.empty?
+        body
+      end
+
+      # Validate the immutable inputs required to backfill a GitHub Release.
+      # This must never create a tag or publish a gem as a side effect.
+      def github_release_backfill_check(version, require_rubygems: true)
+        normalized_version = version.to_s.delete_prefix("v")
+        tag = "v#{normalized_version}"
+        diagnostics = []
+        token = github_token
+        diagnostics << "GITHUB_TOKEN is not set" if token.empty?
+
+        gem_name = detect_gem_name
+        if require_rubygems && !rubygems_version_published?(gem_name, normalized_version)
+          diagnostics << "RubyGems.org does not list #{gem_name} #{normalized_version}"
+        end
+
+        remote = preferred_github_remote
+        if remote.nil?
+          diagnostics << "no GitHub remote is configured"
+        elsif !remote_tag_exists?(remote, tag)
+          diagnostics << "remote #{remote.inspect} does not contain tag #{tag}"
+        end
+
+        section, = extract_changelog_for_version(normalized_version)
+        diagnostics << "CHANGELOG.md does not contain a section for #{normalized_version}" unless section
+
+        {
+          "ok" => diagnostics.empty?,
+          "version" => normalized_version,
+          "tag" => tag,
+          "gem_name" => gem_name,
+          "remote" => remote,
+          "diagnostics" => diagnostics
+        }
+      end
+
+      def github_release_token_configured?
+        !github_token.empty?
+      end
+
+      def github_release_required?
+        github_release_token_configured? && truthy_value?(ENV["KETTLE_RELEASE_REQUIRE_GITHUB_RELEASE"])
+      end
+
+      def github_token
+        token = ENV.fetch("GITHUB_TOKEN", "").strip
+        return token unless token.empty?
+
+        ENV.fetch("GH_TOKEN", "").strip
+      end
+
+      def rubygems_version_published?(gem_name, version)
+        versions = Kettle::Dev::RubyGemsVersions.fetch(gem_name, version_hint: version, refresh: true)
+        Array(versions).any? { |entry| entry.is_a?(Hash) && entry["number"].to_s == version.to_s }
+      rescue => error
+        warn("Could not verify RubyGems.org publication for #{gem_name} #{version}: #{error.class}: #{error.message}")
+        false
+      end
+
+      def remote_tag_exists?(remote, tag)
+        _stdout, _stderr, status = Open3.capture3("git", "ls-remote", "--exit-code", "--tags", remote, "refs/tags/#{tag}", chdir: @root)
+        status.success?
+      rescue SystemCallError => error
+        warn("Could not verify remote tag #{tag}: #{error.class}: #{error.message}")
+        false
       end
 
       # Returns [section_text, compare_ref_line, tag_ref_line]
@@ -2465,6 +2560,28 @@ module Kettle
       rescue => e
         [false, "#{e.class}: #{e.message}"]
       end
+
+      def github_update_release(owner:, repo:, token:, tag:, title:, body:)
+        lookup = URI("https://api.github.com/repos/#{owner}/#{repo}/releases/tags/#{tag}")
+        get = Net::HTTP::Get.new(lookup)
+        get["Accept"] = "application/vnd.github+json"
+        get["Authorization"] = "token #{token}"
+        get["User-Agent"] = "kettle-dev-release-cli"
+        release = Net::HTTP.start(lookup.host, lookup.port, use_ssl: true) { |http| http.request(get) }
+        return [false, "release #{tag} was not found (HTTP #{release.code})"] unless release.is_a?(Net::HTTPSuccess)
+
+        id = JSON.parse(release.body).fetch("id")
+        uri = URI("https://api.github.com/repos/#{owner}/#{repo}/releases/#{id}")
+        request = Net::HTTP::Patch.new(uri)
+        request["Accept"] = "application/vnd.github+json"
+        request["Authorization"] = "token #{token}"
+        request["User-Agent"] = "kettle-dev-release-cli"
+        request.body = JSON.dump(name: title, body: body)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
+        response.is_a?(Net::HTTPSuccess) ? [true, "updated"] : [false, "HTTP #{response.code}: #{response.body}"]
+      rescue => e
+        [false, "#{e.class}: #{e.message}"]
+      end
     end
   end
 end

data/lib/kettle/dev/version.rb

@@ -5,7 +5,7 @@ module Kettle
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = "2.5.14"
+      VERSION = "2.5.15"
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 2.5.14
+  version: 2.5.15
 platform: ruby
 authors:
 - Peter H. Boling
@@ -256,7 +256,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.3
+        version: 3.2.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -266,7 +266,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.3
+        version: 3.2.4
 - !ruby/object:Gem::Dependency
   name: stone_checksums
   requirement: !ruby/object:Gem::Requirement
@@ -276,7 +276,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.7
+        version: 1.0.8
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -286,7 +286,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.7
+        version: 1.0.8
 - !ruby/object:Gem::Dependency
   name: gitmoji-regex
   requirement: !ruby/object:Gem::Requirement
@@ -296,7 +296,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.10
+        version: 2.0.11
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -306,7 +306,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.10
+        version: 2.0.11
 description: "\U0001F372 Kettle::Dev is a meta tool from kettle-dev to streamline
   development and testing. Acts as a shim dependency, pulling in many other dependencies,
   to give you OOTB productivity with a RubyGem, or Ruby app project. Configures a
@@ -401,10 +401,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v2.5.14
-  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v2.5.14/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v2.5.15
+  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v2.5.15/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/2.5.14
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/2.5.15
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev