diff --git a/doc/contributor/how-to-guide.md b/doc/contributor/how-to-guide.md index bea9550e834e..fa9415c37592 100644 --- a/doc/contributor/how-to-guide.md +++ b/doc/contributor/how-to-guide.md @@ -31,6 +31,9 @@ * [How to tag slow ruby/spec tests](#how-to-tag-slow-rubyspec-tests) * [How to introduce a constant in specs](#how-to-introduce-a-constant-in-specs) * [How to add a new spec](#how-to-add-a-new-spec) + * [How to work on a new CRuby feature](#how-to-work-on-a-new-cruby-feature) + * [How to prepare PR for changes in the next CRuby version](#how-to-prepare-pr-for-changes-in-the-next-cruby-version) + * [How to use jt CLI tool](#how-to-use-jt-cli-tool) ## How to find a Core Method implementation @@ -1564,3 +1567,68 @@ There are the following main directories: - `spec/ruby/core` - specs for the Core Library - `spec/ruby/library` - specs for the Standard Library - `spec/ruby/language` - specs for the Ruby syntax itself + +## How to work on a new CRuby feature + +When you work on a new feature/method usually you make the following steps: + +- check a feature/method description in the Ruby documentation +- check a corresponding issue (on the Ruby bug tracker ): + - a feature description + - discussion + - "Associated revisions" tab with commits and diffs (pay attention to added MRI and ruby/spec tests) +- check existing ruby/spec tests in the TruffleRuby repository +- add missing test cases +- untag ruby/spec tests +- implement the feature +- untag MRI tests and ensure they pass too +- mention in a PR description an original issue in a way it's described in the Ruby + release notes or provide a link to an original ticket (on ) + +## How to prepare PR for changes in the next CRuby version + +When you work on a new feature that is introduced in Ruby version which TruffleRuby doesn't support yet +(e.g. TruffleRuby is compatible with Ruby 3.1 now but the feature is introduced in Ruby 3.2) there is a +problem with running proper specs locally and on CI (both internal and GitHub Actions). + +So you should ensure that the specs for the new feature are run and passed successfully on CI and the +whole suit pass successfully as well: + +- add specs for the new feature if they are missing (with a `ruby_version_is` guard) +- use `PRETEND_RUBY_VERSION` environment variable to run specs for the new feature +- add a file with specs for the new feature to the next list in `spec/truffleruby.next-specs` (to run them on CI) +- use `jt test :next` to run locally all the specs for the next CRuby version + +If the new feature breaks existing behavior and some specs fail - disable them temporary (until TruffleRuby +is switched to the next CRuby version completely) with tagging as failed (use `jt tag `) + +Look for additional details in [The "Running specs for Ruby 3.3 features" section of the Contributor Workflow document](workflow.md#running-specs-for-ruby-33-features). + +## How to use jt CLI tool + +The `jt` CLI tool has a lot of commands but there are very few basic ones that you may need to use often: + +- `jt ruby` - run TruffleRuby REPL (`irb`) + - `jt ruby ` - execute a file with Ruby source code with TruffleRuby + - `jt ruby -e ''` - execute a string of Ruby source code with TruffleRuby REPL + - `jt -q ruby --jdebug -e ''` - to launch debugger +- `jt test ` - run ruby/spec test file + - `jt --use ruby test ` - to use tests against current CRuby, not TruffleRuby + - `jt -u ruby test ` - there is a short form `-u` + - `jt test -- --jdebug` - to launch debugger + - `jt test fast ` - run subset of specs and tag slow test cases with tag `slow` + - `jt test :next` - run specs for features introduced in the next CRuby version, not supported by TruffleRuby currently +- `jt test mri ` - run MRI test file + - `jt test mri --jdebug` - to launch debugger for MRI tests (without `--`) + - `jt test mri -- -n ` - to run only specified UnitTest case +- `jt build` +- `jt clean` +- `jt rebuild` +- `jt sync` - to synchronize changes in Standard Library Ruby source code and apply them without rebuilding TruffleRuby +- `jt tag` - ruby/spec only +- `jt untag ` - (ruby/spec only) regenerate an exclude file for particular ruby/spec file (and list all the failed test cases) +- `jt retag ` - (MRI test only) regenerate an exclude file for particular MRI test file (and list all the failed test cases) +- `jt lint fast` - to run some linter checks (that are run on CI) locally +- `jt rubocop` - to run Ruby source code linter separately from other linter checks. + - `jt rubocop -a` - to correct safely Rubocop warnings automatically + - `jt rubocop -A` - to correct unsafely Rubocop warnings automatically