Appraisal::Matrix

Sometimes our gems are using dependencies which have consistent major/minor versions released with breaking changes, and we want to ensure compatibility by explicitly testing against the array of versions.

Appraisal::Matrix provides an interface for testing against that entire array without repetition in the Appraisals file.

Installation

TODO: Replace UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.

Install the gem and add to the application's Gemfile by executing:

$ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG

Usage

Single gem usage

The most common use-case is wanting to test compatibility with all supported versions of Rails.

# Appraisals
# frozen_string_literal: true

require "appraisal/matrix"

appraisal_matrix(activesupport: "6.1")

Then run

$ bundle exec appraisal install

A gemfile like the one below will be created for each major/minor version of activesupport starting with 6.1.

# activesupport_6_1.gemfile
# This file was generated by Appraisal

gem "activesupport", "~> 6.1.0"

Passing blocks to Appraisal

Any block passed to appraisal_matrix will be run in each individual appraisal. For example, if you rely on removing gems using appraisal you can pass the exact same block to appraisal_matrix.

appraisal_matrix(activesupport: "6.1") do
  remove_gem 'test_after_commit'
end

Block arguments

If you would like to setup conditional logic based off of the versions of the gems in the matrix, you can pass a block with arguments to appraisal_matrix.

appraisal_matrix(activesupport: "6.1") do |activesupport:|
  # activesupport <Gem::Version>
  if activesupport < "7"
    remove_gem 'test_after_commit'
  end
end

Appraising more than one Gem

You can also pass more than one gem to appraisal_matrix to create a matrix of all combinations of the specified gems.

appraisal_matrix(activesupport: "6.1", sidekiq: "7.0")

Version argument options

In addition to specifying the minimum requested version, users will be able to make additional version requests.

Additional version restrictions

Include additional version boundaries. Either include the requirement strings as an array or pass the versions key to the options hash.

appraisal_matrix(activesupport: [">= 6.1", "< 7.1"])
appraisal_matrix(activesupport: ["~> 6.0", "!= 6.1.0"])
appraisal_matrix(activesupport: { versions: ["> 6.1.1"] })

Version step

The default operation is to test against each minor version. You can choose to be more or less inclusive when necessary.

Only test the latest release of each major version.

appraisal_matrix(activesupport: { versions: [">= 6.1", "< 7.1"], step: :major })

Or include all patch releases

appraisal_matrix(activesupport: { versions: [">= 6.1", "< 7.1"], step: :patch })

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/invoca/appraisal-matrix.

License

The gem is available as open source under the terms of the MIT License.

Invoca/appraisal-matrix