rubinius

Overview

With the release of the RubySpec project, the Rubinius git repository is now a hybrid repository containing four different elements.

1. the Rubinius code itself
2. a copy of the MSpec code at $ROOT/mspec
3. a copy of the RubySpec specs at $ROOT/spec/frozen
4. the RubySpec specs as a clone at $ROOT/spec/ruby

The purpose of the copy of the RubySpecs at $ROOT/spec/frozen ("frozen specs") is to ensure that there are no regressions caused by new Rubinius code. Since Rubinius does not pass all the RubySpecs, there are a set of tags in $ROOT/spec/tags/frozen that are synchronized with the frozen specs and exclude known failures. These tags are used by the rake spec, rake spec:full (i.e. bin/mspec ci and bin/mspec ci -B full.mspec) commands to run the complete set of specs that are expected to pass.

The clone at $ROOT/spec/ruby is provided merely for your convenience. You do not have to commit to RubySpecs from this clone. There is nothing special about the clone. It is not part of the Rubinius repository at all. However, there are several convenience rake tasks to assist you in working with it.

Note that the Rubinius spec directory has been a hybrid since its inception. The RubySpecs are describing the behavior of MatzRuby. Rubinius is only matching that behavior. The rest of the specs are describing behavior specific to Rubinius that may or may not be relevant to matching the behavior described by the RubySpecs (e.g. $ROOT/spec/compiler or $ROOT/spec/library/actor).

Ask yourself...

There are only two things you need to keep in mind while working in the Rubinius repository:

1. What is my role?
2. What code am I modifying?

The rest of this document is organized by role. Focus on your role first, then on what code you are modifying.

My role is...

• existing committer
• new contributor
• casual observer

Existing committers

Just to be clear, you currently have a commit bit to the Rubinius repository. If this is not true, this is not your role. Try a different one.

Now, ask yourself...

1. Am I modifying the RubySpecs (any specs that describe the behavior of MatzRuby)?
2. Am I modifying Rubinius code or Rubinius-specific specs?
3. Am I updating the RubySpec copy at $ROOT/spec/frozen?

These are separate physically, conceptually, and functionally. Respect that separation and life will be easier.

I am modifying RubySpecs

The first thing you need to do is get a commit bit to the RubySpec repository on Github. To do so, try any (but please not all) of the options below

• Hit up brixen in #rubinius, #rubyspec, #ruby-core or #jruby and give him your Github username
• Send a note to the Rubinius ML
• Send a note to the RubySpec ML
• Open a ticket on the RubySpec tracker

Important: After you get your Github commit bit for the RubySpec repository, in the Rubinius repository run rake spec:committer to update the git URL in $ROOT/spec/ruby/.git/config so that you can push changes.

Now, on to adding or modifying RubySpec files. Again, the RubySpecs are describing the behavior of MatzRuby. The only thing that matters when you are writing RubySpecs is whether they pass on MatzRuby.

1. Edit a file under spec/ruby/1.8/...
2. Run bin/mspec -tr spec/ruby/1.8/some/file_spec.rb
3. Repeat until the spec passes on MatzRuby
4. Run rake git:status OR cd spec/ruby; git status
5. Run rake spec:commit OR cd spec/ruby; git add; git commit ... as normal
6. Run rake spec:update (to check for conflicts) OR rake spec:push (to update and then push your changes)

That's it. If you are modifying other RubySpecs, then repeat. If not, then switch modes. For you vim users, that's easy. For the rest of you, do some finger pushups or something. But go back and ask yourself the "What am I doing?" question.

I am modifying Rubinius code

If you are fixing a bug in Rubinius for which there are already specs (RubySpecs or Rubinius-specific specs), or you are writing new Rubinius-specific specs, proceed exactly as before.

1. Run rake git:update
2. Run bin/mspec spec/some/spec_file.rb to confirm the spec fails
3. Make some changes
4. Run rake
5. Run bin/mspec spec/some/spec_file.rb
6. Repeat until the spec passes
7. Run rake spec OR bin/mspec ci
8. Repeat if there are any regressions caught by the CI process
9. Run bin/mspec tag --del fails spec/frozen/1.8/some/spec_file.rb to remove tags for specs that now pass
10. Run rake git:status OR git status to review your changes
11. Run git add, git commit ...
12. Run rake git:push

Again, that's it. You are done with this task. Make sure you know your next task before continuing.

I am updating the spec/frozen copy of the RubySpecs

Commits are being made to the RubySpec repository all the time. This task will update the $ROOT/spec/frozen copy to the current HEAD of the RubySpec repository. It is almost certain that Rubinius will fail some of the new specs, so the tags must be updated as well.

1. Run rake git:update
2. Run rake spec:sync. This will update the specs and commit the changes.
3. Run rake clean build to force a recompilation of everything
4. Run rake spec:full OR bin/mspec ci -B full.mspec
5. Review any new CI failures
6. Run bin/mspec tag spec/frozen/1.8/... for each class that has failing specs
7. Run rake git:status OR git status to review changes to the tags
8. Run git add, git commit ...
9. Run rake git:push

It is essential that you manually review failures resulting from updating the frozen specs. If something looks amiss, talk to someone in #rubinius. If you're not sure, simply do not do this task.

New contributor

You've heard that Rubinius is the best thing since vented beer cans and spandex and you'd like to work up a little patch for some rough spot.

First, let's get ready to rumble.

1. Clone the Rubinius repository (see Using Git )
2. Run rake build
3. Run rake spec:full

Everything should be hunky-dory. If not, post a message to the mailing list or hop into the #rubinius IRC channel on freenode. For the purpose of this exercise, we'll assume things are fine.

Now, ask yourself...

1. Am I modifying the RubySpecs (any specs that describe the behavior of MatzRuby)?
2. Am I modifying Rubinius code or Rubinius-specific specs?

I am modifying RubySpecs

1. Edit a file under spec/ruby/1.8/...
2. Run bin/mspec -tr spec/ruby/1.8/some/spec_file.rb
3. Repeat until the spec passes on MatzRuby
4. Run rake git:status OR cd spec/ruby; git status
5. Change directory to spec/ruby
6. Run git status, git add, git commit, etc.
7. Run git format-patch
8. Upload the patch in a ticket on the rubyspec.org website

You're done. When your patch is accepted, you will get a commit bit to the RubySpecs repository. However, while you're on a roll, why not add a patch for Rubinius as well. See the next section for that.

I am modifying Rubinius code

1. Run bin/mspec spec/some/spec_file.rb to confirm the spec fails
2. Edit a file somewhere in Rubinius (probably under the kernel directory)
3. Run rake to build your change
4. Run bin/mspec spec/some/spec_file.rb to see if your spec passes
5. Repeat until your spec passes
6. Run rake spec:full OR bin/mspec ci -B full.mspec to ensure there are no regressions
7. Change directory to Rubinius root if not already there
8. Run git status, git add, git commit, etc.
9. Run git format-patch
10. Upload the patch in a ticket on the Rubinius lighthouse account

When your patch is accepted by the Rubinius project, you'll get a commit bit for the Rubinius repository. You'll also get a bit for the RubySpec repository (as long as you have a Github account and let us know your Github username).

Casual observers

If you are a casual observer, you probably don't have a commit bit (we'll assume you do not). You clone the Rubinius repository, build it, poke around a bit.

For you, nothing significant should change. All of the following activities work just like they did before from your perspective.

1. Clone the Rubinius repository
2. Run rake build
3. Run rake spec OR bin/mspec ci
4. Run shotgun/rubinius and play around in irb
5. Run rake install and play some more

If you would like to work on the RubySpecs from within your Rubinius clone, run rake spec:update.