Skip to content

Merging specs from JRuby and other sources

Jump to bottom
Benoit Daloze edited this page Nov 7, 2024 · 90 revisions

Once per month, specs from all sources are merged together in this repo and then back to the 3 Ruby implementations, by a ruby/spec maintainer. This is not trivial so if you never did it before you should coordinate with someone who did.

Synchronizing specs between the ruby/spec repository and CRuby/JRuby/TruffleRuby should be performed in the following order:

  1. Upstreaming changes from Ruby implementations:
    1. Pull changes made to mspec and push them to ruby/mspec
    2. Pull changes made to ruby specs and push them to ruby/spec
  2. Downstreaming changes from ruby/mspec and ruby/spec back to Ruby implementations:
    1. Push ruby/mspec & ruby/spec changes to implementations

The whole sync'ing should be done as quickly as possible (at most in the same day), and creating the PRs to the Ruby implementations too. For CRuby the PR/push should be merged as quickly as possible (because CRuby does not have merge commits), for JRuby/TruffleRuby they need to be created as quickly as possible but can be merged later with a merge commit without issues.

The reason for this timing is we simply rm -rf spec/ruby && git clone ruby/spec in each Ruby implementation, overriding any changes. So if there are any specs committed in these repo between sync'ing to ruby/spec and back, they need to be imported to ruby/spec semi-manually, by using ONLY_FILTER=true ruby sync-rubyspec.rb mri|jruby|truffleruby and cherry-picking commits from the corresponding branch to the main branch.

Therefore when sync'ing specs you should try as much as possible to handle everything yourself, that means fixing the ruby/spec CI (including RuboCop), addressing transient specs, etc.

Most of the work is already automated by the sync-rubyspec.rb script.

Prerequisites

Install chruby

To check locally that new specs pass on all supported Ruby versions, specs will be run on the lowest and the highest supported Ruby versions. To switch between Ruby versions a chruby command is used. Use https://github.com/postmodern/chruby to install it.

If ZSH is used locally then chruby should be installed not only in ~/.zshrc but also in ~/.zshenv to be available in non-interactive sessions (when the script runs the chruby command).

Install Ruby versions to run specs

Get the lowest and the highest supported (by ruby/spec) Ruby versions from the CI config. Use ruby-install or ruby-build to install them to the ~/.rubies directory . The specs also will be run on the current Ruby head.

Layout

It's expected by the script that MSpec and ruby/spec working directories are siblings:

mspec
rubyspec

The Ruby, JRuby and TruffleRuby Git repositories will be cloned by the script into the mspec/tool/sync directory.

Upstream MSpec changes in MRI, JRuby and TruffleRuby

  1. Check if there are any changes under spec/mspec in TruffleRuby, JRuby, Ruby (and git checkout master && git pull in each)
  2. If so:
    • cd mspec/tool/sync
    • ruby sync-rubyspec.rb --mspec mri
    • ruby sync-rubyspec.rb --mspec jruby
    • ruby sync-rubyspec.rb --mspec truffleruby

Upstream ruby/spec changes in MRI, JRuby and TruffleRuby

  1. Build Ruby head
  2. cd mspec/tool/sync, ruby sync-rubyspec.rb mri
  3. cd mspec/tool/sync, ruby sync-rubyspec.rb jruby
  4. cd mspec/tool/sync, ruby sync-rubyspec.rb truffleruby
  5. cd rubyspec, git push
  6. Check ruby/spec CI and fix it until gets green

Use TEST_MASTER=false ... to skip testing against Ruby head.

How to build Ruby head

The main instruction is located here. But in short the following commands should be executed locally in the Ruby working directory after cloning Ruby Git repository:

./autogen.sh
mkdir ~/.rubies
./configure --prefix="${HOME}/.rubies/ruby-master" --disable-install-doc
make -j8 install-nodoc

Ruby dev build will be available as ruby-master with chruby command.

Downstream ruby/spec to MRI, JRuby and TruffleRuby

The Ruby, JRuby and TruffleRuby Git repositories should be cloned (or reuse ones in mspec/tool/sync)

On macOS pbpaste could be used instead of xsel command.

Ruby

  1. Run the following commands:
cd ruby
spec/mspec/tool/pull-latest-mspec-spec
make test-spec MSPECOPT="-j"
make test-bundled-gems-spec
  1. Push directly to master or make a PR (if so, make sure to merge it ASAP)

JRuby

  1. Run the following commands:
cd jruby
git checkout -b update-specs
spec/mspec/tool/pull-latest-mspec-spec
  1. Make a PR (Milestone: Non-Release)
  2. Check CI, tag failed specs with xsel -b | spec/mspec/tool/tag_from_output.rb

TruffleRuby

  1. Run the commands:
cd truffleruby
git checkout -b bd/update-specs-YYYYMMDD
spec/mspec/tool/pull-latest-mspec-spec
jt --build test fast
  1. Commit slow tags (message: Add slow tags)
  2. Tag failed specs with xsel -b | spec/mspec/tool/tag_from_output.rb (message: Add tags for new failing specs)
  3. Make a PR
Clone this wiki locally