Skip to content

Merging specs from JRuby and other sources

Jump to bottom
Charles Oliver Nutter edited this page Nov 5, 2024 · 90 revisions

Once per month, specs from all sources are merged together in this repo.

Synchronizing specs between the ruby/spec repository and Ruby/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 changes to implementations
    2. Push ruby/spec changes to implementations

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 install

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

It is also possible to use ruby-build to install ruby-dev instead.

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

cd ruby
spec/mspec/tool/pull-latest-mspec-spec
make test-spec MSPECOPT="-j"
make test-bundled-gems-spec

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