gem_kit-release 0.1.0 → 0.2.0

data/lib/gem_kit/release/gate.rb

@@ -23,7 +23,7 @@ module GemKit
       def deprecation_problems(version)
         project.load!
 
-        Deprecate.pending(version).map do |entry|
+        GemKit::Deprecate.pending(version).map do |entry|
           "#{entry.removed_in.to_s.ljust(8)} #{entry}#{entry.declared_at ? "\n#{" " * 9}#{entry.declared_at}" : ""}"
         end
       end
@@ -32,7 +32,7 @@ module GemKit
       # way past, not worth blocking on.
       def upcoming_deprecations(version)
         project.load!
-        Deprecate.upcoming(version)
+        GemKit::Deprecate.upcoming(version)
       end
 
       # Changelog format, plus "is there an entry for this version?" when one
@@ -96,12 +96,12 @@ describe "gem_kit/release/gate" do
 
   # Run a block with the deprecation registry isolated.
   isolated = lambda do |&block|
-    saved = GemKit::Release::Deprecate.registry.dup
-    GemKit::Release::Deprecate.registry.clear
+    saved = GemKit::Deprecate.registry.dup
+    GemKit::Deprecate.registry.clear
     begin
       block.call
     ensure
-      GemKit::Release::Deprecate.registry.replace(saved)
+      GemKit::Deprecate.registry.replace(saved)
     end
   end
 
@@ -134,7 +134,7 @@ describe "gem_kit/release/gate" do
       File.write(path, clean_changelog)
 
       isolated.call do
-        GemKit::Release::Deprecate.register(name: "Old", replacement: "New", removed_in: "1.0")
+        GemKit::Deprecate.register(name: "Old", replacement: "New", removed_in: "1.0")
         gate = GemKit::Release::Gate.new(stub_project.call(path))
 
         gate.release_problems("1.0.0").first.should.match(/deprecation due in 1\.0\.0: .*Old -> New/)
@@ -146,7 +146,7 @@ describe "gem_kit/release/gate" do
   it "does not block a bump on a deadline that has not arrived" do
     Dir.mktmpdir do |dir|
       isolated.call do
-        GemKit::Release::Deprecate.register(name: "Old", replacement: "New", removed_in: "2.0")
+        GemKit::Deprecate.register(name: "Old", replacement: "New", removed_in: "2.0")
         gate = GemKit::Release::Gate.new(stub_project.call(File.join(dir, "CHANGELOG.md")))
 
         gate.bump_problems("1.1.0").should == []

data/lib/gem_kit/release/generators/setup.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "thor"
+require "thor/group"
+
+require_relative "../commands/command"
+
+module GemKit
+  module Release
+    module Generators
+      # `gem kit setup` — a Thor generator, which is what Rails' own generators
+      # are. Using one rather than hand-rolled File.write buys the whole
+      # conflict protocol for free: `create`/`identical`/`conflict` status
+      # lines, a prompt offering diff/overwrite/skip when a file exists and
+      # differs, and --force / --skip / --pretend to answer that prompt ahead
+      # of time.
+      #
+      # It writes the two documents that describe this toolchain, rendered for
+      # the project's own name and versions. They are copies rather than links
+      # because a policy nobody can read in their own repo is a policy nobody
+      # follows, and because the examples are worth more with real numbers in
+      # them.
+      class Setup < Thor::Group
+        include Thor::Actions
+
+        # --force, --skip, --pretend and --quiet: Thor::Actions implements the
+        # behaviour but leaves declaring the switches to the generator.
+        add_runtime_options!
+
+        class_option :gem, type: :string,
+                           desc: "Which gem, in a repository holding more than one gemspec"
+
+        def self.source_root
+          File.expand_path("../templates", __dir__)
+        end
+
+        # Written into the project, not the working directory: `gem kit setup`
+        # run from a subdirectory still belongs to the gem.
+        def self.banner = "gem kit setup"
+
+        # The policy is the repository's — one deprecation policy governs every
+        # gem in it — so DEPRECATIONS.md is written once, whichever gem you
+        # named.
+        def deprecations_document
+          template("DEPRECATIONS.md.erb", File.join(project.root, "DEPRECATIONS.md"))
+        end
+
+        # The process is the gem's: every command in it names a version and a
+        # changelog belonging to one gem. So a repository with two gems gets
+        # RELEASE-<gem>.md apiece, matching the changelogs.
+        def release_document
+          template("RELEASE.md.erb", File.join(project.root, release_document_name))
+        end
+
+        def where_to_link_them
+          say ""
+          say "Link them from your README and AGENTS.md so they are found."
+        end
+
+        # Everything below is machinery, not a step. Thor runs every public
+        # method of a Thor::Group in order, so helpers have to say so.
+        no_commands do
+          # Every command in a multi-gem repository needs to say which gem it
+          # means, so the examples show it.
+          # Pads a command so the trailing comments line up whatever the gem
+          # is called.
+          def step(command) = command.ljust(step_width)
+
+          def step_width
+            @step_width ||= [30, "gem kit changelog#{gem_flag} <VERSION>".length + 2].max
+          end
+
+          def multi_gem  = project.multi_gem?
+          def tag_prefix = project.tag_prefix
+
+          # DEPRECATIONS.md is written once for the repository, so everything
+          # it says has to hold for every gem in it — no version numbers, and
+          # no link to one gem's changelog.
+          def deadline_rule
+            if multi_gem
+              "The usual deadline is the next major of the gem the name lives in."
+            else
+              "The current version is #{version}, so the usual deadline is #{next_major}."
+            end
+          end
+
+          def changelog_reference
+            multi_gem ? "that gem's changelog" : "`#{changelog}`"
+          end
+
+          def release_document_link
+            multi_gem ? "The RELEASE-<gem>.md beside it" : "[RELEASE.md](RELEASE.md)"
+          end
+
+          def gem_flag
+            project.multi_gem? ? " --gem #{project.name}" : ""
+          end
+
+          def release_document_name
+            project.multi_gem? ? "RELEASE-#{project.name}.md" : "RELEASE.md"
+          end
+
+          # The values the templates render against. Kept small and obvious — a
+          # template needing more than this is documenting the tool, not the
+          # project.
+          # DEPRECATIONS.md is the repository's, so what it is *about* must not
+          # depend on which gem you named — otherwise running setup for the
+          # second gem rewrites the first gem's document.
+          def subject
+            project.multi_gem? ? File.basename(project.root) : project.name
+          end
+
+          def name       = project.name
+          def version    = project.version.to_s
+          def next_major = project.next_major_version
+          def changelog  = File.basename(project.changelog_path)
+          def test       = project.test_command
+          def today      = Time.now.strftime("%Y-%m-%d")
+
+          def version_file
+            project.version_file.sub("#{project.root}/", "")
+          end
+
+          def project
+            @project ||= Project.detect(Dir.pwd, name: options[:gem])
+          rescue Project::NotFound, Project::Ambiguous => error
+            raise Failure, error.message
+          end
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/generators/setup" do
+  require_relative "../../../../spec/support/gem_kit_release_spec"
+  extend GemKitReleaseSpec
+
+  it "writes both documents into the project root" do
+    with_gem do |dir|
+      status, out, _err = invoke(["setup"], dir)
+
+      status.should == 0
+      out.should.match(/create.*DEPRECATIONS\.md/)
+      out.should.match(/create.*RELEASE\.md/)
+      File.exist?(File.join(dir, "DEPRECATIONS.md")).should.be.true
+      File.exist?(File.join(dir, "RELEASE.md")).should.be.true
+    end
+  end
+
+  it "renders them for this project's name and versions" do
+    with_gem(version: "4.1.0") do |dir|
+      invoke(["setup"], dir)
+
+      deprecations = File.read(File.join(dir, "DEPRECATIONS.md"))
+      deprecations.should.match(/A deprecation in demo is a \*\*dated promise\*\*/)
+      deprecations.should.match(/4\.1\.0, so the usual deadline is 5\.0/)
+      deprecations.should.not.match(/<%=/)
+
+      release = File.read(File.join(dir, "RELEASE.md"))
+      release.should.match(/Releasing demo/)
+      release.should.not.match(/<%=/)
+    end
+  end
+
+  # Thor::Actions reports an unchanged file as `identical` rather than
+  # rewriting it, which is the generator behaviour we switched to Thor for.
+  it "reports an unchanged document as identical rather than rewriting it" do
+    with_gem do |dir|
+      invoke(["setup"], dir)
+      before = File.mtime(File.join(dir, "RELEASE.md"))
+
+      _status, out, _err = invoke(["setup"], dir)
+
+      out.should.match(/identical.*RELEASE\.md/)
+      File.mtime(File.join(dir, "RELEASE.md")).should == before
+    end
+  end
+
+  it "--force overwrites a document that differs" do
+    with_gem do |dir|
+      File.write(File.join(dir, "RELEASE.md"), "mine\n")
+
+      status, out, _err = invoke(["setup", "--force"], dir)
+
+      status.should == 0
+      out.should.match(/force.*RELEASE\.md/)
+      File.read(File.join(dir, "RELEASE.md")).should.not == "mine\n"
+    end
+  end
+
+  it "--skip leaves a document that differs alone" do
+    with_gem do |dir|
+      File.write(File.join(dir, "RELEASE.md"), "mine\n")
+
+      invoke(["setup", "--skip"], dir).first.should == 0
+      File.read(File.join(dir, "RELEASE.md")).should == "mine\n"
+    end
+  end
+
+  it "--pretend writes nothing" do
+    with_gem do |dir|
+      invoke(["setup", "--pretend"], dir).first.should == 0
+      File.exist?(File.join(dir, "RELEASE.md")).should.be.false
+    end
+  end
+
+  it "is reachable by its alias" do
+    with_gem do |dir|
+      invoke(["init"], dir).first.should == 0
+      File.exist?(File.join(dir, "RELEASE.md")).should.be.true
+    end
+  end
+
+  # In a repository with several gems the process document is per-gem, but the
+  # policy is the repository's — so running setup for the second gem must not
+  # rewrite what the first one wrote.
+  it "writes a release document per gem and one policy for the repository" do
+    with_gem(second_gem: true) do |dir|
+      _status, first, _err  = invoke(["setup", "--gem", "demo"], dir)
+      _status, second, _err = invoke(["setup", "--gem", "other"], dir)
+
+      first.should.match(/create.*DEPRECATIONS\.md/)
+      first.should.match(/create.*RELEASE-demo\.md/)
+
+      second.should.match(/identical.*DEPRECATIONS\.md/)
+      second.should.match(/create.*RELEASE-other\.md/)
+
+      File.exist?(File.join(dir, "RELEASE.md")).should.be.false
+    end
+  end
+
+  it "spells the commands with --gem when the repository holds several" do
+    with_gem(second_gem: true) do |dir|
+      invoke(["setup", "--gem", "demo"], dir)
+
+      release = File.read(File.join(dir, "RELEASE-demo.md"))
+      release.should.match(/gem kit bump --gem demo/)
+      release.should.match(/CHANGELOG-demo\.md/)
+      release.should.match(/demo-v1\.2\.3/)
+    end
+  end
+
+  it "reports a directory with no gemspec" do
+    Dir.mktmpdir do |dir|
+      invoke(["setup"], dir).first.should == 1
+    end
+  end
+end

data/lib/gem_kit/release/project.rb

@@ -25,15 +25,37 @@ module GemKit
     class Project
       class NotFound < StandardError; end
 
+      # More than one gemspec and nothing to choose between them. A monorepo
+      # has to say which gem it means.
+      class Ambiguous < StandardError; end
+
       # Overridable settings. Each is nil until set, and nil means "infer".
       Config = Struct.new(:changelog, :version_file, :require_path, :test_command,
                           :changelog_writer, keyword_init: true)
 
-      def self.detect(dir = Dir.pwd, config: GemKit::Release.config)
-        gemspec = Dir[File.join(dir, "*.gemspec")].sort.first
-        raise NotFound, "no .gemspec in #{dir}" if gemspec.nil?
+      # `name` picks one gem out of a repository that holds several — matched
+      # against the gemspec's filename, so `--gem gem_kit` finds
+      # gem_kit.gemspec and not gem_kit-release.gemspec.
+      def self.detect(dir = Dir.pwd, name: nil, config: GemKit::Release.config)
+        gemspecs = Dir[File.join(dir, "*.gemspec")].sort
+        raise NotFound, "no .gemspec in #{dir}" if gemspecs.empty?
+
+        if name
+          match = gemspecs.find { |path| File.basename(path, ".gemspec") == name }
+          raise NotFound, "no #{name}.gemspec in #{dir}" if match.nil?
+
+          return new(match, config: config)
+        end
+
+        # Silently picking the first would mean bumping the wrong gem's version
+        # and only finding out on release.
+        if gemspecs.size > 1
+          names = gemspecs.map { |path| File.basename(path, ".gemspec") }
+          raise Ambiguous, "#{gemspecs.size} gemspecs in #{dir} (#{names.join(", ")}); " \
+                           "name one with --gem"
+        end
 
-        new(gemspec, config: config)
+        new(gemspecs.first, config: config)
       end
 
       attr_reader :root, :gemspec_path, :config
@@ -55,13 +77,38 @@ module GemKit
 
       def version = Gem::Version.new(spec.version.to_s)
 
-      # The next major version — the default deadline for a deprecation.
+      # The next major version — the usual deadline for a deprecation. Written
+      # "5.0" rather than "5": it reads as a version in prose and in a
+      # declaration, and Gem::Version treats the two as equal anyway.
       def next_major_version
-        Gem::Version.new(version.segments.first.to_s).bump.to_s
+        "#{version.segments.first.to_i + 1}.0"
       end
 
+      # Every gemspec beside this one, this one included. A repository with
+      # more than one releases each gem on its own schedule, and several things
+      # below have to know that.
+      def siblings
+        @siblings ||= Dir[File.join(root, "*.gemspec")].size
+      end
+
+      def multi_gem? = siblings > 1
+
+      # One changelog per gem. A shared file cannot work: the release gate asks
+      # whether the version being cut is the *topmost* released section, and
+      # two gems interleaved in one file means the older one never is — so the
+      # second gem could never be released.
       def changelog_path
-        File.expand_path(config.changelog || "CHANGELOG.md", root)
+        File.expand_path(config.changelog || default_changelog, root)
+      end
+
+      def default_changelog
+        multi_gem? ? "CHANGELOG-#{name}.md" : "CHANGELOG.md"
+      end
+
+      # `v1.2.3` says which version but not which gem, which is fine until a
+      # repository holds two of them at the same version.
+      def tag_prefix
+        multi_gem? ? "#{name}-v" : "v"
       end
 
       # lib/gem_kit/release/version.rb for "gem_kit-release", lib/brute/version.rb
@@ -158,13 +205,50 @@ describe "gem_kit/release/project" do
 
   it "defaults the changelog to CHANGELOG.md in the project root" do
     with_project.call do |dir|
-      GemKit::Release::Project.detect(dir).changelog_path.should == File.join(dir, "CHANGELOG.md")
+      project = GemKit::Release::Project.detect(dir)
+      project.multi_gem?.should.be.false
+      project.changelog_path.should == File.join(dir, "CHANGELOG.md")
+      project.tag_prefix.should == "v"
+    end
+  end
+
+  # One changelog and one tag namespace per gem, because a repository with two
+  # gems releases them separately.
+  it "gives each gem its own changelog and tag prefix when there are several" do
+    with_project.call(name: "demo") do |dir|
+      File.write(File.join(dir, "other.gemspec"), <<~RUBY)
+        Gem::Specification.new do |spec|
+          spec.name = "other"
+          spec.version = "9.9.9"
+          spec.authors = ["x"]
+          spec.summary = "x"
+          spec.files = []
+        end
+      RUBY
+
+      project = GemKit::Release::Project.detect(dir, name: "demo")
+      project.multi_gem?.should.be.true
+      project.changelog_path.should == File.join(dir, "CHANGELOG-demo.md")
+      project.tag_prefix.should == "demo-v"
+
+      GemKit::Release::Project.detect(dir, name: "other").changelog_path
+        .should == File.join(dir, "CHANGELOG-other.md")
+    end
+  end
+
+  it "an explicit changelog still overrides, in either kind of repository" do
+    with_project.call(name: "demo") do |dir|
+      File.write(File.join(dir, "other.gemspec"), "Gem::Specification.new { |s| s.name = \"other\" }")
+
+      config = GemKit::Release::Project::Config.new(changelog: "HISTORY.md")
+      GemKit::Release::Project.detect(dir, name: "demo", config: config).changelog_path
+        .should == File.join(dir, "HISTORY.md")
     end
   end
 
   it "bumps to the next major for the default deprecation deadline" do
     with_project.call(version: "4.1.0") do |dir|
-      GemKit::Release::Project.detect(dir).next_major_version.should == "5"
+      GemKit::Release::Project.detect(dir).next_major_version.should == "5.0"
     end
   end
 
@@ -177,6 +261,39 @@ describe "gem_kit/release/project" do
     end
   end
 
+  it "picks one gem out of a repository holding several" do
+    with_project.call(name: "demo") do |dir|
+      File.write(File.join(dir, "other.gemspec"), <<~RUBY)
+        Gem::Specification.new do |spec|
+          spec.name = "other"
+          spec.version = "9.9.9"
+          spec.authors = ["x"]
+          spec.summary = "x"
+          spec.files = []
+        end
+      RUBY
+
+      GemKit::Release::Project.detect(dir, name: "demo").name.should == "demo"
+      GemKit::Release::Project.detect(dir, name: "other").version.should == Gem::Version.new("9.9.9")
+    end
+  end
+
+  it "refuses to guess between several gemspecs" do
+    with_project.call(name: "demo") do |dir|
+      File.write(File.join(dir, "other.gemspec"), "Gem::Specification.new { |s| s.name = \"other\" }")
+
+      lambda { GemKit::Release::Project.detect(dir) }
+        .should.raise(GemKit::Release::Project::Ambiguous)
+    end
+  end
+
+  it "reports a named gem that is not here" do
+    with_project.call(name: "demo") do |dir|
+      lambda { GemKit::Release::Project.detect(dir, name: "nope") }
+        .should.raise(GemKit::Release::Project::NotFound)
+    end
+  end
+
   it "takes overrides from the config" do
     with_project.call do |dir|
       config = GemKit::Release::Project::Config.new(changelog: "HISTORY.md", test_command: "rake")

data/lib/gem_kit/release/templates/DEPRECATIONS.md.erb

@@ -1,19 +1,18 @@
 # Deprecations
 
-A deprecation in <%= name %> is a **dated promise**: it names the replacement
+A deprecation in <%= subject %> is a **dated promise**: it names the replacement
 *and* the version the old name stops existing in. That promise is
 machine-readable — every declaration registers itself, and the release tooling
 refuses to ship a version that breaks one.
 
-The mechanism is [`GemKit::Release::Deprecate`](https://rubygems.org/gems/gem_kit-release),
+The mechanism is [`GemKit::Deprecate`](https://rubygems.org/gems/gem_kit),
 built on [`Gem::Deprecate`](https://docs.ruby-lang.org/en/master/Gem/Deprecate.html).
 
 ## The rules
 
 1. **Never delete a public name outright.** Leave it working, deprecated, until
    its deadline.
-2. **Every deprecation names a removal version.** The current version is
-   <%= version %>, so the usual deadline is <%= next_major %>.
+2. **Every deprecation names a removal version.** <%= deadline_rule %>
 3. **Removals happen in major versions only.** A minor or patch release never
    takes a name away.
 4. **The deadline is enforced, not remembered.** `gem kit bump` and `gem kit release`
@@ -25,7 +24,7 @@ built on [`Gem::Deprecate`](https://docs.ruby-lang.org/en/master/Gem/Deprecate.h
 
 ```ruby
 class Session
-  extend GemKit::Release::Deprecate
+  extend GemKit::Deprecate
 
   def new_reset
     # ...
@@ -56,7 +55,7 @@ against the class, not its singleton:
 
 ```ruby
 class << self
-  extend GemKit::Release::Deprecate
+  extend GemKit::Deprecate
   deprecate :some_class_method, "Other.method", "<%= next_major %>"
 end
 ```
@@ -69,7 +68,7 @@ its body:
 ```ruby
 module Old
   class Thing < New::Thing
-    extend GemKit::Release::Deprecate
+    extend GemKit::Deprecate
     superseded_by "New::Thing", "<%= next_major %>"
   end
 end
@@ -98,15 +97,15 @@ Pass a version to ask "what comes due here?" — it exits non-zero if anything
 does, which is what makes it usable as a gate in CI:
 
 ```sh
-gem kit deprecations <%= next_major %>.0.0
+gem kit deprecations <%= next_major %>.0
 ```
 
 Programmatically, the same data:
 
 ```ruby
-GemKit::Release::Deprecate.registry                  # every declaration
-GemKit::Release::Deprecate.pending("<%= next_major %>.0.0")   # deadlines that have arrived
-GemKit::Release::Deprecate.upcoming("<%= next_major %>.0.0")  # still in their grace period
+GemKit::Deprecate.registry                  # every declaration
+GemKit::Deprecate.pending("<%= next_major %>.0")   # deadlines that have arrived
+GemKit::Deprecate.upcoming("<%= next_major %>.0")  # still in their grace period
 ```
 
 Each entry carries `name`, `replacement`, `removed_in` and `declared_at`.
@@ -118,7 +117,7 @@ code is actually gone:
 
 ```
 $ gem kit bump major
-ERROR:  Refusing to bump <%= version %> -> <%= next_major %>.0.0:
+ERROR:  Refusing to bump <%= version %> -> <%= next_major %>.0:
 
   <%= next_major %>      Session#old_reset -> Session#new_reset
            lib/session.rb:19
@@ -128,11 +127,11 @@ ERROR:  Refusing to bump <%= version %> -> <%= next_major %>.0.0:
 
 So the order of work is:
 
-1. `gem kit deprecations <%= next_major %>.0.0` — read the list.
+1. `gem kit deprecations <%= next_major %>.0` — read the list.
 2. Delete each deprecated name and its specs. For a constant shim, that means
    deleting the whole file.
 3. Update anything in `examples/` and the docs still using the old name.
-4. Record the removals in `<%= changelog %>` under `### Removed`.
+4. Record the removals in <%= changelog_reference %> under `### Removed`.
 5. `gem kit bump major` — now it goes through.
 
 `--force` exists for the case where you have decided to extend a grace period,
@@ -156,18 +155,18 @@ through:
 
 ```ruby
 captured = []
-original = GemKit::Release::Deprecate.method(:warn)
-GemKit::Release::Deprecate.define_singleton_method(:warn) { |message| captured << message }
+original = GemKit::Deprecate.method(:warn)
+GemKit::Deprecate.define_singleton_method(:warn) { |message| captured << message }
 begin
   legacy.old_reset
 ensure
-  GemKit::Release::Deprecate.define_singleton_method(:warn, original)
+  GemKit::Deprecate.define_singleton_method(:warn, original)
 end
 ```
 
 ## See also
 
-- [RELEASE.md](RELEASE.md) — where the deprecation gates sit in the release
+- <%= release_document_link %> — where the deprecation gates sit in the release
   process.
-- [<%= changelog %>](<%= changelog %>) — the `### Deprecated` and `### Removed`
-  sections are the user-facing half of all this.
+- The changelog — its `### Deprecated` and `### Removed` sections are the
+  user-facing half of all this.