rbs 4.0.3 → 4.1.3

data/core/struct.rbs

@@ -104,8 +104,8 @@
 # *   #inspect (aliased as #to_s): Returns a string representation of `self`.
 # *   #to_h: Returns a hash of the member name/value pairs in `self`.
 #
-class Struct[Elem]
-  include Enumerable[Elem]
+class Struct[E]
+  include Enumerable[E]
 
   # The types that can be used when "indexing" into a `Struct` via `[]`, `[]=`, `dig`, and
   # `deconstruct_keys`.
@@ -362,7 +362,7 @@ class Struct[Elem]
   #
   # Related: #members.
   #
-  def to_a: () -> Array[Elem]
+  def to_a: () -> Array[E]
 
   # <!--
   #   rdoc-file=struct.c
@@ -385,8 +385,8 @@ class Struct[Elem]
   #
   # Raises ArgumentError if the block returns an inappropriate value.
   #
-  def to_h: () -> Hash[Symbol, Elem]
-          | [K, V] () { (Symbol key, Elem value) -> [K, V] } -> Hash[K, V]
+  def to_h: () -> Hash[Symbol, E]
+          | [K, V] () { (Symbol key, E value) -> [K, V] } -> Hash[K, V]
 
   # <!-- rdoc-file=struct.c -->
   # Returns the values in `self` as an array:
@@ -441,8 +441,8 @@ class Struct[Elem]
   #
   # Related: #each_pair.
   #
-  def each: () -> Enumerator[Elem, self]
-          | () { (Elem value) -> void } -> self
+  def each: () -> Enumerator[E, self]
+          | () { (E value) -> void } -> self
 
   # <!--
   #   rdoc-file=struct.c
@@ -465,8 +465,8 @@ class Struct[Elem]
   #
   # Related: #each.
   #
-  def each_pair: () -> Enumerator[[Symbol, Elem], self]
-               | () { ([Symbol, Elem] key_value) -> void } -> self
+  def each_pair: () -> Enumerator[[Symbol, E], self]
+               | () { ([Symbol, E] key_value) -> void } -> self
 
   # <!--
   #   rdoc-file=struct.c
@@ -492,7 +492,7 @@ class Struct[Elem]
   #
   # Raises IndexError if `n` is out of range.
   #
-  def []: (index name_or_position) -> Elem
+  def []: (index name_or_position) -> E
 
   # <!--
   #   rdoc-file=struct.c
@@ -521,7 +521,7 @@ class Struct[Elem]
   #
   # Raises IndexError if `n` is out of range.
   #
-  def []=: (index name_or_position, Elem value) -> Elem
+  def []=: (index name_or_position, E value) -> E
 
   # <!--
   #   rdoc-file=struct.c
@@ -540,8 +540,8 @@ class Struct[Elem]
   #
   # With no block given, returns an Enumerator.
   #
-  def select: () -> Enumerator[Elem, Array[Elem]]
-            | () { (Elem value) -> boolish } -> Array[Elem]
+  def select: () -> Enumerator[E, Array[E]]
+            | () { (E value) -> boolish } -> Array[E]
 
   # <!-- rdoc-file=struct.c -->
   # With a block given, returns an array of values from `self` for which the block
@@ -591,7 +591,7 @@ class Struct[Elem]
   # Raises RangeError if any element of the range is negative and out of range;
   # see Array@Array+Indexes.
   #
-  def values_at: (*int | range[int?] positions) -> Array[Elem]
+  def values_at: (*int | range[int?] positions) -> Array[E]
 
   # <!--
   #   rdoc-file=struct.c
@@ -634,7 +634,7 @@ class Struct[Elem]
   #     f.dig(0, 0, :b, 0) # => 1
   #     f.dig(:b, 0) # => nil
   #
-  def dig: (index name_or_position) -> Elem
+  def dig: (index name_or_position) -> E
          | (index name_or_position, untyped, *untyped) -> untyped
 
   # <!-- rdoc-file=struct.c -->
@@ -664,5 +664,5 @@ class Struct[Elem]
   #     h = joe.deconstruct_keys(nil)
   #     h # => {:name=>"Joseph Smith, Jr.", :address=>"123 Maple, Anytown NC", :zip=>12345}
   #
-  def deconstruct_keys: (Array[index & Hash::_Key]? indices) -> Hash[index & Hash::_Key, Elem]
+  def deconstruct_keys: (Array[index & Hash::_Key]? indices) -> Hash[index & Hash::_Key, E]
 end

data/core/thread.rbs

@@ -1565,10 +1565,10 @@ class Thread::Mutex < Object
 
   # <!--
   #   rdoc-file=thread_sync.rb
-  #   - mutex.lock  -> self
+  #   - mutex.unlock  -> self
   # -->
-  # Attempts to grab the lock and waits if it isn't available. Raises
-  # `ThreadError` if `mutex` was locked by the current thread.
+  # Releases the lock. Raises `ThreadError` if `mutex` wasn't locked by the
+  # current thread.
   #
   def unlock: () -> self
 end
@@ -1604,7 +1604,7 @@ end
 #
 #     consumer.join
 #
-class Thread::Queue[Elem = untyped] < Object
+class Thread::Queue[E = untyped] < Object
   # <!-- rdoc-file=thread_sync.c -->
   # Pushes the given `object` to the queue.
   #
@@ -1719,7 +1719,7 @@ class Thread::Queue[Elem = untyped] < Object
   # If `timeout` seconds have passed and no data is available `nil` is returned.
   # If `timeout` is `0` it returns immediately.
   #
-  def pop: (?boolish non_block, ?timeout: _ToF?) -> Elem?
+  def pop: (?boolish non_block, ?timeout: _ToF?) -> E?
 
   # <!--
   #   rdoc-file=thread_sync.c
@@ -1729,7 +1729,7 @@ class Thread::Queue[Elem = untyped] < Object
   # -->
   # Pushes the given `object` to the queue.
   #
-  def push: (Elem obj) -> void
+  def push: (E obj) -> void
 
   # <!--
   #   rdoc-file=thread_sync.rb
@@ -1750,12 +1750,7 @@ end
 #
 # See Thread::Queue for an example of how a Thread::SizedQueue works.
 #
-class Thread::SizedQueue[Elem = untyped] < Thread::Queue[Elem]
-  # <!--
-  #   rdoc-file=thread_sync.rb
-  #   - <<(object, non_block = false, timeout: nil)
-  # -->
-  #
+class Thread::SizedQueue[E = untyped] < Thread::Queue[E]
   alias << push
 
   # <!--
@@ -1813,8 +1808,8 @@ class Thread::SizedQueue[Elem = untyped] < Thread::Queue[Elem]
   # If `timeout` seconds have passed and no space is available `nil` is returned.
   # If `timeout` is `0` it returns immediately. Otherwise it returns `self`.
   #
-  def push: (Elem obj, ?boolish non_block) -> void
-          | (Elem obj, timeout: _ToF?) -> self?
+  def push: (E obj, ?boolish non_block) -> void
+          | (E obj, timeout: _ToF?) -> self?
 end
 
 class ConditionVariable = Thread::ConditionVariable

data/docs/CONTRIBUTING.md

@@ -12,7 +12,8 @@
 The RBS repository contains the type definitions of Core API and Standard Libraries.
 There are some discussions whether if it is the best to have them in this repository, but we have them and continue updating the files meanwhile.
 
-The target version of the bundled type definitions is the latest _release_ of Ruby -- `3.1` as of January 2022.
+The target version of the bundled type definitions is the [latest _release_ of Ruby](https://www.ruby-lang.org/en/downloads/branches/) -- `4.0` as of 2026.
+Note, however, that the CI runs the tests on every non-EOL Ruby -- `3.3` and later as of 2026.
 
 **The core API** type definitions are in `core` directory.
 You will find the familiar class names in the directory, like `string.rbs` or `array.rbs`.

data/docs/inline.md

@@ -123,10 +123,38 @@ end
 
 This creates the types `::API`, `::API::V1`, and `::API::V1::Resources`.
 
+### `module-self` constraint
+
+The `module-self` constraint declares which classes or modules the module can be mixed into.
+
+```ruby
+# @rbs module-self: _Each[String]
+module Enumerable2
+end
+```
+
+This is equivalent to `module Enumerable2 : _Each[String]` in RBS, meaning `Enumerable2` can only be included in classes that satisfy the `_Each[String]` interface.
+
+Multiple `module-self` constraints can be declared with separate annotations:
+
+```ruby
+# @rbs module-self: _Each[String]
+# @rbs module-self: Comparable
+module StringCollection
+end
+```
+
+You can add a description after `--`:
+
+```ruby
+# @rbs module-self: Minitest::Test -- depending on assertion methods
+module TestHelper
+end
+```
+
 ### Current Limitations
 
 - Generic module definitions are not supported
-- Module self-type constraints are not supported
 
 ## Method Definitions
 
@@ -135,6 +163,8 @@ Inline RBS supports methods defined using the `def` syntax in Ruby.
 ```ruby
 class Calculator
   def add(x, y) = x+y
+
+  def self.zero = 0
 end
 ```
 
@@ -205,6 +235,18 @@ The type of both methods is `(Integer, Integer) -> Integer | (Float, Float) -> F
 > The `@rbs METHOD-TYPE` syntax allows overloads with the `|` operator, just like in RBS files.
 > Multiple `: METHOD-TYPE` declarations are required for overloads.
 
+The `#:` syntax can also be used as a trailing annotation to declare the return type of a method:
+
+```ruby
+class Calculator
+  def add(x, y) #: Integer
+    x + y
+  end
+
+  def subtract(x, y) = x - y #: Integer
+end
+```
+
 The `@rbs METHOD-TYPE` syntax allows having `...` at the last part.
 
 ```ruby
@@ -309,9 +351,10 @@ end
 
 ### Current Limitations
 
-- Class methods and singleton methods are not supported
-- Only positional and keyword parameters are supported. Splat parameters (`*x`, `**y`) and block parameter (`&block`) are not supported yet.
 - Method visibility declaration is not supported yet
+- The `class << self` syntax is not supported
+- Top-level method definitions (outside any class/module) are not supported
+- Method definitions with a non-self receiver (e.g. `def obj.foo`) are not supported
 
 ## Attributes
 
@@ -389,6 +432,7 @@ The attribute definitions are ignored because the names are given by string lite
 ### Current Limitations
 
 - Attribute visibility is not supported yet. All attributes are _public_
+- Top-level attribute definitions (outside any class/module) are not supported
 
 ## Mixin
 
@@ -487,7 +531,7 @@ end
 ```
 
 The `@rbs @VAR-NAME: TYPE` syntax enclosed in `class`/`module` syntax declares instance variables.
-You can add the documentation of the variable followed by two hyphones (`--`).
+You can add the documentation of the variable followed by two hyphens (`--`).
 
 Instance variable declarations must be under the `class`/`module` syntax, and they are ignored if written inside method definitions.
 
@@ -519,14 +563,16 @@ The types of constants may be automatically inferred when the right-hand side co
 - **Floats**: `RATE = 3.14` → `Float`
 - **Booleans**: `ENABLED = true` → `bool`
 - **Strings**: `NAME = "test"` → `String`
-- **Symbols**: `STATUS = :ready` → `:ready`
+- **Symbols**: `STATUS = :ready` → `Symbol`
+- **Nil**: `EMPTY = nil` → `nil`
 
 ```ruby
 MAX_SIZE = 100           # Inferred as Integer
 PI = 3.14159            # Inferred as Float
 DEBUG = false           # Inferred as bool
 APP_NAME = "MyApp"      # Inferred as String
-DEFAULT_MODE = :strict  # Inferred as :strict
+DEFAULT_MODE = :strict  # Inferred as Symbol
+NONE = nil              # Inferred as nil
 ```
 
 ### Explicit Type Annotations
@@ -567,10 +613,22 @@ MyKernel = Kernel #: module-alias
 
 This creates new type names that refer to the same class or module as the original.
 
-The annotations can have optional type name to specify the class/module name, for the case it cannot be infered through the right-hand-side of the constant declaration.
+The annotations can have optional type name to specify the class/module name, for the case it cannot be inferred through the right-hand-side of the constant declaration.
 
 ```ruby
 MyObject = object #: class-alias Object
 
 MyKernel = kernel #: module-alias Kernel
 ```
+
+## Skip Annotation
+
+The `@rbs skip` annotation makes inline RBS ignore the following declaration.
+
+```ruby
+class Calculator
+  # @rbs skip
+  def debug_internal
+  end
+end
+```

data/docs/rbs_by_example.md

@@ -107,14 +107,14 @@ end
 For now, it's safe to ignore them, but they're included for completeness.
 
 ```rbs
-class Array[Elem]
+class Array[E]
   def *: (String) -> String
-       | (Integer) -> Array[Elem]
+       | (Integer) -> Array[E]
 end
 ```
 
 `Array`'s `*` method, when given a `String` returns a `String`. When given an
-`Integer`, it returns an `Array` of the same contained type `Elem` (in our example case, `Elem` corresponds to `Integer`).
+`Integer`, it returns an `Array` of the same contained type `E` (in our example case, `E` corresponds to `Integer`).
 
 ### Union types
 
@@ -150,9 +150,9 @@ end
 ```
 
 ```rbs
-class Enumerable[Elem]
-  def first: () -> Elem?
-           | (Integer) -> Array[Elem]
+class Enumerable[E]
+  def first: () -> E?
+           | (Integer) -> Array[E]
 end
 ```
 
@@ -160,12 +160,12 @@ end
 
 When called with no arguments, the return value will either be an instance of
 whatever type is contained in the enumerable, or `nil`. We represent that with
-the type variable `Elem`, and the `?` suffix nilable marker.
+the type variable `E`, and the `?` suffix nilable marker.
 
 When called with an `Integer` positional argument, the return value will be an
 `Array` of whatever type is contained.
 
-The `?` syntax is a convenient shorthand for a union with nil. An equivalent union type would be `(Elem | nil)`.
+The `?` syntax is a convenient shorthand for a union with nil. An equivalent union type would be `(E | nil)`.
 
 ### Keyword Arguments
 
@@ -222,9 +222,9 @@ end
 ```
 
 ```rbs
-class Array[Elem]
-  def filter: () { (Elem) -> boolish } -> ::Array[Elem]
-            | () -> ::Enumerator[Elem, ::Array[Elem]]
+class Array[E]
+  def filter: () { (E) -> boolish } -> ::Array[E]
+            | () -> ::Enumerator[E, ::Array[E]]
 end
 ```
 
@@ -264,13 +264,13 @@ a.collect.with_index {|x, i| x * i}
 ```
 
 ```rbs
-class Array[Elem]
-  def collect: [U] () { (Elem) -> U } -> Array[U]
-             | () -> Enumerator[Elem, Array[untyped]]
+class Array[E]
+  def collect: [U] () { (E) -> U } -> Array[U]
+             | () -> Enumerator[E, Array[untyped]]
 end
 ```
 
-Type variables can also be introduced in methods. Here, in `Array`'s `#collect` method, we introduce a type variable `U`. The block passed to `#collect` will receive a parameter of type `Elem`, and return a value of type `U`. Then `#collect` will return an `Array` of type `U`.
+Type variables can also be introduced in methods. Here, in `Array`'s `#collect` method, we introduce a type variable `U`. The block passed to `#collect` will receive a parameter of type `E`, and return a value of type `U`. Then `#collect` will return an `Array` of type `U`.
 
 In this example, the method receives its signature from the inferred return type of the passed block. When then block is absent, as in when the method returns an `Enumerator`, we can't infer the type, and so the return value of the enumerator can only be described as `Array[untyped]`.
 
@@ -284,9 +284,9 @@ In this example, the method receives its signature from the inferred return type
 ```
 
 ```rbs
-class Enumerable[Elem]
-  def partition: () { (Elem) -> boolish } -> [Array[Elem], Array[Elem]]
-               | () -> ::Enumerator[Elem, [Array[Elem], Array[Elem] ]]
+class Enumerable[E]
+  def partition: () { (E) -> boolish } -> [Array[E], Array[E]]
+               | () -> ::Enumerator[E, [Array[E], Array[E] ]]
 end
 ```
 
@@ -300,9 +300,9 @@ Tuples can be of any size, and they can have mixed types.
 ```
 
 ```rbs
-class Enumerable[Elem]
+class Enumerable[E]
   def to_h: () -> ::Hash[untyped, untyped]
-          | [T, U] () { (Elem) -> [T, U] } -> ::Hash[T, U]
+          | [T, U] () { (E) -> [T, U] } -> ::Hash[T, U]
 end
 ```
 

data/docs/release.md

@@ -0,0 +1,247 @@
+# Releasing RBS
+
+A release is a pull request and one workflow run. Everything that leaves the
+repository — the tag, both gems, and the GitHub release — is produced by the
+`Release gems` workflow, so nothing has to be built or pushed from a laptop.
+
+Each release ships **two gems**:
+
+| Gem | Platform | Parser |
+| --- | --- | --- |
+| `rbs-X.Y.Z.gem` | `ruby` (MRI) | C extension, compiled on install |
+| `rbs-X.Y.Z-java.gem` | `java` (JRuby) | `rbs_parser.wasm`, built by the workflow |
+
+The `-java` gem contains no native code — just `rbs_parser.wasm`. The Chicory/ASM
+jars it needs are not shipped in the gem; they are declared as `jar-dependencies`
+requirements and fetched from Maven when the gem is installed. So the gem can be
+built once in any environment and runs on every JRuby.
+
+There are three kinds of release, and they differ in what gets written up:
+
+| Version | CHANGELOG section | GitHub release |
+| --- | --- | --- |
+| `X.Y.Z` | The whole cycle since the previous release proper, prereleases included | Published |
+| `X.Y.Z.pre.N` | What changed since `X.Y.Z.pre.N-1` | Published, marked as a prerelease |
+| `X.Y.Z.dev.N` | None | None |
+
+`.dev.N` releases are cut from the development line for people who need a change
+early, so they are gems and tags and nothing else.
+
+## Prerequisites
+
+Push rights to the `rbs` gem on RubyGems are **not** needed: the workflow
+authenticates through a trusted publisher registered for this repository and
+`release-gems.yml`. What is needed is write access to the repository, since that
+is what lets you dispatch the workflow.
+
+## Steps
+
+The release pull request in step 1 is merged by a person who has reviewed it. Its merge commit is
+what step 2 dispatches, tags, and pushes to RubyGems, and none of that can be taken back — so
+prepare that pull request and stop there, rather than merging it and carrying on to step 2.
+
+The bump that starts a new minor is the only other pull request that sets `RBS::VERSION`. It
+publishes nothing and another bump undoes it, so one opened on an explicit request can go through
+on its own.
+
+### 1. Prepare the release
+
+Open a pull request that carries everything the release needs:
+
+- `lib/rbs/version.rb` — set `RBS::VERSION` to the version being released.
+- `Gemfile.lock` — run `bundle install` after the bump; the lockfile records the version too.
+- `CHANGELOG.md` — add a section for the new version, directly under the `# CHANGELOG` heading.
+  Sections are newest first.
+
+Label the pull request `skip-changelog`. It carries no change of its own, and without the label it
+shows up in the next release's list — that is why 4.1.0's changelog contains a `Version 4.1.0`
+entry.
+
+`rake gem:changelog` lists the pull requests merged since the last release, already formatted:
+
+```console
+$ bundle exec rake gem:changelog | pbcopy
+```
+
+Where it starts follows `RBS::VERSION`, so bump the version first: a prerelease starts from the
+latest tag, and a release proper skips the prerelease tags and starts from the previous release
+proper. Pass a version to override it (`rake 'gem:changelog[4.1.0]'`). Only the list goes to
+STDOUT, so it pipes cleanly. Pull requests labeled `skip-changelog` are left out and reported on
+STDERR, and pull requests that only touch `rust/` are left out because the crates have their own
+release cycle.
+
+On a release proper, the `X.Y.Z.pre.N` sections above the previous release are replaced by the one
+section being written — their pull requests are in it, and the notes they were published with stay
+on their own GitHub releases.
+
+Sort the list into the sections below. `rake gem:changelog:json` prints the same pull requests with
+the changed files, labels, and body of each, which is what the sorting is based on.
+
+```markdown
+## X.Y.Z (YYYY-MM-DD)
+
+### Signature updates
+
+### Language updates
+
+### Library changes
+
+#### rbs prototype
+
+#### rbs collection
+
+### Miscellaneous
+```
+
+The sections always appear in this order; delete the ones that end up empty, which is most of them
+on a small release. Two things scale with the size of the release:
+
+- **Summary paragraphs**, above the first section. A patch release usually has none, 4.1.0 has four
+  paragraphs, and 4.0.0 has nine.
+- **A list of the types whose signatures changed**, as the first line of `### Signature updates`,
+  written as `**Updated classes/modules/methods:**` followed by the names in backticks. Used on
+  `X.Y.0` releases only.
+
+The date is the day the gem is released, matching the `vX.Y.Z` tag — not the day this pull request
+is opened. Fix it up before step 2 if the pull request sat for a few days.
+
+### 2. Run the `Release gems` workflow
+
+Once the pull request is merged, dispatch
+[`release-gems.yml`](../.github/workflows/release-gems.yml) from the Actions tab with two inputs:
+
+| Input | Value |
+| --- | --- |
+| `commit` | The full 40-character SHA of the merge commit, taken from the merged pull request |
+| `version` | `X.Y.Z`, without the leading `v` |
+
+The ref selector picks which copy of the workflow file runs, not what gets released — leave it on
+`master`. Everything is built from `commit`, so the run is unaffected by whatever lands on `master`
+in the meantime, and a patch release cut from a release branch is dispatched the same way as any
+other: the workflow does not care which branch the commit is on.
+
+The two inputs say the same thing twice, once as a commit and once as a name, and the run stops
+before anything is built unless they agree with each other and with the repository:
+
+- `commit` has to be a full SHA that some branch contains,
+- `version` has to be the `RBS::VERSION` that commit declares,
+- CHANGELOG.md has to start with a section for `version` (skipped for `.dev.N`, which is not
+  written up),
+- `vX.Y.Z` must not exist yet.
+
+It then:
+
+- builds `rbs-X.Y.Z.gem`,
+- compiles `rbs_parser.wasm` and builds `rbs-X.Y.Z-java.gem`,
+- checks both: platforms, the C extension on one and its absence on the other, and that the wasm
+  module made it into the `java` gem,
+- installs the `java` gem on JRuby and parses with it, so the WebAssembly runtime is exercised
+  before anything is published,
+- uploads both gems as an artifact,
+- tags `commit` as `vX.Y.Z` and pushes the tag,
+- pushes both gems to RubyGems through trusted publishing,
+- publishes the GitHub release with the notes from CHANGELOG.md, skipping this last step for
+  `.dev.N` versions.
+
+The tag is created once both gems are known to build and run, and before anything is published: a
+tag can be deleted, while a version pushed to RubyGems can only be yanked.
+
+Checking the `dry_run` box runs everything up to the artifact and stops — no tag, no gems pushed,
+no release — which is how the build is exercised without releasing. `version` still has to match
+the commit, so a dry run is also how a release is rehearsed before it is cut.
+
+## The version on `master`
+
+`RBS::VERSION` on `master` is read one of two ways, told apart by how the version ends:
+
+| On `master` | Means |
+| --- | --- |
+| `X.Y.0.dev` — a bare `.dev` | `X.Y.0` is being developed |
+| A complete version — `X.Y.Z`, `X.Y.Z.pre.N`, `X.Y.Z.dev.N` | The version *after* the one named is being developed |
+
+So `4.1.1` on `master` is not a claim that `master` is 4.1.1. It says 4.1.1 has shipped and what
+comes after it is being worked on. `4.1.2.dev.1` says the same thing about itself: that release is
+out, and the line continues towards 4.1.2.
+
+Both become true the moment the release is tagged, so **nothing has to be done to `master` after a
+release**. `4.0.1` was followed by `4.0.2` with no version change in between, and `4.1.2.dev.1` is
+what `master` carries today.
+
+The bare `X.Y.0.dev` is the exception because it is the one version that names a target rather than
+a predecessor: a new minor is developed towards `X.Y.0` for a long time, before it is known whether
+the next thing to ship is `X.Y.0.pre.1` or `X.Y.0` itself. Setting it is the only version change
+that has to be made deliberately.
+
+`rake gem:changelog` reads `RBS::VERSION` too, to decide where the next changelog starts — but the
+version is set to the one being released before the changelog is generated, so it sees that rather
+than whatever `master` was carrying.
+
+## Starting a new minor
+
+`master` is the development line of one minor at a time. Moving it from `X.Y` to `X.(Y+1)` is not
+part of any one release — it is the decision that the `X.Y` line is done, taken whenever that
+becomes true — and it is the one moment the version on `master` is changed by hand. Two changes, in
+opposite places:
+
+1. **Branch the line being left behind**, from the last `master` commit that belongs to it:
+
+   ```console
+   $ git switch --create aaa-X.Y.x <that commit>
+   $ git push -u origin aaa-X.Y.x
+   ```
+
+   Branch from the commit *before* the bump below, so the branch keeps the version its line was
+   released under. Patch releases of `X.Y` are cut from here from now on, with their changes
+   cherry-picked from `master` — see [Backports](#backports). The `aaa-` prefix carries no meaning
+   beyond sorting the release branches to the top of the branch list.
+
+2. **Bump `master`** to `X.(Y+1).0.dev`, in a pull request with `Gemfile.lock` regenerated and
+   labeled `skip-changelog` like the release pull request itself. `4.1` was started exactly this
+   way: `aaa-4.0.x` was branched at the commit before `Start 4.1 development`, which set
+   `RBS::VERSION` to `4.1.0.dev`.
+
+Two loose ends that are easy to forget:
+
+- **The release note of the new line.** `rake gem:gh_release` links every published release to
+  `https://github.com/ruby/rbs/wiki/Release-Note-X.Y`, built from the version number without
+  checking that the page is there. Nothing has to be written when the line starts — the page comes
+  together as the first release proper of the line comes into view — but it does have to exist by
+  the time that release is published, or its notes link to an empty page.
+- **Release branches that are done.** A branch is worth keeping only while its line might still
+  get a patch. The ones that exist do not cover every line that ever had one — `3.8.1` shipped and
+  there is no `aaa-3.8.x` — so this is housekeeping rather than a rule, but starting a new minor is
+  the natural moment to look at the bottom of the branch list and delete what has been superseded.
+
+## Backports
+
+A patch release is cut from a release branch (`aaa-X.Y.x`), and what it carries beyond the previous
+release is cherry-picked from the development line. Cherry-pick with `-x`:
+
+```console
+$ git cherry-pick -x <commit>
+```
+
+`-x` records the commit the change was copied from, and that recorded line is what `rake
+gem:changelog` follows to reach the pull request the change was written and reviewed in. Without
+it, the only pull request a backported commit is associated with is the one that carried the
+backport, which says nothing about the change and is the same for every commit it brought over —
+that is why the 4.0.3 changelog credits its three entries to the same pull request.
+
+## Notes
+
+- Prereleases (`X.Y.Z.pre.N`) are only installed with `gem install rbs --pre`;
+  a plain `gem install rbs` is unaffected. On JRuby, `gem install rbs [--pre]`
+  resolves to the `-java` gem automatically.
+- The WASI SDK version is pinned in `wasm.yml`, `jruby.yml`, `release-gems.yml`, and
+  `Dockerfile.jruby`, each carrying its own copy. Keep them in sync when bumping. The
+  Chicory/ASM versions are not duplicated: they are the `jar` requirements in
+  `rbs.gemspec`, which is where the workflow, `Dockerfile.jruby` and `gem install` all
+  read them from.
+- `rake 'gem:check_release[X.Y.Z]'` and `rake gem:tag` are what the workflow runs to
+  check the release and to create the tag. Both work locally, which is the fallback
+  if the tag ever has to be created by hand.
+- Those two tasks and `rake gem:gh_release` come from the Rakefile of the commit
+  being released, not from the branch the workflow was dispatched from. Releasing
+  from a release branch (`aaa-X.Y.x`) therefore needs the release tooling on that
+  branch as well; without it the run fails on the missing task, before publishing
+  anything.

data/docs/syntax.md

@@ -196,8 +196,8 @@ It is an alias of `top` type, and you can use `boolish` if we want to allow any
 We can see an example at the definition of `Enumerable#find`:
 
 ```rbs
-module Enumerable[Elem, Return]
-  def find: () { (Elem) -> boolish } -> Elem?
+module Enumerable[E, R]
+  def find: () { (E) -> boolish } -> E?
 end
 ```