Issue #22081 has been reported by soutaro (Soutaro Matsumoto). ---------------------------------------- Feature #22081: Core type definition migration from `ruby/rbs` to `ruby/ruby` https://bugs.ruby-lang.org/issues/22081 * Author: soutaro (Soutaro Matsumoto) * Status: Open * Assignee: soutaro (Soutaro Matsumoto) * Target version: 4.1 ---------------------------------------- Currently, the RBS type definitions for core libraries live in the `ruby/rbs` repository. When you change a core class or method in `ruby/ruby`, the corresponding RBS type definition often needs to be updated too — but that update requires a separate PR to `ruby/rbs`, so the work cannot be completed within `ruby/ruby` alone. This is painful for Ruby core committers and contributors. To address this problem, we will move the core library type definitions to `ruby/ruby` so that you can update the RBS type definitions within the same PR. We want to get this done in Ruby 4.1. **Question:** Do you have any concerns about migrating the RBS core type definitions to `ruby/ruby`? ## Current workflow The `test-bundled-gems` CI job in `ruby/ruby` runs the core type definition tests bundled with the rbs-gem. The tests actually call core methods and validate that the arguments and return values have the expected types using `is_a?`. When you change a core library in `ruby/ruby` in a way that requires a type definition update, the `test-bundled-gems` job fails and CI turns red. At that point, you have two options: 1. **Update the RBS type definitions** by submitting a separate PR to `ruby/rbs` 2. **Skip the failing tests** by adding the test name to the `rbs_skip_tests` file (in `ruby/ruby` repository) Either way, you are forced to take some action to get CI green again. Option 1 is actually very painful in practice. The type definitions bundled with the rbs-gem correspond to the released version of Ruby, not the in-development version. As a result, PRs to `ruby/rbs` for in-development APIs often end up modifying tests rather than type definitions — wasteful and frustrating work. Some examples: https://github.com/ruby/rbs/pull/2366 https://github.com/ruby/rbs/pull/2706 ## Updated workflow We can streamline the workflow by moving the core library RBS type definitions to `ruby/ruby` repository. - We will add a directory such as `sig` to `ruby/ruby` and store files like `string.rbs` there - Ruby's CI will run tests (`test-bundled-gems`) for the RBS type definitions in `ruby/ruby` repository. If your commit changes the core library methods/classes, please update the RBS files and tests too. - Ruby 4.1 will ship with the core type definitions, which will be installed with it. The rbs-gem will load the core library type definitions shipped with Ruby. With this workflow, when `test-bundled-gems` fails, you can fix the issue directly within your `ruby/ruby` work — without leaving the repository or coordinating a separate PR — which makes updating RBS much easier. *Note:* This workflow introduces a new step — *updating the RBS type definitions* — that wasn't previously required of Ruby committers. However, it replaces the existing workaround of skipping tests or coordinating a separate PR to `ruby/rbs` just to keep CI green. And unlike that workaround, updating the RBS definitions is itself a real improvement to Ruby. We believe this trade-off is acceptable. ## Implementation plan ### What we won't do 1. We will keep rbs-gem as a bundled gem. We won't make it a default gem, default library, or Ruby built-in. rbs-gem has a C extension, and changing from a bundled gem would require significantly more work for compilation. 2. We will keep the `ruby/rbs` repository for development of the library implementation. We want to release new versions of the gem more often than Ruby's release cycle. ### File layout in `ruby/ruby` repository - Type definitions will be stored under `sig/` (e.g., `sig/core/string.rbs`) - Type definition tests will be placed under `test/sig` - The bundled version of rbs-gem will be used to test against the `sig/` type definitions and `test/sig` tests Note that the directory names are tentative. Let me know if you have an idea what the names of the directories should be. ### Installation and distribution When Ruby is installed, the core and standard library RBS type definitions will be installed alongside it. The rbs-gem will reference these bundled definitions rather than maintaining its own copy. The RBS files will be installed under something like `"#{RbConfig::CONFIG["prefix"]}/sig"`, but the exact path is not decided yet. Suggestions are welcome! *Note:* We may also want an install-time option to skip installing the RBS type definitions, for example for minimal Ruby builds where they are not needed. #### Releasing new type definitions Currently, we can release a new version of rbs-gem to update the core type definition. After this migration, we need to wait for the next Ruby release to update type definition. I think this is okay, since the core type definition is pretty stable today. ### Testing RBS type definition tests will run as part of `make test-all` in `ruby/ruby`, rather than only through `test-bundled-gems`. This ensures type definitions are validated during the standard Ruby development workflow. Note that the RBS test suite currently takes 2–3 minutes in CI, so we need to decide which development tasks should include full testing. ### Other notes - Core RBS definitions contain documentation copied from RDoc, which needs to be updated before each release. For now, @soutaro plans to do this manually. - Ruby 4.0 and earlier releases do not include RBS type definitions, so the rbs-gem releases must continue to bundle them. @soutaro will copy the type definitions from `ruby/ruby` to `ruby/rbs` at each rbs-gem release. -- https://bugs.ruby-lang.org/