kettle-family 1.3.26 → 1.3.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cd05963542f86f54bc825842b8f73649a7520e61ddc695c505a6d19b3897581
-  data.tar.gz: c4fc9a81de19c42aa0265fa04d255dc4f40ddcd5485aff3eec57b44647a26ddd
+  metadata.gz: 68173e6324c65cec8417346451236a9cf2dd3d94fc4e91919676f0c611910042
+  data.tar.gz: 3579c4ad1ab8f299fd1225396c91e4b4c8ff51bfa8f81c6f73410ec1c4277a3c
 SHA512:
-  metadata.gz: 97f87951b90ef59a674a55678be2af49d853f874d221297f3dd8661311400997f5430b9dd9b9e4ce88b32c543baf0d60977b975602a2d01c54f3c0217442c495
-  data.tar.gz: d25120f0322dc957334262f218c07ad8be84669d3632ddcc33aecc7e4f9217407246489b3bcca24aae5e26a43618bc8be888fbba0a3278b8920f6985468be242
+  metadata.gz: 47009c3a27af69f4225d2ca340357ee80481be9e37c4ff73393abf2e6816bce67d084b06f1faddf332e983f4e363de72d2b67bd83e9f910d437f203f7994fca9
+  data.tar.gz: bad1f7ecc474afec6feaf144b489f2f6d702cf9f3d1fa21b237bf6171324d4db4d8dae5034ab1f71678e505e27aa1d4862413185e52a1946ee7bbe7c5a0c3614

data/CHANGELOG.md

@@ -30,6 +30,19 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.3.27] - 2026-10-20
+
+- TAG: [v1.3.27][1.3.27t]
+- COVERAGE: 93.04% -- 7460/8018 lines in 44 files
+- BRANCH COVERAGE: 77.50% -- 2994/3863 branches in 44 files
+- 37.45% documented
+
+### Fixed
+
+- Preserve branch identity in template reports and exact-branch resume hints, and support MEMBER@BRANCH selection and resume targets.
+
+- Retry template preparation once when Bundler reports a cached gemspec evaluating to nil.
+
 ## [1.3.26] - 2026-10-20
 
 - TAG: [v1.3.26][1.3.26t]
@@ -3165,7 +3178,9 @@ Please file a bug if you notice a violation of semantic versioning.
 - Fixed CI load failures on engines without compatible `pty` support by falling back to Open3 for interactive release commands.
 - Fixed Ruby 3.2 version-bump support by loading Prism lazily and wiring the Prism gem only for MRI versions that need it.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.26...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.27...HEAD
+[1.3.27]: https://github.com/kettle-dev/kettle-family/compare/v1.3.26...v1.3.27
+[1.3.27t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.27
 [1.3.26]: https://github.com/kettle-dev/kettle-family/compare/v1.3.25...v1.3.26
 [1.3.26t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.26
 [1.3.25]: https://github.com/kettle-dev/kettle-family/compare/v1.3.24...v1.3.25

data/README.md

@@ -1225,7 +1225,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-7.956-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-8.018-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-family/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/lib/kettle/family/cli.rb

@@ -49,7 +49,7 @@ module Kettle
 
       module SelectionOptions
         def self.included(base)
-          base.option :only, value: {type: String, usage: "MEMBERS"}, desc: "Select comma-separated members, or release-state tokens: unreleased/unrel, prepared/prep, pending/pend, bump"
+          base.option :only, value: {type: String, usage: "MEMBERS"}, desc: "Select comma-separated members or branch targets (MEMBER@BRANCH), or release-state tokens: unreleased/unrel, prepared/prep, pending/pend, bump"
           base.option :exclude, value: {type: String, usage: "MEMBERS"}, desc: "Exclude comma-separated members"
           base.option :start_at, long: "--start-at", value: {type: String, usage: "MEMBER[@BRANCH]"}, desc: "Select from member through the end of order"
         end
@@ -823,7 +823,7 @@ module Kettle
       def build_report(command, options)
         config = Config.load(root: options[:root], path: options[:config])
         start_at = parse_start_at(options[:start_at])
-        Selection.validate_positional_start_at!(command, start_at.member)
+        Selection.validate_positional_start_at!(command, start_at.member, branch: start_at.branch)
         effective_only = default_only_filter(command: command, only: options[:only])
         discovery = Discovery.new(
           config: config,
@@ -841,6 +841,7 @@ module Kettle
           Orderer.new(members: members, mode: config.order_mode, hints: config.order_hints).ordered(allow_cycles: command == "release-state")
         end
         state_event_tape = release_state_event_tape(command: command, config: config, options: options)
+        branch_selection = template_branch_selection(command: command, config: config, members: ordered, only: effective_only)
         Selection.validate_release_state_only_filter!(effective_only)
         release_state_results = release_state_results_for_selection(
           command: command,
@@ -855,6 +856,7 @@ module Kettle
           members: ordered,
           release_state_results: release_state_results
         ).apply(only: effective_only, exclude: options[:exclude], start_at: start_at.member)
+        options = options.merge(template_branch_selection: branch_selection)
         result_members = selected
         display_members = display_members_for(command: command, config: config, members: ordered, selected_members: selected)
         display_selected_members = display_members_for(command: command, config: config, members: selected, selected_members: selected)
@@ -889,7 +891,7 @@ module Kettle
           config_path: config.path,
           branch_lanes: config.branch_lanes,
           release_target_branches: release_target_branches(command: command, config: config, start_at: start_at),
-          member_release_target_branches: member_release_target_branches(command: command, members: selected, config: config, start_at: start_at),
+          member_release_target_branches: member_release_target_branches(command: command, members: selected, config: config, start_at: start_at, branch_selection: branch_selection),
           release_mode: release_mode(command: command, options: options),
           release_resume_arguments: release_resume_arguments(command: command, options: options),
           command: command,
@@ -955,7 +957,32 @@ module Kettle
         names = only.to_s.split(",").map(&:strip).reject(&:empty?)
         return nil if names.empty? || names.any? { |name| Selection.status_token?(name) }
 
-        names
+        Selection.member_names(only)
+      end
+
+      def template_branch_selection(command:, config:, members:, only:)
+        selectors = Selection.branch_selectors(only)
+        unless command == "template"
+          raise Error, "MEMBER@BRANCH selectors are only supported for template" unless selectors.empty?
+
+          return {}
+        end
+        return {} if selectors.empty?
+
+        by_name = members.to_h { |member| [member.name, member] }
+        selectors.group_by(&:first).transform_values do |member_selectors|
+          member_name = member_selectors.first.first
+          member = by_name[member_name]
+          member_config = member && member_release_config(member: member, config: config)
+          branches = member_config && BranchTargetConfig.branch_targets_for(command, member_config.release_target_branches)
+          raise Error, "member #{member_name.inspect} has no template branch targets" unless branches
+
+          selected_branches = member_selectors.map(&:last).uniq
+          unknown = selected_branches - branches
+          raise Error, "unknown branch target(s) for #{member_name}: #{unknown.join(", ")}" unless unknown.empty?
+
+          selected_branches
+        end
       end
 
       def display_members_for(command:, config:, members:, selected_members:)
@@ -1031,6 +1058,7 @@ module Kettle
           bex_args: options[:bex_args],
           start_member: start_at.member,
           start_branch: start_at.branch,
+          template_branch_selection: options[:template_branch_selection],
           event_tape: state_event_tape,
           release_state_results: release_state_results
         ).results
@@ -1560,10 +1588,18 @@ module Kettle
         slice_branch_targets(branch_targets, start_at.branch)
       end
 
-      def member_release_target_branches(command:, members:, config:, start_at:)
+      def member_release_target_branches(command:, members:, config:, start_at:, branch_selection: {})
         members.each_with_object({}) do |member, memo|
           member_config = member_release_config(member: member, config: config)
-          memo[member.name] = member_branch_targets(command: command, member: member, member_config: member_config, start_at: start_at) if member_config
+          next unless member_config
+
+          branches = if command == "template" && branch_selection.key?(member.name)
+            branch_selection.fetch(member.name)
+          else
+            member_branch_targets(command: command, member: member, member_config: member_config, start_at: start_at)
+          end
+          branches = slice_branch_targets(branches, start_at.branch) if command == "template" && start_at.branch && start_at.member == member.name
+          memo[member.name] = branches
         end
       end
 

data/lib/kettle/family/report.rb

@@ -122,7 +122,7 @@ module Kettle
 
         lines << "results:"
         visible_results.each do |result|
-          lines << "  #{result_state(result)} #{result.member_name} #{result.phase} #{result.reason || ""}".rstrip
+          lines << "  #{result_state(result)} #{result_identity(result)} #{result.phase} #{result.reason || ""}".rstrip
           append_result_stdout(lines, result)
           append_indented_output(lines, result.stderr) if !result.ok? && !result.stderr.to_s.empty?
           resume_hint = resume_hint_for(result)
@@ -436,20 +436,39 @@ module Kettle
       end
 
       def selected_names
-        selected_members.map(&:name)
+        return selected_members.map(&:name) unless branch_stack_template?
+
+        selected_members.flat_map do |member|
+          branches = member_release_target_branches[member.name]
+          branches ? branches.map { |branch| "#{member.name}@#{branch}" } : [member.name]
+        end
       end
 
       def selected_member_results
         return {} unless member_result_command?
 
+        selected_identities = selected_names
         built = visible_results.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |result, memo|
-          next unless selected_names.include?(result.member_name)
+          identity = result_identity(result)
+          next unless selected_identities.include?(identity)
 
-          memo[result.member_name] << result
+          memo[identity] << result
         end
         built.sort.to_h
       end
 
+      def result_identity(result)
+        if branch_stack_template? && result.branch && member_release_target_branches.fetch(result.member_name, []).include?(result.branch)
+          "#{result.member_name}@#{result.branch}"
+        else
+          result.member_name
+        end
+      end
+
+      def branch_stack_template?
+        command == "template" && !member_release_target_branches.empty?
+      end
+
       def summary_succeeded
         selected_member_results.filter_map do |member_name, member_results|
           next if member_results.empty?
@@ -479,7 +498,7 @@ module Kettle
         # Alphabetical summary lists, regardless of parallel completion order.
         visible_results.reject(&:ok?).sort_by.with_index { |result, index| [result.member_name, index] }.map do |result|
           {
-            "member" => result.member_name,
+            "member" => result_identity(result),
             "phase" => result.phase,
             "reason" => result.reason || "command failed"
           }
@@ -511,9 +530,9 @@ module Kettle
 
       def summary_ran_member_names
         if command == "template"
-          failed = visible_results.reject(&:ok?).map(&:member_name)
-          templated = selected_member_results.filter_map do |member_name, member_results|
-            member_name if member_results.any? { |result| result.phase == "template" }
+          failed = visible_results.reject(&:ok?).map { |result| result_identity(result) }
+          templated = selected_member_results.filter_map do |identity, member_results|
+            identity if member_results.any? { |result| result.phase == "template" }
           end
           return (failed + templated).uniq
         end
@@ -778,7 +797,7 @@ module Kettle
         return "kettle-family #{command}" if family_root_phase?(result.phase)
         # A positional --start-at would silently drop pending members that are
         # ordered ahead of this one, so wave-dispatched commands resume by name.
-        return "kettle-family #{command} --only #{result.member_name}" if non_positional_dispatch?
+        return "kettle-family #{command} --only #{result_identity(result)}" if non_positional_dispatch?
 
         "kettle-family #{command} --start-at #{result.member_name}"
       end

data/lib/kettle/family/selection.rb

@@ -41,13 +41,18 @@ module Kettle
       # than letting it silently drop members. Mirrors the class-method validation
       # convention used by validate_release_state_only_filter! so callers in the CLI
       # do not have to know which commands are affected.
-      def self.validate_positional_start_at!(command, start_at)
+      def self.validate_positional_start_at!(command, start_at, branch: nil)
         return if start_at.nil? || start_at.to_s.empty?
         return unless non_positional_dispatch?(command)
+        return if command == "template" && !branch.to_s.empty?
 
+        detail = if command == "template"
+          "Use --only #{start_at} (or the prior report's retry hint), or MEMBER@BRANCH for a branch-stack resume."
+        else
+          "Use --only #{start_at} (or the resume hint from the previous report) instead."
+        end
         raise Error, "--start-at is not supported for #{command}: members are dispatched in dependency " \
-                     "waves, so a positional resume would silently skip members that never ran. " \
-                     "Use --only #{start_at} (or the resume hint from the previous report) instead."
+                     "waves, so a positional resume would silently skip members that never ran. #{detail}"
       end
 
       def self.status_tokens
@@ -73,6 +78,20 @@ module Kettle
         end.map(&:branch).compact.uniq
       end
 
+      def self.member_names(only)
+        Array(only.to_s.split(",").map(&:strip).reject(&:empty?)).map { |selector| selector.split("@", 2).first }
+      end
+
+      def self.branch_selectors(only)
+        only.to_s.split(",").map(&:strip).reject(&:empty?).filter_map do |selector|
+          member_name, branch = selector.split("@", 2)
+          next unless branch
+          raise Error, "invalid branch selector #{selector.inspect}; expected MEMBER@BRANCH" if member_name.empty? || branch.empty?
+
+          [member_name, branch]
+        end
+      end
+
       def self.validate_release_state_only_filter!(only)
         names = only.to_s.split(",").map(&:strip).reject(&:empty?)
         status_tokens = names.select { |name| status_token?(name) }
@@ -112,9 +131,10 @@ module Kettle
           return select_release_state_status(selected, status_tokens)
         end
 
-        unknown = names - members.map(&:name)
+        unknown = self.class.member_names(only) - members.map(&:name)
         raise Error, "unknown member(s): #{unknown.join(", ")}" unless unknown.empty?
 
+        names = self.class.member_names(only)
         selected.select { |candidate| names.include?(candidate.name) }
       end
 

data/lib/kettle/family/version.rb

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

data/lib/kettle/family/workflow.rb

@@ -107,8 +107,9 @@ module Kettle
       RUBY
       REGISTRY_WAIT_ATTEMPTS = 15
       REGISTRY_WAIT_INTERVAL_SECONDS = 15
+      TEMPLATE_GEMSPEC_RETRY_DELAY_SECONDS = 0.25
 
-      def initialize(command:, config:, members:, family_members: nil, execute: false, accept: true, commit: true, allow_dirty: false, autostash: true, template_cleanup: true, publish: false, push: false, tag: false, start_step: nil, skip_steps: nil, fast_recovery: nil, fast_recovery_members: nil, skip_ci: false, skip_changelog: false, skip_appraisals: false, local_ci: false, continue_ci_failures: false, ci_workflows: nil, skip_bundle_audit: false, skip_remotes: nil, required_remotes: nil, auto_dependency_floors: nil, validate_ci_bundles: nil, gha_sha_pins_upgrade: "patch", gha_sha_pins_check: false, gha_sha_pins_ttl_days: nil, env_overrides: {}, debug: false, verbose: false, gem_signing_password: nil, secrets_provider: nil, jobs: nil, progress_io: nil, reset_target: nil, bup_args: [], bex_args: [], start_member: nil, start_branch: nil, release_state_results: nil, event_tape: nil, **options)
+      def initialize(command:, config:, members:, family_members: nil, execute: false, accept: true, commit: true, allow_dirty: false, autostash: true, template_cleanup: true, publish: false, push: false, tag: false, start_step: nil, skip_steps: nil, fast_recovery: nil, fast_recovery_members: nil, skip_ci: false, skip_changelog: false, skip_appraisals: false, local_ci: false, continue_ci_failures: false, ci_workflows: nil, skip_bundle_audit: false, skip_remotes: nil, required_remotes: nil, auto_dependency_floors: nil, validate_ci_bundles: nil, gha_sha_pins_upgrade: "patch", gha_sha_pins_check: false, gha_sha_pins_ttl_days: nil, env_overrides: {}, debug: false, verbose: false, gem_signing_password: nil, secrets_provider: nil, jobs: nil, progress_io: nil, reset_target: nil, bup_args: [], bex_args: [], start_member: nil, start_branch: nil, template_branch_selection: {}, release_state_results: nil, event_tape: nil, **options)
         @command = command
         @config = config
         @members = members
@@ -162,6 +163,7 @@ module Kettle
         @bex_args = bex_args
         @start_member = start_member
         @start_branch = start_branch
+        @template_branch_selection = template_branch_selection
         @release_state_results = Array(release_state_results)
         @event_tape = event_tape
         @template_commit_mutex = Mutex.new
@@ -1634,7 +1636,10 @@ module Kettle
       # linked worktrees avoids repeatedly switching the primary checkout and
       # allows the branch stack to use the requested template worker budget.
       def template_branch_worktree_results(member:, member_config:)
-        branches = BranchTargetConfig.branch_targets_for(command, member_config.release_target_branches)
+        branches = @template_branch_selection.fetch(member.name) do
+          BranchTargetConfig.branch_targets_for(command, member_config.release_target_branches)
+        end
+        branches = slice_branch_targets(branches, start_branch) if start_member == member.name && start_branch
         return [] if branches.empty?
 
         entries = []
@@ -5595,6 +5600,13 @@ module Kettle
         commit_normalized_lockfiles(branch_members: [member], runner: runner, memo: memo, reason: "reset", force: true)
       end
 
+      def transient_cached_gemspec_failure?(result)
+        return false unless execute && result && !result.ok?
+
+        output = [result.stdout, result.stderr].join("\n")
+        output.include?("Bundler::GemspecError") && output.match?(/isn't a Gem::Specification \(NilClass instead\)/)
+      end
+
       def recoverable_bundle_failure?(result)
         return false unless execute && !result.ok?
 
@@ -5794,6 +5806,19 @@ module Kettle
           command: template_prepare_command(member),
           env: template_prepare_env(wave_jobs: wave_jobs, member: member)
         )
+        if transient_cached_gemspec_failure?(result)
+          sleep(TEMPLATE_GEMSPEC_RETRY_DELAY_SECONDS)
+          retry_result = runner.call(
+            member: member,
+            phase: "prepare_template_dependencies_retry",
+            command: template_prepare_command(member),
+            env: template_prepare_env(wave_jobs: wave_jobs, member: member)
+          )
+          unless retry_result.ok?
+            retry_result.stderr = [result.stderr, "Initial attempt failed with a transient cached-gemspec error.", retry_result.stderr].compact.reject(&:empty?).join("\n")
+          end
+          result = retry_result
+        end
         if recoverable_bundle_failure?(result)
           recover_template_lockfiles(
             member: member,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-family
 version: !ruby/object:Gem::Version
-  version: 1.3.26
+  version: 1.3.27
 platform: ruby
 authors:
 - Peter H. Boling
@@ -567,10 +567,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-family.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.3.26
-  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.3.26/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.3.27
+  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.3.27/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-family/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.3.26
+  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.3.27
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-family/wiki
   news_uri: https://www.railsbling.com/tags/kettle-family