steep 2.0.0 → 2.1.0.dev.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c7bef651d95df5415538e6d1a288b29395b2e49bdbabe20f3a79c51669760f7
-  data.tar.gz: a60d0fddf36b2e962d8c02802ab9f24424a2a428b07e63b5eb6c40c744fc0e71
+  metadata.gz: 9985b9a834986497b037bbe836f6646aad30fcc1dfa33cf187a3f6aea572d5c6
+  data.tar.gz: a3ef68064767f01a511e48b02598f4dffa6c403554898b59a76762a732aaa448
 SHA512:
-  metadata.gz: 66f4985fee2186d7e9a4166b8a54f34272c3d156df4fc315d56ae4246361ba7fb44a77ebd8cf0f85860abe4bc75f5b5be5fad3c36a6183be2a4060cdbdacbc7a
-  data.tar.gz: ccf6e2b72945cb200fe448532887750f1b89e08a8ad3926cdc50711164aced9fb9fec693a0981825d604592889f46f3cb4bc94e8c23e437e368955e5187c4c8d
+  metadata.gz: '018023551867526507d0b4a490a871c7b06e7bce17aedc87a1e6622d21fc5de212530fd34b94b4fc81fe45e618312433c5a4426969a27bd2144a9a84ee40c874'
+  data.tar.gz: 5d5c55850108f163260d34f0745e684efa15c922d22a9b417ac41272757c78b579656229ecf191d8e14e33b39cae015cc8fc876d8f4ccdd1fba99045e467a725

data/README.md

@@ -247,7 +247,7 @@ Use `bundle exec rake -T` to see all available tasks.
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `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 gem` workflow rather than from a working copy -- see [doc/release.md](doc/release.md).
 
 ## Contributing
 

data/Rakefile

@@ -29,210 +29,413 @@ namespace :test do
   end
 end
 
-Rake::Task[:release].enhance do
-  Rake::Task[:"release:note"].invoke
-  Rake::Task[:"release:github"].invoke
-  Rake::Task[:"release:release-prs"].invoke
-end
+# Pull requests with one of these labels are omitted from the changelog.
+CHANGELOG_SKIP_LABELS = ["skip-changelog"]
+
+# The tags a release proper starts *after*, rather than at.
+CHANGELOG_PRERELEASE_TAGS = ["v*.pre*", "v*.dev*"]
+
+# Resolves the commit-ish the changelog of the release being prepared starts from.
+#
+# `version` is a version number, a tag, or any commit-ish. When it is omitted, the base follows
+# `Steep::VERSION`:
+#
+# * `X.Y.Z.pre.N` documents what changed since `X.Y.Z.pre.N-1`, so it starts from the latest tag.
+# * `X.Y.Z` documents the whole cycle, the prereleases included, so it skips the prerelease tags
+#   in between and starts from the previous release proper.
+#
+# This is the step that is easy to get wrong by hand: on a release proper the latest tag is a
+# prerelease, so the obvious default would produce only the tail of the cycle. Passing a version
+# explicitly overrides all of it.
+#
+def changelog_base(version)
+  require "open3"
 
-desc "Generate changelog template from GH pull requests"
-task :changelog do
-  major, minor, patch, pre = Steep::VERSION.split(".", 4)
-  major = major.to_i
-  minor = minor.to_i
-  patch = patch.to_i
+  from =
+    if version
+      # `2.1.0` and `v2.1.0` both mean the tag `v2.1.0`, while `master` or a SHA is used as is.
+      version.match?(/\A\d/) ? "v#{version}" : version
+    else
+      command = ["git", "describe", "--tags", "--match", "v*", "--abbrev=0"]
+      unless Gem::Version.new(Steep::VERSION).prerelease?
+        CHANGELOG_PRERELEASE_TAGS.each { |glob| command.push("--exclude", glob) }
+      end
 
-  if patch == 0
-    milestone = "Steep #{major}.#{minor}"
-  else
-    milestone = "Steep #{major}.#{minor}.x"
-  end
+      output, status = Open3.capture2(*command)
+      raise "🚨 Cannot detect the tag the changelog starts from. Give the previous version explicitly." unless status.success?
+      output.chomp
+    end
 
-  puts "🔍 Finding pull requests that is associated to milestone `#{milestone}`..."
+  _, status = Open3.capture2("git", "rev-parse", "--verify", "--quiet", "#{from}^{commit}")
+  raise "🚨 No such commit-ish: `#{from}`" unless status.success?
 
-  command = [
-    "gh",
-    "pr",
-    "list",
-    "--json",
-    "url,title,number",
-    "--limit=100",
-    "--search" ,
-    "milestone:\"#{milestone}\" is:merged sort:updated-desc -label:Released"
-  ]
+  from
+end
 
+# Runs a GraphQL query against the repository of the working directory.
+#
+# `body` is the selection set inside `repository`, so a query can use the `$owner` and `$name`
+# variables. Returns the contents of `data.repository`.
+#
+def changelog_graphql(body)
   require "open3"
-  output, status = Open3.capture2(*command)
-  raise status.inspect unless status.success?
-
   require "json"
-  json = JSON.parse(output, symbolize_names: true)
 
-  unless json.empty?
-    puts
-    json.each do |line|
-      puts "* #{line[:title]} ([##{line[:number]}](#{line[:url]}))"
+  @changelog_repository ||=
+    begin
+      output, status = Open3.capture2("gh", "repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner")
+      raise status.inspect unless status.success?
+      output.chomp.split("/", 2)
     end
-  else
-    puts "  (🤑 There is no *unreleased* pull request associated to the milestone.)"
-  end
+  owner, name = @changelog_repository
+
+  query = <<~GRAPHQL
+    query($owner: String!, $name: String!) {
+      repository(owner: $owner, name: $name) {
+        #{body}
+      }
+    }
+  GRAPHQL
+
+  output, status = Open3.capture2(
+    "gh", "api", "graphql",
+    "-f", "query=#{query}",
+    "-f", "owner=#{owner}",
+    "-f", "name=#{name}",
+    binmode: true
+  )
+  raise status.inspect unless status.success?
+
+  # GitHub always answers in UTF-8, while the default external encoding follows the locale. Without
+  # this, a pull request body with an emoji fails to parse under `LANG=C`, as in GitHub Actions.
+  JSON.parse(output.force_encoding(Encoding::UTF_8), symbolize_names: true).dig(:data, :repository)
 end
 
-namespace :release do
-  desc "Ensure release note"
-  task :note do
-    version = Gem::Version.new(Steep::VERSION)
-    major, minor, patch, pre = Steep::VERSION.split(".", 4)
-    major = major.to_i
-    minor = minor.to_i
-    patch = patch.to_i
+# Lists the commits between `from` and `HEAD`, newest first.
+#
+def changelog_commits(from)
+  require "open3"
 
-    wiki_url = "https://github.com/soutaro/steep/wiki/Release-Note-#{major}.#{minor}"
+  output, status = Open3.capture2("git", "log", "--format=%H", "#{from}..HEAD")
+  raise status.inspect unless status.success?
 
-    puts "🧐 Checking if Release note page already exists..."
+  output.lines.map(&:chomp).reject(&:empty?)
+end
 
-    unless `curl --silent -o/dev/null --head #{wiki_url} -w '%{http_code}'` == "200"
-      pre_flag = version.prerelease? ? " --pre" : ""
-      pre_requirement = version.prerelease? ? ", '~> #{major}.#{minor}.#{patch}.#{pre}'" : ""
+# 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.
+#
+# 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.
+#
+# 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?
 
-      puts "----"
+  require "open3"
 
-      puts <<~PREFIX if patch
-        **The latest version of Steep #{major}.#{minor} is `#{pre}`.**
+  # `--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?
 
-      PREFIX
+  # 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)
 
-      puts <<~TEMPLATE
-        Some of the highlights in Steep #{major}.#{minor} are:
+  output.split("\0").each_slice(2).each_with_object({}) do |(commit, message), origins|
+    commit = commit.to_s.strip
+    next if commit.empty?
 
-        * New feature 1 (URL)
-        * New feature 2 (URL)
-        * New feature 3 (URL)
+    origin = message.to_s[CHERRY_PICK_ORIGIN, 1] or next
+    origins[commit] = origin
+  end
+end
 
-        You can install it with `$ gem install steep#{pre_flag}` or using Bundler.
+# 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: "#{oid}") {
+          ... on Commit {
+            associatedPullRequests(first: 10) {
+              nodes {
+                number title url merged
+                labels(first: 100) { nodes { name } }
+              }
+            }
+          }
+        }
+      GRAPHQL
+    end
 
-        ```rb
-        gem 'steep', require: false#{pre_requirement}
-        ```
+    response = changelog_graphql(aliases.join("\n"))
 
-        See the [CHANGELOG](https://github.com/soutaro/steep/blob/master/CHANGELOG.md) for the details.
+    slice.each_with_index do |oid, index|
+      nodes = response.dig(:"c#{index}", :associatedPullRequests, :nodes) || []
 
-        ## New feature 1
+      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
 
-        ## New feature 2
+# 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
 
-        ## New feature 3
+  [pull_requests.values, skipped.values]
+end
 
-        ## Diagnostics updates
+# Fetches the details that help classifying the pull requests: the changed files and the body.
+#
+def changelog_pull_request_details(pull_requests)
+  pull_requests.each_slice(50).flat_map do |slice|
+    aliases = slice.map do |pr|
+      <<~GRAPHQL
+        p#{pr[:number]}: pullRequest(number: #{pr[:number]}) {
+          body
+          author { login }
+          files(first: 100) {
+            nodes { path }
+            pageInfo { hasNextPage }
+          }
+        }
+      GRAPHQL
+    end
 
-        ## Updating Steep
+    details = changelog_graphql(aliases.join("\n"))
 
-      TEMPLATE
-      puts "----"
-      puts
+    slice.map do |pr|
+      detail = details[:"p#{pr[:number]}"] or next pr
 
-      puts "  ⏩️ Create the release note with the template: #{wiki_url}"
-    else
-      if patch == 0 || version.prerelease?
-        puts "  ⏩️ Open the release note and update it at: #{wiki_url}"
-      else
-        puts "  ✅ Release note is ready!"
-      end
+      pr.merge(
+        author: detail.dig(:author, :login),
+        # The body is a hint for writing the changelog, not a copy source. Keep it short.
+        body: detail[:body].to_s.strip.slice(0, 1000),
+        files: detail.dig(:files, :nodes).map { |file| file[:path] },
+        files_truncated: detail.dig(:files, :pageInfo, :hasNextPage)
+      )
     end
-    puts
   end
+end
 
-  desc "Create GitHub release automatically"
-  task :github do
-    version = Gem::Version.new(Steep::VERSION)
-    major, minor, patch, *_ = Steep::VERSION.split(".")
-    major = major.to_i
-    minor = minor.to_i
-    patch = patch.to_i
+# Reports the pull requests omitted by their label, so that they do not disappear silently.
+#
+def warn_skipped_pull_requests(skipped, skip_labels)
+  return if skipped.empty?
 
-    puts "✏️ Making a draft release on GitHub..."
+  numbers = skipped.map { |pr| "##{pr[:number]}" }
+  numbers = numbers.take(20).push("and #{numbers.size - 20} more") if numbers.size > 20
 
-    content = File.read(File.join(__dir__, "CHANGELOG.md"))
-    changelog = content.scan(/^## \d.*?(?=^## \d)/m)[0]
-    changelog = changelog.sub(/^.*\n^.*\n/, "").rstrip
+  $stderr.puts
+  $stderr.puts "  (⏭️  Skipped #{skipped.size} pull request(s) labeled #{skip_labels.map { |label| "`#{label}`" }.join(" or ")}: #{numbers.join(", ")})"
+end
 
-    notes = <<NOTES
-[Release note](https://github.com/soutaro/steep/wiki/Release-Note-#{major}.#{minor})
+# Prints the changelog template listing the pull requests merged between `from` and `HEAD`.
+#
+# The changelog goes to STDOUT and everything else goes to STDERR, so that the output can be
+# piped to another command: `rake gem:changelog | pbcopy`
+#
+def print_changelog(from, skip_labels: CHANGELOG_SKIP_LABELS)
+  $stderr.puts "🔍 Finding pull requests merged between `#{from}` and `HEAD`..."
+
+  commits = changelog_commits(from)
+  if commits.empty?
+    $stderr.puts "  (🤔 There is no commit after `#{from}`.)"
+    return
+  end
 
-#{changelog}
-NOTES
+  pull_requests, skipped = changelog_pull_requests(commits, skip_labels: skip_labels)
 
-    command = [
-      "gh",
-      "release",
-      "create",
-      "--draft",
-      "v#{Steep::VERSION}",
-      "--title=#{Steep::VERSION}",
-      "--notes=#{notes}"
-    ]
-
-    if version.prerelease?
-      command << "--prerelease"
+  if pull_requests.empty?
+    $stderr.puts "  (🤔 No pull request is associated to the commits after `#{from}`.)"
+  else
+    $stderr.puts
+    pull_requests.each do |pr|
+      puts "* #{pr[:title]} ([##{pr[:number]}](#{pr[:url]}))"
     end
+    $stdout.flush
+  end
 
-    require "open3"
-    output, status = Open3.capture2(*command)
-    if status.success?
-      puts "  ⏩️ Done! Open #{output.chomp} and publish the release!"
-      puts
+  warn_skipped_pull_requests(skipped, skip_labels)
+end
+
+# Prints the same pull requests as `print_changelog` as JSON, with the details that help
+# classifying them into the sections of CHANGELOG.md.
+#
+# This is the input for the release automation, so it always prints a valid JSON document.
+#
+def print_changelog_json(from, skip_labels: CHANGELOG_SKIP_LABELS)
+  require "json"
+
+  $stderr.puts "🔍 Finding pull requests merged between `#{from}` and `HEAD`..."
+
+  commits = changelog_commits(from)
+  pull_requests, skipped = changelog_pull_requests(commits, skip_labels: skip_labels)
+  pull_requests = changelog_pull_request_details(pull_requests)
+
+  $stderr.puts "  (📋 #{pull_requests.size} pull request(s))"
+
+  puts JSON.pretty_generate(
+    {
+      from: from,
+      to: "HEAD",
+      pull_requests: pull_requests,
+      skipped: skipped
+    }
+  )
+  $stdout.flush
+
+  warn_skipped_pull_requests(skipped, skip_labels)
+end
+
+namespace :gem do
+  desc "Generate changelog template from GH pull requests merged since the previous release"
+  task :changelog, [:version] do |_task, args|
+    print_changelog(changelog_base(args[:version]))
+  end
+
+  namespace :changelog do
+    desc "Print the pull requests of `gem:changelog` as JSON, with the changed files and body of each"
+    task :json, [:version] do |_task, args|
+      print_changelog_json(changelog_base(args[:version]))
     end
   end
 
-  desc "Add `Released` labels to pull requests associated to the version"
-  task "release-prs" do
-    major, minor, patch, pre = Steep::VERSION.split(".", 4)
-    major = major.to_i
-    minor = minor.to_i
-    patch = patch.to_i
+  # 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
 
-    if patch == 0
-      milestone = "Steep #{major}.#{minor}"
+  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[2.1.0]'`"
+    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 == Steep::VERSION or
+      raise "🚨 Releasing #{version}, but this commit declares `Steep::VERSION = #{Steep::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
-      milestone = "Steep #{major}.#{minor}.x"
+      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 Steep::VERSION"
+  task :tag do
+    tag = "v#{Steep::VERSION}"
+
+    # Annotated, so that the tag carries its own author and date rather than
+    # borrowing the tagged commit's.
+    sh "git", "tag", "--annotate", "--message", "Steep #{Steep::VERSION}", tag
+    sh "git", "push", "origin", tag
+
+    puts "🏷️  Pushed #{tag}."
+  end
+
+  desc "Publish the GitHub release for Steep::VERSION, unless it is a `.dev.` version"
+  task :gh_release do
+    require "open3"
+
+    version = Gem::Version.new(Steep::VERSION)
+    major, minor, *_ = Steep::VERSION.split(".")
+    tag = "v#{Steep::VERSION}"
 
-    if pre =~ /dev/
-      puts "🔍 Skipping `Released` tags because `dev` release: `#{pre}`"
+    if dev_release?(Steep::VERSION)
+      puts "⏭️  #{Steep::VERSION} is a dev release, so there is no GitHub release to publish."
       next
     end
 
-    puts "🔍 Finding pull requests that is associated to milestone `#{milestone}`..."
+    # The release is created against an existing tag, so that the artifacts and the
+    # notes describe a commit that is already immutable.
+    _, 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?
 
+    notes = <<~NOTES
+      [Release note](https://github.com/soutaro/steep/wiki/Release-Note-#{major}.#{minor})
+
+      #{changelog_section(Steep::VERSION)}
+    NOTES
+
+    # Published rather than drafted: the notes are the changelog section that was
+    # already reviewed in the release pull request, so there is nothing left to edit.
     command = [
-      "gh",
-      "pr",
-      "list",
-      "--json",
-      "url,title,number",
-      "--search" ,
-      "milestone:\"#{milestone}\" is:merged sort:updated-desc -label:Released"
+      "gh", "release", "create", tag,
+      "--title=#{Steep::VERSION}",
+      "--notes=#{notes}"
     ]
+    command << "--prerelease" if version.prerelease?
 
-    require "open3"
     output, status = Open3.capture2(*command)
-    raise status.inspect unless status.success?
+    raise "🚨 `gh release create` failed: #{status.inspect}" unless status.success?
 
-    require "json"
-    json = JSON.parse(output, symbolize_names: true)
-
-    puts "  ✅ Found #{json.size} PRs..."
-
-    json.each do |pr|
-      puts "🧐 Updating #{pr[:url]}..."
-      output, status = Open3.capture2("gh", "pr", "edit", pr[:number].to_s, "--add-label", "Released")
-      raise status.inspect unless status.success?
-      puts "  ✅ Done!"
-      sleep 0.5
-    end
+    puts "📝 Released #{tag}: #{output.chomp}"
   end
 end
-
 namespace :rbs do
   task :watch do
     require "listen"

data/doc/release.md

@@ -0,0 +1,264 @@
+# Releasing Steep
+
+A release is a pull request and one workflow run. Everything that leaves the
+repository — the tag, the gem, and the GitHub release — is produced by the
+`Release gem` workflow, so nothing has to be built or pushed from a laptop.
+
+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 `steep` gem on RubyGems are **not** needed: the workflow
+authenticates through a trusted publisher registered for this repository and
+`release.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 `Steep::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/steep/version.rb` — set `Steep::VERSION` to the version being released.
+- `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.
+
+`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 `Steep::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[2.0.0]'`). Only the list goes to
+STDOUT, so it pipes cleanly. Pull requests labeled `skip-changelog` are left out and reported on
+STDERR.
+
+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.
+
+Both tasks reach GitHub through `gh`, which a Claude Code on the web session cannot do. See
+[Assembling the changelog without `gh`](#assembling-the-changelog-without-gh) for how the same list
+is produced there.
+
+```markdown
+## X.Y.Z (YYYY-MM-DD)
+
+### Type checker core
+
+### Commandline tool
+
+### Language server
+
+### Miscellaneous
+```
+
+The sections always appear in this order; delete the ones that end up empty. One thing scales with
+the size of the release: **summary paragraphs**, above the first section. A patch release usually
+has none, while 2.0.0 opens with a `### Summary` describing its three major features.
+
+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 gem` workflow
+
+Once the pull request is merged, dispatch
+[`release.yml`](../.github/workflows/release.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 `Steep::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 `steep-X.Y.Z.gem`,
+- checks its metadata: the platform, no C extension, `exe/steep` and `lib/steep.rb` present, and
+  none of the development directories shipped,
+- installs the gem the way a user would and type checks a small project with it — one that has to
+  pass and one that has to fail — so the executable, the dependencies, and the type checker are
+  exercised before anything is published,
+- uploads the gem as an artifact,
+- tags `commit` as `vX.Y.Z` and pushes the tag,
+- pushes the gem 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 the gem is 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 gem 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`
+
+`Steep::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 `2.0.0` on `master` is not a claim that `master` is 2.0.0. It says 2.0.0 has shipped and what
+comes after it is being worked on. Both become true the moment the release is tagged, so **nothing
+has to be done to `master` after a release**.
+
+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 `Steep::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 labeled `skip-changelog` like the
+   release pull request itself.
+
+One loose end that is easy to forget: **the release note of the new line**. `rake gem:gh_release`
+links every published release to `https://github.com/soutaro/steep/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.
+
+## 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.
+
+## Assembling the changelog without `gh`
+
+A release can be prepared from a Claude Code on the web session, with one exception:
+`gem:changelog` and `gem:changelog:json` cannot run there. Both go through `gh`, and in such a
+session `api.github.com` is blocked at the agent proxy for anything the shell does. `gh` is not
+installed, installing it does not help, and rewriting the tasks against REST or Net::HTTP would be
+blocked the same way — the refusal is keyed on the session rather than on the client.
+
+Nothing else in the release is affected. `gem:check_release` and `gem:tag` read git and the working
+tree, and `gem:gh_release` runs on a runner, where `gh` and `github.token` both work.
+
+What the session does have is the GitHub MCP server, which reaches the API through its own
+credentials. The changelog is assembled with its tools, in the three steps the rake task takes.
+
+**1. Where the changelog starts.** The rule is `changelog_base`: a prerelease starts from the
+latest tag, a release proper skips the prerelease tags. Tags are not fetched by default.
+
+```console
+$ git fetch origin --tags
+$ git describe --tags --match 'v*' --abbrev=0 --exclude 'v*.pre*' --exclude 'v*.dev*'
+v2.0.0
+```
+
+Drop the two `--exclude` flags for a prerelease, which starts at the latest tag whatever it is.
+
+**2. The commits.**
+
+```console
+$ git log --format=%H v2.0.0..HEAD
+```
+
+**3. The pull requests they came from.** List the merged pull requests with `list_pull_requests`
+(`base: master`, `state: closed`, `sort: updated`, `direction: desc`, and `fields: number, title,
+labels, merged_at, head`), paging back until `merged_at` predates the base tag, and keep the ones
+whose `head.sha` appears in the commit list from step 2. That intersection is what the task's
+GraphQL `associatedPullRequests` query answers, reached from the other side.
+
+Then drop the pull requests labeled `skip-changelog` and format the rest newest first, which is the
+order of step 2:
+
+```markdown
+* {title} ([#{number}](https://github.com/soutaro/steep/pull/{number}))
+```
+
+Sorting them into sections needs the changed files, which `gem:changelog:json` would have supplied:
+`pull_request_read` with `get_files` per pull request, or `get` for the body.
+
+Four things about that matching, the first of which is a trap:
+
+- **Do not read the numbers from `Merge pull request #N` commit subjects.** A squashed or rebased
+  pull request never writes that subject at all. Matching `head.sha` does not have that failure
+  mode.
+- `head.sha` is in the history because this repository merges pull requests with merge commits. A
+  squashed or rebased one would need its `merge_commit_sha`, which the listing does not carry.
+- The listing reports `merged: false` for pull requests that are merged — the field is not
+  populated by that endpoint. Read `merged_at` instead.
+- On a release branch the commits are cherry-picks, so resolve the `(cherry picked from commit
+  <sha>)` trailer first and match the recorded origin, as `changelog_origins` does. Matching the
+  cherry-pick itself attributes every backport to the pull request that carried it.
+
+## Notes
+
+- Prereleases (`X.Y.Z.pre.N`) are only installed with `gem install steep --pre`; a plain
+  `gem install steep` is unaffected.
+- `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/steep/diagnostic/ruby.rb

@@ -112,7 +112,7 @@ module Steep
           send = case node.type
                  when :send, :csend
                    node
-                 when :block, :numblock
+                 when :block, :numblock, :itblock
                    node.children[0]
                  end
 
@@ -163,7 +163,7 @@ module Steep
           send = case node.type
                  when :send, :csend
                    node
-                 when :block, :numblock
+                 when :block, :numblock, :itblock
                    node.children[0]
                  end
 
@@ -245,7 +245,7 @@ module Steep
                   loc ||= node.loc.operator if node.loc.respond_to?(:operator) # steep:ignore NoMethod
                   loc ||= node.loc.selector if node.loc.respond_to?(:selector) # steep:ignore NoMethod
                   loc
-                when :block
+                when :block, :numblock, :itblock
                   node.children[0].loc.selector
                 end
           super(node: node, location: loc || node.loc.expression)
@@ -1061,7 +1061,7 @@ module Steep
         def header_line
           header =
             case node&.type
-            when :send, :csend, :block, :numblock
+            when :send, :csend, :block, :numblock, :itblock
               "The method is deprecated"
             when :const, :casgn
               "The constant is deprecated"

data/lib/steep/node_helper.rb

@@ -220,7 +220,7 @@ module Steep
 
     def private_send?(node)
       case node.type
-      when :block, :numblock
+      when :block, :numblock, :itblock
         private_send?(node.children[0])
       when :send, :csend
         receiver, = deconstruct_send_node!(node)
@@ -243,7 +243,7 @@ module Steep
         when :send, :csend, :super
           if block_node
             case block_node.type
-            when :block, :numblock
+            when :block, :numblock, :itblock
               if send_node.equal?(block_node.children[0])
                 return [send_node, block_node]
               end

data/lib/steep/services/goto_service.rb

@@ -422,7 +422,7 @@ module Steep
           when :send
             location = (_ = node.location) #: Parser::AST::_SelectorLocation
             if test_ast_location(location.selector, line: line, column: column)
-              if (parent = parents[0]) && parent.type == :block && parent.children[0] === node
+              if (parent = parents[0]) && (parent.type == :block || parent.type == :numblock || parent.type == :itblock) && parent.children[0] === node
                 node = parents[0]
               end
 

data/lib/steep/services/hover_provider/ruby.rb

@@ -103,7 +103,7 @@ module Steep
             when :send, :csend
               result_node =
                 case parents[0]&.type
-                when :block, :numblock
+                when :block, :numblock, :itblock
                   if node == parents.fetch(0).children[0]
                     parents.fetch(0)
                   else

data/lib/steep/services/signature_help_provider.rb

@@ -59,7 +59,7 @@ module Steep
               if begin_loc.end_pos <= pos && pos <= end_loc.begin_pos
                 # Given position is between open/close parens of args of send node
 
-                if parent && (parent.type == :block || parent.type == :numblock) && node.equal?(parent.children[0])
+                if parent && (parent.type == :block || parent.type == :numblock || parent.type == :itblock) && node.equal?(parent.children[0])
                   send_node = parent
                 else
                   send_node = node

data/lib/steep/source.rb

@@ -31,7 +31,7 @@ module Steep
     end
 
     def self.new_parser
-      Prism::Translation::Parser33.new(Builder.new).tap do |parser|
+      Prism::Translation::Parser34.new(Builder.new).tap do |parser|
         parser.diagnostics.all_errors_are_fatal = true
         parser.diagnostics.ignore_warnings = true
       end
@@ -257,7 +257,7 @@ module Steep
         annot.line or next
 
         case node.type
-        when :def, :module, :class, :block, :numblock, :ensure, :defs, :resbody
+        when :def, :module, :class, :block, :numblock, :itblock, :ensure, :defs, :resbody
           location = node.loc
           location.line <= annot.line && annot.line < location.last_line
         else
@@ -565,13 +565,13 @@ module Steep
                   end
                 ]
               )
-            when :numblock
-              send, size, body = node.children
+            when :numblock, :itblock
+              send, arg, body = node.children
               node = node.updated(
                 nil,
                 [
                   map_child_node(send) {|child| insert_type_node(child, child_assertions) },
-                  size,
+                  arg,
                   insert_type_node(body, child_assertions)
                 ]
               )
@@ -648,7 +648,7 @@ module Steep
         case node.type
         when :send, :csend
           node
-        when :block, :numblock
+        when :block, :numblock, :itblock
           send = node.children[0]
           case send.type
           when :send, :csend

data/lib/steep/type_construction.rb

@@ -2696,7 +2696,7 @@ module Steep
             constr.add_typing(node, type: type)
           end
 
-        when :block, :numblock, :send, :csend
+        when :block, :numblock, :itblock, :send, :csend
           synthesize_sendish(node, hint: hint, tapp: nil)
 
         when :forwarded_args, :forward_arg
@@ -2772,6 +2772,20 @@ module Steep
 
           params = Parser::AST::Node.new(:args, arg_nodes)
 
+          if send_node.type == :lambda
+            # @type var node: Parser::AST::Node & Parser::AST::_BlockNode
+            type_lambda(node, params_node: params, body_node: body, type_hint: hint)
+          else
+            type_send(node, send_node: send_node, block_params: params, block_body: body, unwrap: send_node.type == :csend, tapp: tapp, hint: hint)
+          end
+        end
+      when :itblock
+        yield_self do
+          send_node, _name, body = node.children
+
+          arg_nodes = [Parser::AST::Node.new(:procarg0, [:it])]
+          params = Parser::AST::Node.new(:args, arg_nodes)
+
           if send_node.type == :lambda
             # @type var node: Parser::AST::Node & Parser::AST::_BlockNode
             type_lambda(node, params_node: params, body_node: body, type_hint: hint)
@@ -3346,7 +3360,7 @@ module Steep
             end
           end
 
-          if node.type == :csend || ((node.type == :block || node.type == :numblock) && node.children[0].type == :csend)
+          if node.type == :csend || ((node.type == :block || node.type == :numblock || node.type == :itblock) && node.children[0].type == :csend)
             optional_type = AST::Types::Union.build(types: [call.return_type, AST::Builtin.nil_type])
             call = call.with_return_type(optional_type)
           end
@@ -3509,7 +3523,7 @@ module Steep
 
         when AST::Types::Any
           case node.type
-          when :block, :numblock
+          when :block, :numblock, :itblock
             # @type var node: Parser::AST::Node & Parser::AST::_BlockNode
             block_annotations = source.annotations(block: node, factory: checker.factory, context: nesting)
             block_params or raise

data/lib/steep/type_inference/logic_type_interpreter.rb

@@ -564,9 +564,12 @@ module Steep
                   false_types << type
                 end
               else
-                # For === (for_receiver: false), non-literal types can match the literal in truthy branch
-                # For == (for_receiver: true), non-literal types only go to falsy branch
-                true_types << AST::Types::Literal.new(value: value_node.children[0]) unless for_receiver
+                # For `==`, narrow only when the literal can be a value of `type`.
+                # e.g. `Symbol == :fatal` can be true, but `SomeClass == :fatal` cannot.
+                literal_type = AST::Types::Literal.new(value: value_node.children[0])
+                if !for_receiver || subtyping?(sub_type: literal_type, super_type: type)
+                  true_types << literal_type
+                end
                 false_types << type
               end
             end

data/lib/steep/typing.rb

@@ -106,7 +106,7 @@ module Steep
             set(body_begin_pos..body_end_pos, context)
           end
 
-        when :block, :numblock
+        when :block, :numblock, :itblock
           range = block_range(node)
           set(range, context)
 
@@ -132,7 +132,7 @@ module Steep
                         node.loc.begin.end_pos # steep:ignore NoMethod
                       end
           end_pos = node.loc.end.begin_pos # steep:ignore NoMethod
-        when :numblock
+        when :numblock, :itblock
           send_node, _ = node.children
           begin_pos = node.loc.begin.end_pos # steep:ignore NoMethod
           end_pos = node.loc.end.begin_pos # steep:ignore NoMethod
@@ -245,7 +245,7 @@ module Steep
                       node.loc.begin.end_pos # steep:ignore NoMethod
                     end
         end_pos = node.loc.end.begin_pos # steep:ignore NoMethod
-      when :numblock
+      when :numblock, :itblock
         send_node, _ = node.children
         begin_pos = node.loc.begin.end_pos # steep:ignore NoMethod
         end_pos = node.loc.end.begin_pos # steep:ignore NoMethod

data/lib/steep/version.rb

@@ -1,3 +1,3 @@
 module Steep
-  VERSION = "2.0.0"
+  VERSION = "2.1.0.dev.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: steep
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0.dev.1
 platform: ruby
 authors:
 - Soutaro Matsumoto
@@ -267,6 +267,7 @@ files:
 - bin/steep-check.rb
 - bin/steep-prof
 - doc/narrowing.md
+- doc/release.md
 - doc/shape.md
 - exe/steep
 - guides/README.md
@@ -448,7 +449,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Gradual Typing for Ruby
 test_files: []