From 9dcb7313e34d33a1a3cf0d904e60d180123b3645 Mon Sep 17 00:00:00 2001 From: Andrew Konchin Date: Fri, 19 Apr 2024 14:20:00 +0300 Subject: [PATCH 1/3] Add "How to work on a new CRuby feature" section to the How-To guide --- doc/contributor/how-to-guide.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/contributor/how-to-guide.md b/doc/contributor/how-to-guide.md index bea9550e834e..f930e6712570 100644 --- a/doc/contributor/how-to-guide.md +++ b/doc/contributor/how-to-guide.md @@ -31,6 +31,7 @@ * [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 find a Core Method implementation @@ -1564,3 +1565,20 @@ 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 ) From 84ca06f97a176fb798d1b9b1e8511e9db5a06192 Mon Sep 17 00:00:00 2001 From: Andrew Konchin Date: Fri, 19 Apr 2024 14:20:27 +0300 Subject: [PATCH 2/3] Add "How to prepare PR for changes in the next CRuby version" section to the How-To guide --- doc/contributor/how-to-guide.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/contributor/how-to-guide.md b/doc/contributor/how-to-guide.md index f930e6712570..e9dea21d99de 100644 --- a/doc/contributor/how-to-guide.md +++ b/doc/contributor/how-to-guide.md @@ -32,6 +32,7 @@ * [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 find a Core Method implementation @@ -1582,3 +1583,22 @@ When you work on a new feature/method usually you make the following steps: - 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). From 7daf94d48d3bea91eaefcf02bd275b755678d015 Mon Sep 17 00:00:00 2001 From: Andrew Konchin Date: Fri, 19 Apr 2024 14:20:41 +0300 Subject: [PATCH 3/3] Add "How to use jt CLI tool" section to the How-To guide --- doc/contributor/how-to-guide.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/doc/contributor/how-to-guide.md b/doc/contributor/how-to-guide.md index e9dea21d99de..fa9415c37592 100644 --- a/doc/contributor/how-to-guide.md +++ b/doc/contributor/how-to-guide.md @@ -33,6 +33,7 @@ * [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 @@ -1602,3 +1603,32 @@ If the new feature breaks existing behavior and some specs fail - disable them t 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