Step 6: Explain how to run the builds across Rubies locally

Author: JuanVqz

.gitignore

@@ -3,3 +3,4 @@
 /Gemfile.lock
 /results/
 /_site/
+/cross-ruby/

CONTRIBUTING.md

@@ -122,6 +122,21 @@ docker compose run --rm -T --entrypoint ruby ruby_4.0 script/build_results_site.
 CI does the same after every run: the site is attached to the run as the
 `site-preview` artifact, and published to GitHub Pages from `main`.
 
+Those results only compare idioms inside one Ruby: in CI each Ruby runs on its own machine.
+The site's "Across Rubies" view compares Rubies, so every build has to run on one machine.
+`script/run_cross_ruby.rb` (Ruby 3 on your machine, it calls Docker) does that, and runs the newest released MRI again after every 3 builds, so the site can show how steady the machine was.
+For example, two files on three builds:
+
+```
+ruby script/run_cross_ruby.rb --files code/date/iso8601-vs-parse.rb,code/string/gsub-vs-tr.rb --builds ruby_3.4,ruby_3.4+yjit,ruby_4.0 --out cross-ruby
+docker compose run --rm -T --entrypoint ruby ruby_4.0 script/build_results_site.rb results _site --cross-ruby cross-ruby
+```
+
+`ruby script/run_cross_ruby.rb --help` lists the options.
+The builds are the ones in the CI matrix (`.github/workflows/benchmarks.yml`), so a new Ruby added there and in `compose.yaml` is measured too, and once released it becomes both the reference and the Ruby the site opens on.
+CI runs every build on every file once a week, split over 6 machines (`.github/workflows/benchmarks-cross-ruby.yml`).
+On an Apple silicon Mac, leave out `ruby_2.1` and `jruby_9.1` (they run under emulation, so their numbers are not comparable) and `ruby_3.1+yjit` (Ruby 3.1's YJIT only exists on x86-64).
+
 ## Benchmarks that need a newer Ruby
 
 CI runs every benchmark on every Ruby in `compose.yaml`, back to Ruby 2.1, and