From b1284d093fed380876e3c42c9a23879b713611d9 Mon Sep 17 00:00:00 2001 From: Emily Samp Date: Thu, 14 Nov 2024 10:37:34 -0600 Subject: [PATCH 1/2] Create a new "Writing Annotations" section in the README Add information about `@missing_method` and `@shim` to that section --- README.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5a736954..eb544f30 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,15 @@ 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 + ### 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: @@ -84,11 +93,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. From e3ed4ef08d0369b56de2becadbc33b88d88ca668 Mon Sep 17 00:00:00 2001 From: Emily Samp Date: Thu, 14 Nov 2024 10:49:55 -0600 Subject: [PATCH 2/2] Document versioned RBI annotations Versioned RBI annotations allow us to specify which parts of an RBI annotation file are relevant to specific gem versions. This adds documentation for this feature and links to it from the README. --- README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/README.md b/README.md index eb544f30..0c21cdac 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,65 @@ It is possible to allow necessary shims for non-existing runtime definitions by * `@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: