appraisal2 3.1.3 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5697b5d78bd1b3ef5881a7e0bdce99ae1d786406652771d072f42e9d131c3d13
-  data.tar.gz: af85c613932969ec699dc5297a8dc4f7d3601d6ce898aa3d5750eba68d72febc
+  metadata.gz: 3ea29429e7d6b15deb35e182590258883e32ef6fecfe015c4d39d932fd4bcf96
+  data.tar.gz: 11bafabfd834fd35254e0777feaa1180be8c6f08b6ea89e92e3615cfefc2b392
 SHA512:
-  metadata.gz: ce5998ea1956670ef493180dcd23ec3026d9468ff87849424a6c491578be7260a277009cb1be39cb29ede5c68507116b61c0cb8473cbe520c5d426f547c55aff
-  data.tar.gz: eed7065a3a876f9416cdc12e6915bdc692c6327dacc13e027b400fc2a120ac06cc1d31b6afb574868c48b76f935212d5938a7adadfc0cd55d44a230cd2e4e57e
+  metadata.gz: 3289da2711ffa8539b1a34aba8346209e077d3fd86cf1bdb1b726bea7093bc8ae5e2f4bc62c8aa68e03783266f6c77bdb743a2dc550a4fb14fb3744714943957
+  data.tar.gz: bf38ac3a50e473895fb994b5e0e2abbcc437e18b1ec9a2f46acb232bfefce945eddbc5201c7cb1ef2ac739ed556ff3e1b1c1da739c32b3525f23bfff01c58a98

data/CHANGELOG.md

@@ -22,11 +22,73 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Changed
 
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [3.2.0] - 2026-07-18
+
+- TAG: [v3.2.0][3.2.0t]
+- COVERAGE: 91.00% -- 910/1000 lines in 29 files
+- BRANCH COVERAGE: 77.54% -- 183/236 branches in 29 files
+- 42.33% documented
+
+### Added
+
+- `appraisal generate`, `install`, `update`, `generate-install`, and
+  `generate-update` can now process appraisals in parallel with
+  `--appraisal-jobs` / `-n`, or `APPRAISAL_JOBS`. Appraisal-level
+  parallelism defaults to 2 workers; use `-n 1` to run serially. Bundler older
+  than 2.1 falls back to serial processing.
+
+### Changed
+
+- Full dependency updates now run `bundle update --all` to avoid Bundler's
+  deprecated implicit full-update form.
+- Acceptance specs now opt into expensive dummy-gem and bundle fixture setup
+  through metadata, and reuse a per-worker cached default fixture stage.
+- Generated CI workflows now cache `.rspec_status` and pass it to
+  `kettle-test` so `turbo_tests2` can balance workers with historical example
+  timings.
+- `generate-install` and `generate-update` now reuse the parsed Appraisals set
+  for their generate and install/update phases.
+
+- kettle-jem-template-20260716-001 - Shim gemspec manifests now include
+  `LICENSE.md` instead of nonexistent `LICENSE.txt`.
+- kettle-jem-template-20260716-002 - Generated gemspec manifests now ship fewer
+  repository-only files by default to reduce downstream distro packaging churn.
+
+### Fixed
+
+- Appraisal command execution now checks whether the `bundle` executable can
+  boot before falling back to RubyGems spec probing and Bundler installation,
+  preserving TruffleRuby's engine-shipped Bundler in isolated subprocesses.
+- Acceptance fixture Bundler selection now detects TruffleRuby's shipped
+  Bundler without reusing a newer Bundler activated by the appraised suite.
+- Acceptance fixture binstubs now pin the selected Bundler version before
+  loading generated `bin/bundle` handoff code.
+- Bundler-backed appraisal installs now set `BUNDLE_JOBS` explicitly so the
+  configured Appraisal job count also controls Bundler's installer worker
+  count in subprocesses.
+- JRuby and TruffleRuby workflows now correctly skip ordinary pull request
+  branches unless the branch targets `jruby/`, `truffleruby/`, or `engines/`.
+
+## [3.1.4] - 2026-07-01
+
+- TAG: [v3.1.4][3.1.4t]
+- COVERAGE: 90.28% -- 827/916 lines in 29 files
+- BRANCH COVERAGE: 79.31% -- 161/203 branches in 29 files
+- 42.25% documented
+
+### Changed
+
 - Clarified README Bundler path caching guidance and removed hard paragraph
   wraps from prose.
 
-### Deprecated
-
 ### Removed
 
 - Removed unused legacy root and fixture Gemfiles for Ruby 1.8, 2.0, and 2.1.
@@ -40,7 +102,7 @@ Please file a bug if you notice a violation of semantic versioning.
 - Disabled `ruby/setup-ruby` Bundler caching in the JRuby 9.3 workflow and
   run a serial Bundler install to avoid legacy fallback index failures.
 
-### Security
+- Package configured license files in gem release file lists.
 
 ## [3.1.3] - 2026-06-22
 
@@ -414,7 +476,11 @@ Please file a bug if you notice a violation of semantic versioning.
   - code coverage tracked with Coveralls, QLTY.sh, and the kettle-soup-cover gem
   - other minor fixes and improvements
 
-[Unreleased]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.3...HEAD
+[Unreleased]: https://github.com/appraisal-rb/appraisal2/compare/v3.2.0...HEAD
+[3.2.0]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.4...v3.2.0
+[3.2.0t]: https://github.com/appraisal-rb/appraisal2/releases/tag/v3.2.0
+[3.1.4]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.3...v3.1.4
+[3.1.4t]: https://github.com/appraisal-rb/appraisal2/releases/tag/v3.1.4
 [3.1.3]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.2...v3.1.3
 [3.1.3t]: https://github.com/appraisal-rb/appraisal2/releases/tag/v3.1.3
 [3.1.2]: https://github.com/appraisal-rb/appraisal2/compare/v3.1.1...v3.1.2

data/README.md

@@ -259,6 +259,21 @@ Use the command that matches the lifecycle you want:
 | `generate-install` | Yes | Yes, via install | First setup, or after intentional Appraisals changes |
 | `generate-update` | Yes | Yes, via update | Regenerate gemfiles, then update dependency locks |
 
+Appraisal2 can process appraisals in parallel with `--appraisal-jobs` / `-n`,
+or with `APPRAISAL_JOBS` when no CLI value is provided. `generate`,
+`generate-install`, and `generate-update` use this for generation. `install`,
+`update`, `generate-install`, and `generate-update` use it to fan out dependency
+resolution across appraisals. External commands run across all appraisals, such
+as `bundle exec appraisal rake test`, use `APPRAISAL_JOBS`. Appraisal-level
+parallelism defaults to 2 workers; use `-n 1` to run serially. When Appraisal2
+is running under Bundler older than 2.1, Appraisal2 falls back to serial
+processing because those Bundler versions do not provide the modern environment
+helpers used to isolate parallel Bundler subprocesses.
+
+Install commands keep `--jobs` / `-j` for the selected gem manager. With
+Bundler, `-j` controls `bundle install --jobs`, while `-n` controls how many
+appraisal gemfiles Appraisal2 processes at the same time.
+
 The deprecated rake task `rake appraisal:install` now delegates to `appraisal generate-install`, preserving its historical generate-and-install behavior while the CLI commands remain explicit.
 
 ### Command Options
@@ -270,12 +285,27 @@ Built-in dependency commands support the following options:
 | Option | Description |
 |--------|-------------|
 | `--gem-manager`, `-g` | Gem manager to use: `bundler` (default) or `ore`; applies to `install`, `update`, `generate-install`, and `generate-update` |
-| `--jobs`, `-j` | Install gems in parallel using the given number of workers; applies to `install` and `generate-install` |
+| `--appraisal-jobs`, `-n` | Process appraisals in parallel for `generate`, `install`, `update`, `generate-install`, and `generate-update` (default: 2; use `-n 1` for serial execution; Bundler < 2.1 falls back to serial processing) |
+| `--jobs`, `-j` | Pass a parallel job count to the selected gem manager; applies to `install` and `generate-install` |
 | `--retry` | Retry network and git requests that have failed; applies to `install` and `generate-install` (default: 1) |
 | `--without` | A space-separated list of groups to skip during installation; applies to `install` and `generate-install` |
 | `--full-index` | Run bundle install with the full-index argument; applies to `install` and `generate-install` |
 | `--path` | Install gems in the specified directory; applies to `install` and `generate-install` |
 
+```bash
+# Process two appraisals at a time, using the default Appraisal worker count
+bundle exec appraisal generate-install
+
+# Process four appraisals at a time
+bundle exec appraisal generate-install -n 4
+
+# Process two appraisals at a time, and give each Bundler install four jobs
+bundle exec appraisal generate-install -n 2 -j 4
+
+# Run Appraisal serially when parallel appraisal processing is not desired
+bundle exec appraisal generate-install -n 1
+```
+
 ### Using Commands with Named Appraisals
 
 #### Using Appraisal's built-in commands with named appraisals
@@ -752,7 +782,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-0.909-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.000-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/appraisal-rb/appraisal2/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/appraisal/appraisal.rb

@@ -94,7 +94,7 @@ module Appraisal
     end
 
     def gemfile_path
-      gemfile_root.mkdir unless gemfile_root.exist?
+      FileUtils.mkdir_p(gemfile_root)
 
       gemfile_root.join(gemfile_name).to_s
     end

data/lib/appraisal/cli.rb

@@ -2,17 +2,27 @@
 
 require "thor"
 require "fileutils"
+require "thread"
 
 module Appraisal
   class CLI < Thor
+    MINIMUM_PARALLEL_BUNDLER_VERSION = Gem::Version.new("2.1.0")
+
     default_task :install
     map ["-v", "--version"] => "version"
+    map "generate-install" => "generate_install"
+    map "generate-update" => "generate_update"
 
     class_option "gem-manager",
       :aliases => "-g",
       :type => :string,
       :default => "bundler",
       :desc => "Gem manager to use for install/update (bundler or ore)"
+    class_option "appraisal-jobs",
+      :aliases => "-n",
+      :type => :numeric,
+      :banner => "SIZE",
+      :desc => "Process appraisals in parallel using the given number of workers."
 
     class << self
       # Override help command to print out usage
@@ -59,7 +69,7 @@ module Appraisal
       :type => :numeric,
       :default => 1,
       :banner => "SIZE",
-      :desc => "Install gems in parallel using the given number of workers."
+      :desc => "Pass the given parallel job count to the selected gem manager."
     method_option "retry",
       :type => :numeric,
       :default => 1,
@@ -78,11 +88,7 @@ module Appraisal
         "Bundler will remember this option."
 
     def install
-      install_options = options.to_h
-      AppraisalFile.each do |appraisal|
-        appraisal.install(install_options)
-        appraisal.relativize
-      end
+      install_appraisals(appraisals, install_options, appraisal_jobs(options))
     end
 
     desc "generate-install", "Generate gemfiles, then resolve and install dependencies for each appraisal"
@@ -91,7 +97,7 @@ module Appraisal
       :type => :numeric,
       :default => 1,
       :banner => "SIZE",
-      :desc => "Install gems in parallel using the given number of workers."
+      :desc => "Pass the given parallel job count to the selected gem manager."
     method_option "retry",
       :type => :numeric,
       :default => 1,
@@ -109,15 +115,14 @@ module Appraisal
       :desc => "Install gems in the specified directory. " \
         "Bundler will remember this option."
     def generate_install
-      invoke(:generate, [], {})
-      invoke(:install, [], options.to_h)
+      appraisal_list = appraisals
+      generate_appraisals(appraisal_list, appraisal_jobs(options))
+      install_appraisals(appraisal_list, install_options, appraisal_jobs(options))
     end
 
     desc "generate", "Generate a gemfile for each appraisal"
     def generate
-      AppraisalFile.each do |appraisal|
-        appraisal.write_gemfile
-      end
+      generate_appraisals(appraisals, appraisal_jobs(options))
     end
 
     desc "clean", "Remove all generated gemfiles and lockfiles from gemfiles folder"
@@ -127,17 +132,14 @@ module Appraisal
 
     desc "update [LIST_OF_GEMS]", "Update dependencies for each generated appraisal gemfile"
     def update(*gems)
-      gem_manager = options["gem-manager"] || options[:gem_manager]
-      update_options = gem_manager ? {:gem_manager => gem_manager} : {}
-      AppraisalFile.each do |appraisal|
-        appraisal.update(gems, update_options)
-      end
+      update_appraisals(appraisals, gems, update_options, appraisal_jobs(options))
     end
 
     desc "generate-update [LIST_OF_GEMS]", "Generate gemfiles, then update dependencies for each appraisal"
     def generate_update(*gems)
-      invoke(:generate, [], {})
-      update(*gems)
+      appraisal_list = appraisals
+      generate_appraisals(appraisal_list, appraisal_jobs(options))
+      update_appraisals(appraisal_list, gems, update_options, appraisal_jobs(options))
     end
 
     desc "list", "List the names of the defined appraisals"
@@ -152,7 +154,99 @@ module Appraisal
 
     private
 
+    def appraisals
+      AppraisalFile.new.appraisals
+    end
+
+    def generate_appraisals(appraisal_list, jobs)
+      each_appraisal(appraisal_list, jobs) do |appraisal|
+        appraisal.write_gemfile
+      end
+    end
+
+    def install_appraisals(appraisal_list, install_options, jobs)
+      each_appraisal(appraisal_list, jobs) do |appraisal|
+        appraisal.install(install_options.dup)
+        appraisal.relativize
+      end
+    end
+
+    def update_appraisals(appraisal_list, gems, update_options, jobs)
+      each_appraisal(appraisal_list, jobs) do |appraisal|
+        appraisal.update(gems, update_options.dup)
+      end
+    end
+
+    def each_appraisal(appraisal_list, jobs)
+      jobs = worker_count(jobs, appraisal_list.length)
+      return appraisal_list.each { |appraisal| yield(appraisal) } if jobs <= 1
+
+      queue = Queue.new
+      errors = []
+      mutex = Mutex.new
+
+      appraisal_list.each { |appraisal| queue << appraisal }
+      jobs.times { queue << nil }
+
+      # rubocop:disable ThreadSafety/NewThread
+      threads = Array.new(jobs) do
+        Thread.new do
+          while (appraisal = queue.pop)
+            begin
+              yield(appraisal)
+            rescue Exception => error # rubocop:disable Lint/RescueException
+              mutex.synchronize { errors << error }
+            end
+          end
+        end
+      end
+      # rubocop:enable ThreadSafety/NewThread
+      threads.each(&:join)
+
+      raise errors.first unless errors.empty?
+    end
+
+    def worker_count(jobs, item_count)
+      jobs = jobs.to_i
+      jobs = 1 if jobs < 1
+      jobs = 1 unless parallel_appraisals_supported?
+      return jobs if item_count.zero?
+
+      [jobs, item_count].min
+    end
+
+    def parallel_appraisals_supported?
+      # Parallel install/update workers depend on Appraisal::Command being able
+      # to build independent Bundler subprocess environments. Bundler 2.1 is the
+      # floor for the modern original_env/unbundled_env API split that replaced
+      # clean_env, so older Bundler versions keep the historical serial path.
+      bundler_version = Gem::Specification.find_all_by_name("bundler").map(&:version).max
+      return false unless bundler_version
+
+      bundler_version >= MINIMUM_PARALLEL_BUNDLER_VERSION
+    end
+
+    def appraisal_jobs(command_options)
+      command_options["appraisal-jobs"] || command_options[:appraisal_jobs] || ENV["APPRAISAL_JOBS"] || 2
+    end
+
+    def install_options
+      options.to_h.reject { |key, _value| key.to_s == "appraisal-jobs" }
+    end
+
+    def update_options
+      gem_manager = options["gem-manager"] || options[:gem_manager]
+      gem_manager ? {:gem_manager => gem_manager} : {}
+    end
+
     def method_missing(name, *args)
+      case name.to_s
+      when "generate-install"
+        return generate_install
+      when "generate-update"
+        return generate_update(*args)
+      end
+
       matching_appraisal = AppraisalFile.new.appraisals.detect do |appraisal|
         appraisal.name == name.to_s
       end
@@ -213,7 +307,7 @@ module Appraisal
           Command.new(actual_args, :gemfile => matching_appraisal.gemfile_path).run
         end
       else
-        AppraisalFile.each do |appraisal|
+        each_appraisal(AppraisalFile.new.appraisals, appraisal_jobs(options)) do |appraisal|
           Command.new(ARGV, :gemfile => appraisal.gemfile_path).run
         end
       end
@@ -240,6 +334,17 @@ module Appraisal
           options[:jobs] = Regexp.last_match(1).to_i
         when /^-j(\d+)$/
           options[:jobs] = Regexp.last_match(1).to_i
+        when /^-j$/
+          options[:jobs] = args[index + 1].to_i
+          skip_next = true
+        when /^--appraisal-jobs=\d+$/
+          nil
+        when /^--appraisal-jobs$/
+          skip_next = true
+        when /^-n\d+$/
+          nil
+        when /^-n$/
+          skip_next = true
         when /^--retry=(\d+)$/
           options[:retry] = Regexp.last_match(1).to_i
         when /^--without=(.+)$/
@@ -271,6 +376,10 @@ module Appraisal
           # Next arg should be the value
           options[:gem_manager] = args[index + 1]
           skip_next = true
+        when /^--appraisal-jobs$/
+          skip_next = true
+        when /^-n$/
+          skip_next = true
         when /^-/
           # Other options are not gems, but we don't handle them all here
           # For now, just skip them to be safe if they start with -