From 6668252942e391c403a882f9a19536ac5310028c Mon Sep 17 00:00:00 2001 From: Carlos Palhares Date: Mon, 26 Feb 2024 11:48:19 -0300 Subject: [PATCH] Add documentation on supporting multiple gem versions --- docs/README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/README.md b/docs/README.md index cfccda8c..9cf0414c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -128,6 +128,34 @@ For JS modules you will need to use gitpkg.now.sh to point to a subfolder within Releases will be published according to [Semantic Versioning](https://semver.org/) and it is the responsibility of the consumers to keep their application dependencies up to date. We recommend leveraging [renovatebot](https://github.com/renovatebot/renovate) 🤖 +## Supporting multiple gem versions + +To support multiple versions of a gem, and add a build to the pipeline, we use [Appraisal](https://github.com/thoughtbot/appraisal). The installation is simple, add `appraisals` to your gemspec as a development dependency and install it, then create an Appraisals file like the following to support multiple versions of rails: + +```ruby +appraise "rails-6-1" do + gem "rails", "6.1.7.7" +end + +appraise "rails-7-0" do + gem "rails", "7.0.8.1" +end +``` + +Run `bundle exec appraisal install`, which will: + +1. Create a `gemfiles` directory +1. Create a different `Gemfile` for each appraisal +1. Install each `Gemfile` bundler and generate a lock file + +The generated file often doesn't comply with `rubocop` defined rules, so you'll also want to run `bundle exec rubocop -A gemfiles`. + +Commit everything that was generated and you can now configure your github workflow. Add the gemfiles to the workflow arguments and they should run with each of the supported ruby versions. [`edgestitch`s workflow](.github/workflows/edgestitch.yml) is a good example. + +When updating gems it's important to remember to run `bundle exec appraisal bundle update `, so all your lock files are updated, but CI will remember you otherwise. + +To run *any* command targeting each of the Appraisals, just run `bundle exec appraisal `, for further information on Appraisal refer to [their documentation](https://github.com/thoughtbot/appraisal). + ## Maintenance 🚧 These packages are maintained by [Power's](https://github.com/powerhome) Heroes for Hire team.