From e3ed4ef08d0369b56de2becadbc33b88d88ca668 Mon Sep 17 00:00:00 2001
From: Emily Samp <emily.samp@shopify.com>
Date: Thu, 14 Nov 2024 10:49:55 -0600
Subject: [PATCH] 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 eb544f3..0c21cda 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: