Should gems include private methods and constants in their RBS files?

[marcotc]

For Ruby gems, is it good practice to include all API (public, protected, and private) in their RBS files, or should they only include the publicly accessible API?

I work with the https://github.com/DataDog/dd-trace-rb gem, and we use https://github.com/soutaro/steep for type checking, thus private methods in the RBS API are relevant for our type checking. But for downstream consumers of the gem, they do not need information about private APIs, as they are not accessible to them.

Is there a guidance today on this subject for Ruby gems? Thank you!

[soutaro]

Hi @marcotc,

We don't have a strong recommendation yet.

RBS ships with type definitions of private APIs. This is simple. But causes a problematic situation -- releasing a patch release with an incompatible change on private APIs.

There are two options to keep things private:

1. Having another directory outside of /sig. And put private definitions there, for example /_sig.
2. Put private definitions inside a directory starting with _ inside /sig, like /sig/_private/foo.rbs. The directories starting with _ is ignored when it's loaded as a library signature.

Either causes another problem to keep the definition without private things valid. You may want to add a CI job to confirm if the type definition without private things is still valid. (Maybe with rbs validate command.)

We are also curious if you have an idea to solve the problem.