Document versioned RBI annotations

README.md

@@ -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:
@@ -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.