Skip to content

Commit

Permalink
Merge pull request #258 from Shopify/emily/versioned-rbi-documentation
Browse files Browse the repository at this point in the history
Document versioned RBI annotations
  • Loading branch information
egiurleo authored Nov 18, 2024
2 parents 0a1ad30 + e3ed4ef commit 12762cc
Showing 1 changed file with 68 additions and 5 deletions.
73 changes: 68 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,74 @@ If you're copying this into your own `index.json`, make sure you strip out the c

See the index [validation schema](schema.json) for more details.

### Writing Annotations

#### Missing methods and shims

It is possible to allow necessary shims for non-existing runtime definitions by using comment tags:

* `@missing_method` to indicate that a method is delegated to another receiver using `method_missing`
* `@shim` to indicate that a definition doesn't actually exist at runtime but is needed to allow type checking

#### Versioned annotations

Many gems simultaneously maintain more than one version, often with different external APIs. If the gem's RBI
annotation file does not match the version being used in your project, it can result in misleading type checking
errors that slow down development.

Starting in version 0.1.10, the rbi gem supports adding gem version comments to RBI annotations, allowing us to
specify the gem versions that include specific methods and constants. [Tapioca](https://github.com/Shopify/tapioca)
version 0.15.0 and later will strip out any parts of the annotation file that are not relevant to the current gem
version when pulling annotations into a project.

##### Syntax

To use this feature, add a comment in the following format directly above a method or constant:

```ruby
# @version > 0.2.0
sig { void }
def foo; end
```

The comment must start with a space, and then the string `@version`, followed by an [operator](#operators) and
a version number. Version numbers must be compatible with Ruby's
[`Gem::Version` specification](https://ruby-doc.org/current/stdlibs/rubygems/Gem/Version.html).

Any method or constant that does not have a version annotation will be considered part of all versions.

For more information about Ruby gem versions, see the [Ruby documentation](https://ruby-doc.org/3.3.4/stdlibs/rubygems/Gem/Version.html).

##### Combining Versions

Version comments can use both "AND" and "OR" logic to form more precise version specifications.

###### AND

To specify an intersection between multiple version ranges, use a comma-separated list of versions. For example:

```ruby
# @version >= 0.3.4, < 0.4.0
sig { void }
def foo; end
```

The example above specifies a version range that starts at version 0.3.4 and includes every version up to 0.4.0.

###### OR

To specify a union between multiple version ranges, place multiple version comments in a row above the same method or
constant. For example:

```ruby
# @version < 1.4.0
# @version >= 4.0.0
sig { void }
def foo; end
```

The example above specifies a version range including any version less than 1.4.0 OR greater than or equal to 4.0.0.

### Pulling annotations

To pull relevant gem annotations into your project, run Tapioca's [`annotations` command](https://github.com/Shopify/tapioca#pulling-rbi-annotations-from-remote-sources) inside your project:
Expand Down Expand Up @@ -84,11 +152,6 @@ For each gem the test works as follows:
2. Tries to `const_get` each constant defined in the RBI file
3. Tries to call `instance_method` for each method and attribute accessor (or `method` for singleton methods) in the RBI file

It is possible to allow necessary shims for non-existing runtime definitions by using comment tags:

* `@missing_method` to indicate that a method is delegated to another receiver using `method_missing`
* `@shim` to indicate that a definition doesn't actually exist at runtime but is needed to allow type checking

### Static checks

Ensure the constants (constants, classes, modules) and properties (methods, attribute accessors) exist are not duplicated from Tapioca generated RBIs and do not create type errors when running Sorbet.
Expand Down

0 comments on commit 12762cc

Please sign in to comment.