chore: document knapsack to knapsack_pro

Co-authored-by: Artur Trzop <[email protected]>

Author: 3v0k4

.github/assets/knapsack-diamonds.png

@@ -0,0 +1,78 @@
+# Migration steps: from Knapsack to Knapsack Pro
+
+Follow these steps to migrate from `knapsack` to `knapsack_pro` in 10 minutes.
+
+Commands are provided to help you with each step.
+
+> [!TIP]
+> On Linux, you need to remove the `''` part from the `sed` commands. Also, you can ignore the `sed: no input files` warning that is printed when there's no substitution to perform.
+
+## Steps
+
+- [ ] Remove the `knapsack` gem:
+   ```bash
+   bundle remove knapsack
+   ```
+
+- [ ] Remove `Knapsack.load_tasks` from the `Rakefile` if present:
+   ```bash
+   sed -i '' '/Knapsack\.load_tasks/d' Rakefile
+   ```
+
+- [ ] Replace `require "knapsack"` with `require "knapsack_pro"`:
+   ```bash
+   grep --files-with-matches --recursive "require.*knapsack" . | xargs sed -i '' "s/'knapsack'/'knapsack_pro'/g"
+   grep --files-with-matches --recursive "require.*knapsack" . | xargs sed -i '' 's/"knapsack"/"knapsack_pro"/g'
+   ```
+
+- [ ] Remove the following code from the test runner configuration:
+   ```diff
+   - Knapsack.tracker.config({
+   -  enable_time_offset_warning: true,
+   -  time_offset_in_seconds: 30
+   - })
+
+   - Knapsack.report.config({
+   -  test_file_pattern: 'spec/**{,/*/**}/*_spec.rb', # ⬅️ Take note of this one for later
+   -  report_path: 'knapsack_custom_report.json'
+   - })
+   ```
+
+- [ ] Replace `Knapsack` with `KnapsackPro`:
+   ```bash
+   grep --files-with-matches --recursive "Knapsack\." . | xargs sed -i '' 's/Knapsack\./KnapsackPro./g'
+   grep --files-with-matches --recursive "Knapsack::" . | xargs sed -i '' 's/Knapsack::/KnapsackPro::/g'
+   ```
+
+- [ ] Rename `KnapsackPro::Adapters::RspecAdapter` to `KnapsackPro::Adapters::RSpecAdapter`:
+   ```bash
+   grep --files-with-matches --recursive "KnapsackPro::Adapters::RspecAdapter" . | xargs sed -i '' 's/RspecAdapter/RSpecAdapter/g'
+   ```
+
+- [ ] Remove any line that mentions `KNAPSACK_GENERATE_REPORT` or `KNAPSACK_REPORT_PATH`:
+   ```bash
+   grep --files-with-matches --recursive "KNAPSACK_GENERATE_REPORT" . | xargs sed -i '' '/KNAPSACK_GENERATE_REPORT/d'
+   grep --files-with-matches --recursive "KNAPSACK_REPORT_PATH" . | xargs sed -i '' '/KNAPSACK_REPORT_PATH/d'
+   ```
+
+- [ ] Rename ENVs from `KNAPSACK_X` to `KNAPSACK_PRO_X`:
+   ```bash
+   grep --files-with-matches --recursive "KNAPSACK_" . | xargs sed -i '' 's/KNAPSACK_/KNAPSACK_PRO_/g'
+   ```
+
+- [ ] Remove all the reports:
+   ```bash
+   rm knapsack_*_report.json
+   ```
+
+- [ ] [Configure Knapsack Pro](https://docs.knapsackpro.com/knapsack_pro-ruby/guide/)
+
+- [ ] Ensure all the CI commands are updated:
+   ```bash
+   grep --files-with-matches --recursive "knapsack:spinach" . | xargs sed -i '' 's/knapsack:spinach/knapsack_pro:spinach/g'
+   grep --files-with-matches --recursive "knapsack:" . | xargs sed -i '' 's/knapsack:/knapsack_pro:queue:/g'
+   grep --files-with-matches --recursive "CI_NODE_TOTAL" . | xargs sed -i '' 's/CI_NODE_TOTAL/KNAPSACK_PRO_CI_NODE_TOTAL/g'
+   grep --files-with-matches --recursive "CI_NODE_INDEX" . | xargs sed -i '' 's/CI_NODE_INDEX/KNAPSACK_PRO_CI_NODE_INDEX/g'
+   ```
+
+- [ ] If you removed `test_file_pattern` when deleting `Knapsack.report.config`, use [`KNAPSACK_PRO_TEST_FILE_PATTERN`](https://docs.knapsackpro.com/ruby/reference/#knapsack_pro_test_file_pattern) instead

MIGRATE_TO_KNAPSACK_PRO.md

@@ -1,36 +1,44 @@
-# knapsack gem
+# Knapsack
 
-Knapsack splits tests evenly across parallel CI nodes to run fast CI build and save you time.
+<p align="center">
+  <a href="https://knapsackpro.com?utm_source=github&utm_medium=readme&utm_campaign=knapsack_gem&utm_content=hero_logo">
+    <img alt="Knapsack" src="./.github/assets/knapsack-diamonds.png" width="300" height="300" style="max-width: 100%;" />
+  </a>
+</p>
 
-|                                              | knapsack gem | knapsack_pro gem |
-| -------------------------------------------- | ------------ | ---------------- |
-| __Is free__                                  | ✓ Yes        | ✓ Yes, [free plan](https://knapsackpro.com?utm_source=github&utm_medium=readme&utm_campaign=knapsack_gem&utm_content=free_plan) |
-| __Regular Mode - a static tests split__      | ✓ Yes        | ✓ Yes |
-| __Queue Mode - a dynamic tests split__ <br>([ensures all CI nodes finish work at the same time](https://docs.knapsackpro.com/2020/how-to-speed-up-ruby-and-javascript-tests-with-ci-parallelisation))       | No           | ✓ Yes |
-| __Auto [split slow RSpec test file](https://knapsackpro.com/faq/question/how-to-split-slow-rspec-test-files-by-test-examples-by-individual-it) between parallel CI nodes__ <br>(a single test file can be auto split by test examples between parallel jobs) | No           | ✓ Yes |
-| Tracking tests timing per commit, branch     | No           | ✓ Yes |
-| Support for other programming languages      | No           | ✓ Yes |
-| Support for CI providers                     | limited      | ✓ Yes |
-| __Installation README__                      | [Install README](http://docs.knapsackpro.com/ruby/knapsack) | [Install README](https://docs.knapsackpro.com) |
+<h3 align="center">Speed up your tests</h3>
+<p align="center">Run your 1-hour test suite in 2 minutes with optimal parallelisation on your existing CI infrastructure</p>
 
-[Features of knapsack vs knapsack_pro Ruby gem](https://knapsackpro.com/features/ruby_knapsack_pro_vs_knapsack?utm_source=github&utm_medium=readme&utm_campaign=knapsack_gem&utm_content=ruby_knapsack_pro_vs_knapsack)
+---
 
-# Do you use Heroku?
+<div align="center">
+  <a href="https://rubygems.org/gems/knapsack">
+    <img alt="Gem Version" src="https://badge.fury.io/rb/knapsack.svg" />
+  </a>
+</div>
 
-Do you know Knapsack Pro Ruby gem is available as Heroku add-on? It works with your current CI server.
-https://elements.heroku.com/addons/knapsack-pro
+<br />
+<br />
 
-Knapsack Pro has Queue Mode that will split Ruby & JS tests in a dynamic way across parallel CI nodes to ensure each parallel job takes a similar time. Thanks to that there is no bottleneck in your CI pipelines.
+Knapsack wraps your current test runner and works with your existing CI infrastructure to split tests optimally.
 
-__See introduction how the Knapsack Pro add-on works__
-https://youtu.be/rmXES2N0_QU
+It comes in two flavors, `knapsack` and `knapsack_pro`:
 
-You may also find useful article how to run parallel dynos on Heroku CI to complete tests faster
-https://docs.knapsackpro.com/2019/how-to-run-tests-faster-on-heroku-ci-with-parallel-dynos
+|                                 | `knapsack` | `knapsack_pro`                          |
+| ------------------------------- | ---------- | --------------------------------------- |
+| Free                            | ✅         | ✅ [Free plan](https://knapsackpro.com?utm_source=github&utm_medium=readme&utm_campaign=knapsack_gem&utm_content=free_plan) |
+| Static split                    | ✅         | ✅                                      |
+| [Dynamic split](https://docs.knapsackpro.com/overview/#queue-mode-dynamic-split)       | ❌ | ✅ |
+| [Split by test examples](https://docs.knapsackpro.com/ruby/split-by-test-examples/)    | ❌ | ✅ |
+| Graphs, metrics, and stats      | ❌         | ✅                                      |
+| Programming languages           | 🤞 (Ruby)  | ✅ (Ruby, Cypress, Jest, SDK/API)       |
+| CI providers                    | 🤞 Limited | ✅ (All)                                |
+| [Heroku add-on](https://elements.heroku.com/addons/knapsack-pro)                       | ❌ | ✅ |
+| Additional features             | ❌         | 🤘 ([Overview](https://docs.knapsackpro.com/overview/)) |
+|                                 | [Install](http://docs.knapsackpro.com/ruby/knapsack) | [Install](https://docs.knapsackpro.com) |
 
-## Do you know
+[`knapsack` vs `knapsack_pro` full comparison](https://knapsackpro.com/features/ruby_knapsack_pro_vs_knapsack?utm_source=github&utm_medium=readme&utm_campaign=knapsack_gem&utm_content=ruby_knapsack_pro_vs_knapsack)
 
-* Knapsack Pro is risk-free integration! Knapsack Pro runs tests in Fallback Mode if your CI servers can't reach our API for any reason.
-* We don't need access to your repository. Knapsack Pro is just wrapper around test runner like RSpec, Cucumber, Minitest etc.
-* Hundreds of developers use Knapsack Pro every day to run fast CI builds.
-* It works with other programming languages.
+# Migrate from `knapsack` to `knapsack_pro`
+
+If you are already using `knapsack` and want to give `knapsack_pro` a try, here's [how to migrate in 10 minutes](./MIGRATE_TO_KNAPSACK_PRO.md).

README.md

@@ -1,3 +1,5 @@
+require 'ostruct'
+
 describe Knapsack::Adapters::RSpecAdapter do
   context do
     before { expect(::RSpec).to receive(:configure) }