Feature #22081: Core type definition migration from `ruby/rbs` to `ruby/ruby`

• Status: Open
• Assignee: soutaro (Soutaro Matsumoto)
• Target version: 4.1

[soutaro (Soutaro Matsumoto)]

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 (Soutaro Matsumoto) 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 (Soutaro Matsumoto) will copy the type definitions from ruby/ruby to ruby/rbs at each rbs-gem release.

[nobu (Nobuyoshi Nakada)]

soutaro (Soutaro Matsumoto) wrote:

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.

+1

The RBS files will be installed under something like "#{RbConfig::CONFIG["prefix"]}/sig", but the exact path is not decided yet. Suggestions are welcome!

I think it should be under $(datarootdir), if sig won't conflict with the other products.

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.

An install-time option, instead of configure-time?

In "Updated workflow":

• 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.

In "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.

Which test does it?
And I'm uncertain if bundled gems can run during test-all for now.