rbs 4.1.1.pre.1-java → 4.1.2-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e68e5f0ead2c31e8a4ba1e8d597c4a9f6f93880edbddbf77c7a330a8a55d196f
-  data.tar.gz: 64b5a5eb90cbfc1bf70489401d2d30e9998b1e579bcbc81f1459871c8c339023
+  metadata.gz: 7f6e4569588dd9eedcb1ba5870467a07929b78d4835efd094a61c0961f4452f7
+  data.tar.gz: e276b9379a7745f1886551f618ad059e5d75fa876729815311d40c18d8779709
 SHA512:
-  metadata.gz: b5536aaba1814d05dfd3c6f4e3466f2c54e57f9a8544e95fb16fdd4e06d0f2867d412a17dd3679090253a3b9513f185af971acd1daf8bbf46541990f0a2ef6a8
-  data.tar.gz: cc1f700e6b09443afe850e8c65a48f54000ce5ccc6cbf68072c837a193b9f7c63f6556c9db03752464daf7fc9376ff7053ef1c312707bfdf4da300dabbf6f34e
+  metadata.gz: 34148f72eaa920f876182110b854974b4554b5bc20589148254569b07201d083b3705330dee501c459b2241e5516a4166bd03013996647642c316f9a88506c0a
+  data.tar.gz: 2f19729a93364aeda81c447b1f232a7fbc3ad37ebd74e0a23f3d3176bbaddcf2c303c235f355d92b58be545620583b540a6ef666f8f63d5b8fa6ba40ffe4d393

data/.github/workflows/jruby.yml

@@ -64,12 +64,7 @@ jobs:
           ruby-version: jruby
           bundler: none
       - name: Install runtime and test gems
-        # rdoc 8.0.0 added a runtime dependency on rbs, which pulls the released
-        # C-extension rbs gem and fails to build on JRuby. Pin rdoc below 8 until
-        # a -java rbs gem is published.
-        run: |
-          gem install prism rake rake-compiler test-unit rspec minitest json-schema pry --no-document
-          gem install rdoc -v "< 8" --no-document
+        run: gem install prism rake rake-compiler test-unit rdoc rspec minitest json-schema pry --no-document
       # jar-dependencies resolves through the JVM, so download the Chicory/ASM
       # jars into ~/.m2 here on JRuby (jar-dependencies is not available in the
       # CRuby step above).

data/.github/workflows/release-gems.yml

@@ -1,12 +1,17 @@
 name: Release gems
 
-# Builds, publishes, and announces a release. Dispatch it against the `vX.Y.Z` tag
-# of the release: the tag is created first so that everything published afterwards
-# traces back to an immutable ref, and so the reversible step comes before the
-# irreversible one.
+# Builds, publishes, and announces a release. Dispatch it with the commit being
+# released and the version that commit declares.
 #
-# Dispatching against a branch builds and verifies the gems and stops there, which
-# is how the build is exercised without releasing anything.
+# Everything is built from `commit`, not from wherever the default branch happens to
+# be when the run starts, so the release describes a state that is already immutable.
+# `version` is the same fact stated a second time -- the run stops before anything is
+# built unless it matches the `RBS::VERSION` of that commit, so dispatching the wrong
+# commit, or the right one under the wrong name, is a failed run rather than a gem
+# that has to be yanked.
+#
+# `dry_run` builds and checks both gems and stops before the tag, which is how the
+# build is exercised without releasing anything.
 #
 # | Gem                  | Platform      | Parser                           |
 # | -------------------- | ------------- | -------------------------------- |
@@ -19,11 +24,26 @@ name: Release gems
 #
 # One job on purpose. Tagging, pushing the gems, and opening the GitHub release
 # all belong to a single release, and keeping them in one place keeps their order
-# readable -- the tag is created before anything is published, so the reversible
-# step comes before the irreversible one.
+# readable -- the tag is created once both gems are known to build and run, and
+# before anything is published, so the reversible step comes before the irreversible
+# one.
+#
+# The file name is what the RubyGems trusted publisher for `rbs` is registered
+# against, so it cannot be renamed without registering the new name first.
 
 on:
   workflow_dispatch:
+    inputs:
+      commit:
+        description: "Commit to release, as a full 40-character SHA"
+        required: true
+      version:
+        description: "Version to release, without the leading `v` (e.g. `4.1.2`)"
+        required: true
+      dry_run:
+        description: "Build and check the gems without tagging or publishing anything"
+        type: boolean
+        default: false
 
 permissions:
   contents: read
@@ -38,12 +58,60 @@ jobs:
     name: release
     runs-on: ubuntu-latest
     permissions:
-      contents: write # publish the GitHub release
+      contents: write # push the tag, publish the GitHub release
       id-token: write # trusted publishing to RubyGems
+    env:
+      # The inputs are read through the environment rather than interpolated into
+      # the scripts below.
+      COMMIT: ${{ inputs.commit }}
+      VERSION: ${{ inputs.version }}
+      TAG: v${{ inputs.version }}
     steps:
       # The gemspec takes its file list from `git ls-files`, so both gems are built
-      # from the committed state.
+      # from the committed state -- of the dispatched commit, since that is what is
+      # checked out. The full history is needed to tell which branches contain it.
       - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.commit }}
+          fetch-depth: 0
+
+      # Before anything is installed or built: these are the two things the release
+      # is named after and built from, and a mistake in either is cheapest to catch
+      # here.
+      - name: Check the inputs
+        run: |
+          if [[ ! "$COMMIT" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "::error::\`$COMMIT\` is not a full 40-character SHA. A release names one exact commit."
+            exit 1
+          fi
+          if [[ ! "$VERSION" =~ ^[0-9][0-9a-zA-Z.]*$ ]]; then
+            echo "::error::\`$VERSION\` is not a version number. Pass it without the leading \`v\`."
+            exit 1
+          fi
+
+          # A release proper is cut from the default branch, while a patch release can
+          # be cut from a release branch, so which branch the commit is on is not this
+          # workflow's business. That it is on one is: a commit no branch contains is
+          # one that nothing in the repository leads to any more.
+          git fetch --no-tags origin "+refs/heads/*:refs/remotes/origin/*"
+          branches=$(git branch --remotes --contains "$COMMIT" --format "%(refname:lstrip=3)")
+          if [ -z "$branches" ]; then
+            echo "::error::$COMMIT is not on any branch."
+            exit 1
+          fi
+          echo "Branches containing $COMMIT:"
+          printf '%s\n' "$branches"
+
+      # A tag that already exists is a version that has already been released, and
+      # pushing it would fail after the build rather than before it.
+      - name: Check that the tag does not exist
+        if: ${{ !inputs.dry_run }}
+        run: |
+          if git ls-remote --exit-code --tags origin "refs/tags/$TAG" > /dev/null; then
+            echo "::error::$TAG already exists, so $VERSION has been released."
+            exit 1
+          fi
+
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -56,25 +124,16 @@ jobs:
           bundle config set --local without libs:profilers
           bundle install --jobs 4 --retry 3
 
-      - name: Read the version
-        id: version
-        run: echo "version=$(ruby -e 'load "lib/rbs/version.rb"; print RBS::VERSION')" >> "$GITHUB_OUTPUT"
-
-      # Fail before spending a minute on the build, and before anything is pushed:
-      # the tag is what the release is named after, so it has to be the version the
-      # tagged commit actually declares.
-      - name: Check the tag against RBS::VERSION
-        if: github.ref_type == 'tag'
-        run: |
-          if [ "${{ github.ref_name }}" != "v${{ steps.version.outputs.version }}" ]; then
-            echo "::error::tag ${{ github.ref_name }} does not match RBS::VERSION ${{ steps.version.outputs.version }}"
-            exit 1
-          fi
+      # Fails before a minute is spent on the build, and before anything is pushed:
+      # the version has to be the one the released commit declares, and -- unless
+      # this is a `.dev.N` release -- the one CHANGELOG.md is written up for.
+      - name: Check the version and the changelog
+        run: bundle exec rake "gem:check_release[$VERSION]"
 
       - name: Build the ruby gem
         run: |
           mkdir -p pkg
-          gem build rbs.gemspec -o "pkg/rbs-${{ steps.version.outputs.version }}.gem"
+          gem build rbs.gemspec -o "pkg/rbs-$VERSION.gem"
 
       # `rake wasm:jruby_setup` compiles src/**/*.c to WebAssembly and copies the
       # result to lib/rbs/wasm/, where the gemspec picks it up. clang runs as a
@@ -91,7 +150,7 @@ jobs:
       - name: Build the java gem
         env:
           RBS_PLATFORM: java
-        run: gem build rbs.gemspec -o "pkg/rbs-${{ steps.version.outputs.version }}-java.gem"
+        run: gem build rbs.gemspec -o "pkg/rbs-$VERSION-java.gem"
 
       # `git ls-files` vouches for everything else, but rbs_parser.wasm is a build
       # artifact, so the java gem is the one that can come out quietly wrong.
@@ -108,8 +167,7 @@ jobs:
             raise "the java gem must not declare an extension" unless java_gem.extensions.empty?
 
             [ruby_gem, java_gem].each { puts "#{_1.full_name}: #{_1.files.size} files" }
-          ' "pkg/rbs-${{ steps.version.outputs.version }}.gem" \
-            "pkg/rbs-${{ steps.version.outputs.version }}-java.gem"
+          ' "pkg/rbs-$VERSION.gem" "pkg/rbs-$VERSION-java.gem"
 
       # The checks above cannot tell whether rbs_parser.wasm actually runs. Install
       # the gem the way a user would -- jar-dependencies fetches Chicory and ASM
@@ -122,7 +180,7 @@ jobs:
           bundler: none
       - name: Check the java gem on JRuby
         run: |
-          gem install "pkg/rbs-${{ steps.version.outputs.version }}-java.gem"
+          gem install "pkg/rbs-$VERSION-java.gem"
           ruby -e '
             require "rbs"
             _, _, decls = RBS::Parser.parse_signature("class Foo end")
@@ -138,27 +196,40 @@ jobs:
           bundler: none
 
       # Uploaded before publishing, so a failed push still leaves the gems behind.
+      # This is also where a dry run ends.
       - uses: actions/upload-artifact@v7
         with:
           name: gems
           path: pkg/*.gem
           if-no-files-found: error
 
-      # Everything below runs only for a release tag.
+      # Everything below runs only for a real release.
+
+      # The tag comes after the 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. What it names was decided by the checkout rather than by the
+      # tagging, so nothing rests on it being created first.
+      - name: Tag the release
+        if: ${{ !inputs.dry_run }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          bundle exec rake gem:tag
+
       - name: Configure RubyGems credentials
-        if: github.ref_type == 'tag'
+        if: ${{ !inputs.dry_run }}
         # No floating major tag on this action, so the exact release is pinned.
         uses: rubygems/configure-rubygems-credentials@v2.1.0
 
       - name: Push the gems
-        if: github.ref_type == 'tag'
+        if: ${{ !inputs.dry_run }}
         run: |
-          gem push "pkg/rbs-${{ steps.version.outputs.version }}.gem"
-          gem push "pkg/rbs-${{ steps.version.outputs.version }}-java.gem"
+          gem push "pkg/rbs-$VERSION.gem"
+          gem push "pkg/rbs-$VERSION-java.gem"
 
       # Last, so that a failed push never announces a release that has no gems.
       - name: Publish the GitHub release
-        if: github.ref_type == 'tag'
+        if: ${{ !inputs.dry_run }}
         env:
           GH_TOKEN: ${{ github.token }}
         run: bundle exec rake gem:gh_release

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 # CHANGELOG
 
-## 4.1.1.pre.1 (2026-07-30)
+## 4.1.2 (2026-08-03)
+
+### Miscellaneous
+
+* Keep GC disabled during GC_test#test_stress_and_stress= ([#3061](https://github.com/ruby/rbs/pull/3061))
+* Fix GC_test#test_enable leaving GC disabled for the rest of the suite ([#3059](https://github.com/ruby/rbs/pull/3059))
+
+## 4.1.1 (2026-07-30)
 
 ### Library changes
 
@@ -99,6 +106,14 @@ This release also introduces `RBS::Rewriter`, an API to edit RBS source text whi
 * ci: skip Gemfile.lock BUNDLED WITH on ruby-head ([#2952](https://github.com/ruby/rbs/pull/2952))
 * Remove `logger` from sig dependencies ([#2904](https://github.com/ruby/rbs/pull/2904))
 
+## 4.0.3 (2026-06-18)
+
+### Miscellaneous
+
+* Fix Ruby CI failure with compressed `Zlib::GzipReader` test fixtures. ([#3005](https://github.com/ruby/rbs/pull/3005))
+* Fix flaky `DirSingletonTest#test_fchdir` and `DirSingletonTest#test_for_fd` under aggressive GC. ([#3005](https://github.com/ruby/rbs/pull/3005))
+* Fix Ruby head CI failure caused by the lockfile-pinned Bundler version. ([#3005](https://github.com/ruby/rbs/pull/3005))
+
 ## 4.0.2 (2026-03-25)
 
 ### Library changes

data/README.md

@@ -196,7 +196,7 @@ Here is a list of some places you can talk with active maintainers.
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. Releases are cut by the `Release gems` workflow rather than from a working copy -- see [docs/release.md](docs/release.md).
 
 ### C Code Formatting
 

data/Rakefile

@@ -438,73 +438,6 @@ task :test_generate_stdlib do
   sh "ruby -c /tmp/Thread_Mutex_test.rb"
 end
 
-Rake::Task[:release].enhance do
-  Rake::Task[:"release:note"].invoke
-end
-
-namespace :release do
-  desc "Explain the post-release steps automatically"
-  task :note do
-    version = Gem::Version.new(RBS::VERSION)
-    major, minor, patch, *_ = RBS::VERSION.split(".")
-    major = major.to_i
-    minor = minor.to_i
-    patch = patch.to_i
-
-    puts "🎉🎉🎉🎉 Congratulations for **#{version}** release! 🎉🎉🎉🎉"
-    puts
-    puts "There are a few things left to complete the release. 💪"
-    puts
-
-    if patch == 0 || version.prerelease?
-      puts "* [ ] Update release note: https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor}"
-    end
-
-    if patch == 0 && !version.prerelease?
-      puts "* [ ] Delete `RBS XYZ is the latest version of...` from release note: https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor}"
-    end
-
-    puts "* [ ] Publish a release at GitHub"
-    puts "* [ ] Make some announcements on Twitter/Mustdon/Slack/???"
-
-    puts
-    puts
-
-    puts "✏️ Making a draft release on GitHub..."
-
-    content = File.read(File.join(__dir__, "CHANGELOG.md"))
-    changelog = content.scan(/^## \d.*?(?=^## \d)/m)[0]
-    changelog = changelog.sub(/^.*\n^.*\n/, "").rstrip
-
-    notes = <<NOTES
-[Release note](https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor})
-
-#{changelog}
-NOTES
-
-    command = [
-      "gh",
-      "release",
-      "create",
-      "--draft",
-      "v#{RBS::VERSION}",
-      "--title=#{RBS::VERSION}",
-      "--notes=#{notes}"
-    ]
-
-    if version.prerelease?
-      command << "--prerelease"
-    end
-
-    require "open3"
-    output, status = Open3.capture2(*command)
-    if status.success?
-      puts "  >> Done! Open #{output.chomp} and publish the release!"
-    end
-  end
-end
-
-
 # Pull requests with one of these labels are omitted from the changelog.
 CHANGELOG_SKIP_LABELS = ["skip-changelog"]
 
@@ -594,20 +527,54 @@ def changelog_commits(from, paths: [])
   output.lines.map(&:chomp).reject(&:empty?)
 end
 
-# Finds the pull requests the commits came from, keeping the order of `commits`.
+# What `git cherry-pick -x` appends to the message of the commit it creates.
+CHERRY_PICK_ORIGIN = /^\(cherry picked from commit ([0-9a-f]{40})\)$/
+
+# Maps the commits that record where they were cherry-picked from to that commit.
 #
-# Returns the pull requests for the changelog and the ones omitted by `skip_labels`.
+# A backport is a cherry-pick, so on a release branch it is the recorded origin, not the commit
+# itself, that leads to the pull request the change was written and reviewed in. Without this a
+# backported change is attributed to the pull request that carried the backport, which says
+# nothing about the change and is the same for every commit it brought over.
 #
-def changelog_pull_requests(commits, skip_labels: CHANGELOG_SKIP_LABELS)
-  pull_requests = {}
-  skipped = {}
+# A commit backported twice -- the development line, then a release branch -- carries one line
+# per hop, appended in order, so the first one is where the change started.
+#
+def changelog_origins(commits)
+  return {} if commits.empty?
+
+  require "open3"
+
+  # `--no-walk` prints these commits and nothing else. NUL delimiters keep a commit message --
+  # which can contain anything, including what this format looks like -- from being read as the
+  # format itself.
+  output, status = Open3.capture2("git", "log", "--no-walk", "--format=%H%x00%B%x00", *commits, binmode: true)
+  raise status.inspect unless status.success?
+
+  # Commit messages are UTF-8, while the default external encoding follows the locale. Without
+  # this, splitting a message that is not ASCII fails under `LANG=C`, as in GitHub Actions.
+  output.force_encoding(Encoding::UTF_8)
 
-  commits.each_slice(50) do |slice|
-    # Ask GitHub which pull requests the commits came from, so that any merge strategy -- merge
-    # commit, squash, or rebase -- is handled without parsing commit messages.
-    aliases = slice.map.with_index do |commit, index|
+  output.split("\0").each_slice(2).each_with_object({}) do |(commit, message), origins|
+    commit = commit.to_s.strip
+    next if commit.empty?
+
+    origin = message.to_s[CHERRY_PICK_ORIGIN, 1] or next
+    origins[commit] = origin
+  end
+end
+
+# Asks GitHub which pull requests each commit came from, so that any merge strategy -- merge
+# commit, squash, or rebase -- is handled without parsing commit messages.
+#
+# Returns `{ oid => [pull request, ...] }`, with an empty array for the commits GitHub has no
+# merged pull request for, including the ones it does not know at all.
+#
+def changelog_associated_pull_requests(oids)
+  oids.uniq.each_slice(50).each_with_object({}) do |slice, found|
+    aliases = slice.map.with_index do |oid, index|
       <<~GRAPHQL
-        c#{index}: object(oid: "#{commit}") {
+        c#{index}: object(oid: "#{oid}") {
           ... on Commit {
             associatedPullRequests(first: 10) {
               nodes {
@@ -620,18 +587,44 @@ def changelog_pull_requests(commits, skip_labels: CHANGELOG_SKIP_LABELS)
       GRAPHQL
     end
 
-    changelog_graphql(aliases.join("\n")).each_value do |commit|
-      next unless commit
+    response = changelog_graphql(aliases.join("\n"))
 
-      commit.dig(:associatedPullRequests, :nodes).each do |pr|
-        next unless pr[:merged]
+    slice.each_with_index do |oid, index|
+      nodes = response.dig(:"c#{index}", :associatedPullRequests, :nodes) || []
 
-        pr = { number: pr[:number], title: pr[:title], url: pr[:url], labels: pr.dig(:labels, :nodes).map { |label| label[:name] } }
-        if (pr[:labels] & skip_labels).empty?
-          pull_requests[pr[:number]] ||= pr
-        else
-          skipped[pr[:number]] ||= pr
-        end
+      found[oid] = nodes.select { |pr| pr[:merged] }.map do |pr|
+        { number: pr[:number], title: pr[:title], url: pr[:url], labels: pr.dig(:labels, :nodes).map { |label| label[:name] } }
+      end
+    end
+  end
+end
+
+# Finds the pull requests the commits came from, keeping the order of `commits`.
+#
+# Returns the pull requests for the changelog and the ones omitted by `skip_labels`.
+#
+def changelog_pull_requests(commits, skip_labels: CHANGELOG_SKIP_LABELS)
+  origins = changelog_origins(commits)
+  found = changelog_associated_pull_requests(commits.map { |commit| origins[commit] || commit })
+
+  # An origin that leads nowhere -- a commit cherry-picked from a fork, or one that went to the
+  # default branch without a pull request -- falls back to the commit in this history, which is
+  # at least the backport that brought it here.
+  fallbacks = commits.select { |commit| origins[commit] && found.fetch(origins[commit], []).empty? }
+  found.update(changelog_associated_pull_requests(fallbacks)) unless fallbacks.empty?
+
+  pull_requests = {}
+  skipped = {}
+
+  commits.each do |commit|
+    prs = found.fetch(origins[commit] || commit, [])
+    prs = found.fetch(commit, []) if prs.empty?
+
+    prs.each do |pr|
+      if (pr[:labels] & skip_labels).empty?
+        pull_requests[pr[:number]] ||= pr
+      else
+        skipped[pr[:number]] ||= pr
       end
     end
   end
@@ -779,6 +772,60 @@ namespace :gem do
     end
   end
 
+  # There are three kinds of release: `X.Y.Z`, `X.Y.Z.pre.N`, and `X.Y.Z.dev.N`. The
+  # `.dev.N` ones are cut from the development line for people who need a specific
+  # change early; they are not written up in the changelog, so there are no notes to
+  # publish and nothing worth announcing.
+  def dev_release?(version)
+    Gem::Version.new(version).segments.include?("dev")
+  end
+
+  # The body of the topmost section of CHANGELOG.md, which is the release being
+  # prepared, minus its own heading.
+  #
+  # The encoding is explicit because the default external encoding follows the
+  # locale, and the changelog is not ASCII.
+  #
+  def changelog_section(version)
+    content = File.read(File.join(__dir__, "CHANGELOG.md"), encoding: Encoding::UTF_8)
+    section = content.scan(/^## \d.*?(?=^## \d)/m)[0] or raise "🚨 Cannot find a release section in CHANGELOG.md"
+    heading, _, body = section.partition("\n")
+    heading.include?(version) or raise "🚨 CHANGELOG.md starts with `#{heading.strip}`, which is not #{version}"
+    body.strip
+  end
+
+  desc "Check that the working tree is ready to be released as the given version"
+  task :check_release, [:version] do |_task, args|
+    version = args[:version] or raise "🚨 Pass the version being released: `rake 'gem:check_release[4.1.2]'`"
+    Gem::Version.correct?(version) or raise "🚨 `#{version}` is not a version number."
+
+    # The version being released and the version the commit declares are stated
+    # separately -- one by whoever starts the release, one by the commit itself --
+    # so that releasing the wrong commit, or releasing the right one under the wrong
+    # name, fails here rather than on RubyGems.
+    version == RBS::VERSION or
+      raise "🚨 Releasing #{version}, but this commit declares `RBS::VERSION = #{RBS::VERSION.inspect}`."
+
+    if dev_release?(version)
+      puts "✅ #{version} is the version of this commit. It is a dev release, so CHANGELOG.md is not checked."
+    else
+      changelog_section(version)
+      puts "✅ #{version} is the version of this commit, and CHANGELOG.md documents it."
+    end
+  end
+
+  desc "Create and push the `vX.Y.Z` tag for RBS::VERSION"
+  task :tag do
+    tag = "v#{RBS::VERSION}"
+
+    # Annotated, so that the tag carries its own author and date rather than
+    # borrowing the tagged commit's.
+    sh "git", "tag", "--annotate", "--message", "RBS #{RBS::VERSION}", tag
+    sh "git", "push", "origin", tag
+
+    puts "🏷️  Pushed #{tag}."
+  end
+
   desc "Publish the GitHub release for RBS::VERSION, unless it is a `.dev.` version"
   task :gh_release do
     require "open3"
@@ -787,11 +834,7 @@ namespace :gem do
     major, minor, *_ = RBS::VERSION.split(".")
     tag = "v#{RBS::VERSION}"
 
-    # There are three kinds of release: `X.Y.Z`, `X.Y.Z.pre.N`, and `X.Y.Z.dev.N`.
-    # The `.dev.N` ones are cut from the development line for people who need a
-    # specific change early; they are not written up in the changelog, so there are
-    # no notes to publish and nothing worth announcing.
-    if version.segments.include?("dev")
+    if dev_release?(RBS::VERSION)
       puts "⏭️  #{RBS::VERSION} is a dev release, so there is no GitHub release to publish."
       next
     end
@@ -801,18 +844,10 @@ namespace :gem do
     _, status = Open3.capture2("git", "rev-parse", "--verify", "--quiet", "#{tag}^{commit}")
     raise "🚨 No such tag: `#{tag}`. Tag the release before creating the GitHub release." unless status.success?
 
-    # The topmost section of the changelog is this release, minus its own heading.
-    # The encoding is explicit because the default external encoding follows the
-    # locale, and the changelog is not ASCII.
-    content = File.read(File.join(__dir__, "CHANGELOG.md"), encoding: Encoding::UTF_8)
-    section = content.scan(/^## \d.*?(?=^## \d)/m)[0] or raise "🚨 Cannot find a release section in CHANGELOG.md"
-    heading, _, body = section.partition("\n")
-    heading.include?(RBS::VERSION) or raise "🚨 CHANGELOG.md starts with `#{heading.strip}`, which is not #{RBS::VERSION}"
-
     notes = <<~NOTES
       [Release note](https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor})
 
-      #{body.strip}
+      #{changelog_section(RBS::VERSION)}
     NOTES
 
     # Published rather than drafted: the notes are the changelog section that was

data/docs/release.md

@@ -1,8 +1,8 @@
 # Releasing RBS
 
-A release is a pull request, a tag, and one workflow run. Everything that leaves
-the repository — both gems and the GitHub release — is produced by the `Release
-gems` workflow, so nothing has to be built or pushed from a laptop.
+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**:
 
@@ -36,6 +36,14 @@ 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:
@@ -97,26 +105,29 @@ on a small release. Two things scale with the size of the release:
 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. Tag the release
+### 2. Run the `Release gems` workflow
 
-Once the pull request is merged, tag the merge commit and push the tag:
+Once the pull request is merged, dispatch
+[`release-gems.yml`](../.github/workflows/release-gems.yml) from the Actions tab with two inputs:
 
-```console
-$ git switch master && git pull
-$ git tag "v$(ruby -e 'load "lib/rbs/version.rb"; print RBS::VERSION')"
-$ git push origin --tags
-```
+| 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 tag comes before anything is published, so that the gems and the release notes describe a
-commit that is already immutable — and because a tag can be deleted, while a version pushed to
-RubyGems can only be yanked.
+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.
 
-### 3. Run the `Release gems` workflow against the tag
+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:
 
-Dispatch [`release-gems.yml`](../.github/workflows/release-gems.yml) from the Actions tab, picking
-the `vX.Y.Z` tag — **not** a branch — in the ref selector. The trusted publisher has no branch
-condition, so the ref you pick is what decides what gets published; the workflow refuses to run
-unless the tag matches `RBS::VERSION`.
+- `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:
 
@@ -127,25 +138,110 @@ It then:
 - 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,
-- pushes both to RubyGems through trusted publishing,
+- 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.
 
-Dispatching against a branch runs everything up to the artifact and stops, which is how the build
-is exercised without releasing.
+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.
 
-### 4. Start the next development cycle
+## 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>
+```
 
-Open another pull request setting `RBS::VERSION` to the next prerelease (`4.1.1` → `4.1.2.pre`),
-with `Gemfile.lock` regenerated, labeled `skip-changelog` like the release pull request itself.
-Without it the version on `master` keeps claiming to be the released version for the whole
-development period, and `rake gem:changelog` reads that version to decide where the next changelog
-starts.
+`-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.
-- `Dockerfile.jruby` pins the WASI SDK / Chicory / ASM versions to match the
-  `wasm`, `jruby`, and `release-gems` workflows. Keep them in sync when bumping.
+- 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/lib/rbs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RBS
-  VERSION = "4.1.1.pre.1"
+  VERSION = "4.1.2"
 end

data/wasm/README.md

@@ -27,6 +27,39 @@ $ rake wasm:install_jars # download the Chicory/ASM jars into ~/.m2 (run on JRub
 
 The compiled `rbs_parser.wasm` is a build artifact and is not checked in.
 
+The WASI SDK is needed for the *build*, not for running the result — the host clang already
+knows the `wasm32` target, but there is no wasm32 libc on a normal machine, so it picks up the
+host headers and fails on the first `#include`. That is what the SDK supplies, along with the
+builtins the link step needs.
+
+## Running the suite on JRuby
+
+[`Dockerfile.jruby`](../Dockerfile.jruby) builds an image that has everything this needs, so no
+JRuby, JDK or WASI SDK has to be installed to work on the JRuby side:
+
+```console
+$ docker build -f Dockerfile.jruby -t rbs-jruby .
+$ docker run --rm rbs-jruby                                  # run the test suite
+$ docker run --rm -e RBS_PLATFORM=java rbs-jruby \
+    gem build rbs.gemspec                                    # build the -java gem
+```
+
+Two things in it are not obvious:
+
+- `build-essential` is for prism, which builds `libprism.so` and loads it through FFI on JRuby
+  rather than as an MRI C extension. It needs `cc` and `make`.
+- Bundler is skipped. The development `Gemfile` pulls in CRuby-only C extensions (bigdecimal,
+  stackprof, …) that cannot build on JRuby, so the few gems the suite needs are installed
+  directly, in the same set as [`jruby.yml`](../.github/workflows/jruby.yml).
+
+The image compiles `rbs_parser.wasm` itself, which is why it carries the WASI SDK. That is not
+the only arrangement: the build needs the SDK but not JRuby, and running the suite needs JRuby
+but not the SDK, so `jruby.yml` splits them instead — it compiles the module on CRuby and then
+switches engines to test against the result.
+
+`rake wasm:install_jars` is the step that has to be on JRuby either way: it resolves the `jar`
+requirements from `rbs.gemspec` through the JVM.
+
 ## Exported functions
 
 The module is built as a "reactor": it has no `main`, and the host calls

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbs
 version: !ruby/object:Gem::Version
-  version: 4.1.1.pre.1
+  version: 4.1.2
 platform: java
 authors:
 - Soutaro Matsumoto