gem_kit-release 0.1.0

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

@@ -0,0 +1,173 @@
+# Deprecations
+
+A deprecation in <%= name %> 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),
+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 %>.
+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`
+   both refuse to move to a version that has a deprecation coming due.
+5. **Deprecating something is a changelog entry** — under `### Deprecated`,
+   naming the replacement and the removal version.
+
+## Deprecating a method
+
+```ruby
+class Session
+  extend GemKit::Release::Deprecate
+
+  def new_reset
+    # ...
+  end
+
+  def old_reset = new_reset
+
+  deprecate :old_reset, "Session#new_reset", "<%= next_major %>"
+end
+```
+
+The old method keeps working and warns on every call, naming the caller:
+
+```
+NOTE: Session#old_reset is deprecated; use Session#new_reset instead.
+It will be removed in <%= next_major %>
+Session#old_reset called from app.rb:12.
+```
+
+Use `:none` as the replacement when there genuinely isn't one:
+
+```ruby
+deprecate :old_reset, :none, "<%= next_major %>"
+```
+
+For a class method, follow the `Gem::Deprecate` idiom — the registry records it
+against the class, not its singleton:
+
+```ruby
+class << self
+  extend GemKit::Release::Deprecate
+  deprecate :some_class_method, "Other.method", "<%= next_major %>"
+end
+```
+
+## Deprecating a renamed or moved constant
+
+Keep the old constant as a subclass of the new one and declare the rename in
+its body:
+
+```ruby
+module Old
+  class Thing < New::Thing
+    extend GemKit::Release::Deprecate
+    superseded_by "New::Thing", "<%= next_major %>"
+  end
+end
+```
+
+Old code keeps running unchanged; instantiating the old name warns and points at
+the new one. The whole shim is those four lines — the implementation lives in
+one place.
+
+It is `superseded_by` rather than `deprecate_constant` because `Module` already
+has a method by that name, and shadowing it would break callers who use it.
+
+## Finding what is outstanding
+
+```sh
+gem kit deprecations
+```
+
+```
+1 outstanding deprecation(s) (current version <%= version %>):
+  <%= next_major %>      Session#old_reset -> Session#new_reset
+           lib/session.rb:19
+```
+
+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
+```
+
+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
+```
+
+Each entry carries `name`, `replacement`, `removed_in` and `declared_at`.
+
+## Paying the debt
+
+When a major version comes around, the bump is blocked until the deprecated
+code is actually gone:
+
+```
+$ gem kit bump major
+ERROR:  Refusing to bump <%= version %> -> <%= next_major %>.0.0:
+
+  <%= next_major %>      Session#old_reset -> Session#new_reset
+           lib/session.rb:19
+
+  Remove them, then bump. Override with --force.
+```
+
+So the order of work is:
+
+1. `gem kit deprecations <%= next_major %>.0.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`.
+5. `gem kit bump major` — now it goes through.
+
+`--force` exists for the case where you have decided to extend a grace period,
+and it prints what it is overriding. It is not the normal path: extending a
+deadline properly means editing the declaration's version, which keeps the
+registry honest.
+
+## Testing deprecated code
+
+`Gem::Deprecate.skip_during` silences these warnings too, so a spec can
+exercise the old path without noise:
+
+```ruby
+Gem::Deprecate.skip_during do
+  legacy.old_reset
+end
+```
+
+To assert *that* something warns, stub the single funnel every warning goes
+through:
+
+```ruby
+captured = []
+original = GemKit::Release::Deprecate.method(:warn)
+GemKit::Release::Deprecate.define_singleton_method(:warn) { |message| captured << message }
+begin
+  legacy.old_reset
+ensure
+  GemKit::Release::Deprecate.define_singleton_method(:warn, original)
+end
+```
+
+## See also
+
+- [RELEASE.md](RELEASE.md) — where the deprecation gates sit in the release
+  process.
+- [<%= changelog %>](<%= changelog %>) — the `### Deprecated` and `### Removed`
+  sections are the user-facing half of all this.

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

@@ -0,0 +1,159 @@
+# Releasing <%= name %>
+
+The whole process, in order:
+
+```sh
+<%= test.ljust(30) %># 1. green suite
+gem kit bump minor            # 2. bump  (prints: now run gem kit changelog --write)
+gem kit changelog --write     # 3. write the entry
+gem kit changelog <VERSION>   # 4. check it
+git commit -am "Release ..."  # 5. commit the bump + changelog
+gem kit release               # 6. build and push
+gem kit tag --push            # 7. tag it
+```
+
+Steps 2 and 6 are gates: they refuse to proceed when something is missing.
+Everything below is what they check and why.
+
+## Versioning
+
+<%= name %> is [semver](https://semver.org/). The version lives in one place —
+`<%= version_file %>` — and is only ever changed by `gem kit bump`.
+
+| Segment | When | What it may contain |
+| --- | --- | --- |
+| **major** | A public name disappears or changes meaning | Removals of deprecated names, breaking signature changes |
+| **minor** | New public surface, backwards compatible | New classes and methods; new deprecations |
+| **patch** | Nothing new, nothing gone | Bug fixes, docs, internals |
+
+Two rules follow from this, and both are enforced in code:
+
+- **Removals only ever land in a major version.** A name promised to disappear
+  in <%= next_major %> disappears in <%= next_major %>.0.0, not in a patch.
+- **Deprecating is a minor.** Adding a deprecation puts no obligation on the
+  user *yet*, so it does not need a major — but it starts the clock. See
+  [DEPRECATIONS.md](DEPRECATIONS.md).
+
+## 1. Green suite
+
+```sh
+<%= test %>
+```
+
+A red suite is not a release candidate; nothing downstream checks this for you.
+
+## 2. Bump
+
+```sh
+gem kit bump <major|minor|patch>
+```
+
+Rewrites `<%= version_file %>` — by rendering its `.erb` template if there is
+one, otherwise by substituting the version literal in place — and prints the
+transition:
+
+```
+<%= version %> -> ...
+
+now run: gem kit changelog --write
+```
+
+**It refuses to bump onto a deprecation deadline.** If any registered
+deprecation is due at the new version, it lists them with their source lines
+and fails. Remove the deprecated code first — that is the point of the promise.
+`--force` overrides and says what it overrode. Deprecations *not* yet due are
+reported for information, not blocked on.
+
+## 3. Changelog
+
+```sh
+gem kit changelog --write
+```
+
+Hands the entry to the AI CLI named by `config.changelog_writer` (default:
+`claude`), with a prompt describing the format and this project's conventions.
+It reads the commits since the last tag and edits `<%= changelog %>` only.
+
+Review what it writes. It is a first draft with the commits in front of it, not
+an oracle — it cannot know which of two changes mattered to users.
+
+The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/):
+
+```md
+## [Unreleased]
+
+## [<%= version %>] - <%= today %>
+
+### Added
+
+- Something users can now do.
+
+### Deprecated
+
+- `Old::Name` — use `New::Name` instead. Removed in <%= next_major %>.
+```
+
+Entries go under `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed` or
+`Security` — those six and no others. `[Unreleased]` stays at the top, emptied
+of anything that shipped.
+
+## 4. Lint the changelog
+
+```sh
+gem kit changelog              # format only
+gem kit changelog <%= version %>       # format, plus "is this version ready?"
+```
+
+Checks the title, that every heading is `## [Unreleased]` or
+`## [1.2.3] - YYYY-MM-DD`, that versions are valid, dated, unique and ordered
+newest-first, that `###` sections are one of the six types and none are empty —
+and, given a version, that it has a non-empty section at the top of the released
+list. Every problem is reported as `<%= changelog %>:<line> <what>`.
+
+## 5. Commit
+
+The version bump, the lockfile and the changelog belong in one commit, before
+anything is pushed to RubyGems. A published gem whose changelog is still
+unwritten in git is the failure this process exists to prevent.
+
+## 6. Release
+
+```sh
+gem kit release           # or: gem kit release --dry-run, which is the CI check
+```
+
+Two gates, both before `gem build` runs:
+
+1. **Changelog** — this version needs its own non-empty, correctly formatted
+   section, sitting at the top of the released list.
+2. **Deprecations** — nothing promised to disappear in this version may still
+   be in the tree.
+
+Then `gem build` and `gem push`. Requires RubyGems push credentials.
+
+## 7. Tag
+
+```sh
+gem kit tag --push
+```
+
+Creates `v<%= version %>`, refusing if it already exists. The tag is also what
+the next `gem kit changelog --write` uses to find the commit range, so a missing
+one makes the following release's changelog harder to write.
+
+## When something goes wrong
+
+**Published a broken gem.** Don't delete it — `gem yank <%= name %> -v X.Y.Z` if
+it is genuinely dangerous, otherwise ship a patch. Yanking a version other
+people have already locked to breaks their builds.
+
+**Bumped but the release failed.** The bump is just a file. Fix the cause and
+re-run `gem kit release`; there is no need to un-bump.
+
+**Changelog written for the wrong version.** Edit the heading and re-run
+`gem kit changelog <version>`. Nothing downstream caches it.
+
+## See also
+
+- [DEPRECATIONS.md](DEPRECATIONS.md) — the deprecation policy the gates enforce.
+- [<%= changelog %>](<%= changelog %>).

data/lib/gem_kit/release/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GemKit
+  module Release
+    VERSION = "0.1.0"
+  end
+end

data/lib/gem_kit/release/version_file.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module GemKit
+  module Release
+    # Owns the one file that states the version, and the semver arithmetic for
+    # moving it. Two layouts are supported, and which one is in play is decided
+    # by whether an ERB template sits beside the file:
+    #
+    #   lib/x/version.rb.erb present -> render it with `version` in scope
+    #   otherwise                    -> substitute the version string in place
+    #
+    # The second is the common case and deliberately surgical: it rewrites the
+    # quoted version literal and touches nothing else in the file.
+    class VersionFile
+      class Error < StandardError; end
+
+      SEGMENTS = %w[major minor patch].freeze
+
+      # A quoted semver literal, e.g. VERSION = "4.1.0"
+      LITERAL = /(["'])(\d+\.\d+\.\d+(?:[-.][0-9A-Za-z.-]+)?)\1/
+
+      attr_reader :path, :template
+
+      def initialize(path, template: nil)
+        @path     = path
+        @template = template
+      end
+
+      # "4.1.0", :minor -> "4.2.0"
+      def self.bump(version, segment)
+        unless SEGMENTS.include?(segment.to_s)
+          raise Error, "unknown segment #{segment.inspect} (expected #{SEGMENTS.join(", ")})"
+        end
+
+        major, minor, patch = version.to_s.split(".").map(&:to_i)
+        case segment.to_s
+        when "major" then "#{major + 1}.0.0"
+        when "minor" then "#{major}.#{minor + 1}.0"
+        when "patch" then "#{major}.#{minor}.#{patch + 1}"
+        end
+      end
+
+      # The version currently written in the file.
+      def read
+        contents = File.read(path)
+        match = contents.match(LITERAL)
+        raise Error, "no version literal in #{path}" if match.nil?
+
+        match[2]
+      end
+
+      # Write `version` into the file. Returns the version written.
+      def write(version)
+        if template
+          File.write(path, ERB.new(File.read(template)).result(binding))
+        else
+          contents = File.read(path)
+          raise Error, "no version literal in #{path}" unless contents.match?(LITERAL)
+
+          File.write(path, contents.sub(LITERAL) { "#{$1}#{version}#{$1}" })
+        end
+
+        version
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/version_file" do
+  require "tmpdir"
+
+  VF = GemKit::Release::VersionFile unless defined?(VF)
+
+  with_file = lambda do |contents, &block|
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "version.rb")
+      File.write(path, contents)
+      block.call(path, dir)
+    end
+  end
+
+  it "bumps each segment, zeroing the ones below it" do
+    VF.bump("4.1.3", :major).should == "5.0.0"
+    VF.bump("4.1.3", :minor).should == "4.2.0"
+    VF.bump("4.1.3", :patch).should == "4.1.4"
+  end
+
+  it "rejects an unknown segment" do
+    lambda { VF.bump("1.0.0", :epoch) }.should.raise(GemKit::Release::VersionFile::Error)
+  end
+
+  it "reads the version literal out of the file" do
+    with_file.call(%(module Demo\n  VERSION = "1.2.3"\nend\n)) do |path|
+      VF.new(path).read.should == "1.2.3"
+    end
+  end
+
+  it "rewrites only the version literal, leaving the rest of the file alone" do
+    original = %(# frozen_string_literal: true\n\nmodule Demo\n  VERSION = "1.2.3" # keep\nend\n)
+    with_file.call(original) do |path|
+      VF.new(path).write("2.0.0").should == "2.0.0"
+      File.read(path).should == original.sub("1.2.3", "2.0.0")
+    end
+  end
+
+  it "handles single-quoted literals" do
+    with_file.call(%(VERSION = '0.9.0'\n)) do |path|
+      VF.new(path).write("0.10.0")
+      File.read(path).should == %(VERSION = '0.10.0'\n)
+    end
+  end
+
+  it "raises when there is no version literal to rewrite" do
+    with_file.call("module Demo\nend\n") do |path|
+      lambda { VF.new(path).read }.should.raise(GemKit::Release::VersionFile::Error)
+      lambda { VF.new(path).write("1.0.0") }.should.raise(GemKit::Release::VersionFile::Error)
+    end
+  end
+
+  it "renders an ERB template when the project generates its version file" do
+    with_file.call(%(VERSION = "0.0.0"\n)) do |path, dir|
+      template = File.join(dir, "version.rb.erb")
+      File.write(template, %(module Demo\n  VERSION = "<%= version %>"\nend\n))
+
+      VF.new(path, template: template).write("3.1.4")
+      File.read(path).should == %(module Demo\n  VERSION = "3.1.4"\nend\n)
+    end
+  end
+end

data/lib/gem_kit/release.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "release/version"
+require_relative "release/deprecate"
+require_relative "release/changelog"
+require_relative "release/project"
+require_relative "release/version_file"
+require_relative "release/gate"
+
+module GemKit
+  # Versioning, changelog and deprecation gates for Ruby gems.
+  #
+  # The premise: a deprecation is a dated promise — it names its replacement
+  # and the version the old name stops existing in — and a release is only
+  # honest if it keeps every promise that has come due and documents what
+  # changed. Both are checkable, so neither should depend on anyone
+  # remembering.
+  #
+  # In a Rakefile, which is the whole integration:
+  #
+  #   require "gem_kit/release/tasks"
+  #
+  # Everything else is inferred from the project's .gemspec. Override only
+  # what cannot be:
+  #
+  #   GemKit::Release.configure do |config|
+  #     config.changelog        = "HISTORY.md"
+  #     config.test_command     = "bin/test"
+  #     config.changelog_writer = "claude"
+  #   end
+  module Release
+    def self.config
+      @config ||= Project::Config.new
+    end
+
+    def self.configure
+      yield config
+      config
+    end
+
+    # The project the tooling is running in.
+    def self.project(dir = Dir.pwd)
+      Project.detect(dir)
+    end
+
+    def self.gate(dir = Dir.pwd)
+      Gate.new(project(dir))
+    end
+
+    # Reset configuration — for tests.
+    def self.reset!
+      @config = nil
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release" do
+  it "exposes a configurable, resettable config" do
+    begin
+      GemKit::Release.configure { |c| c.changelog = "HISTORY.md" }
+      GemKit::Release.config.changelog.should == "HISTORY.md"
+    ensure
+      GemKit::Release.reset!
+    end
+
+    GemKit::Release.config.changelog.should.be.nil
+  end
+
+  it "detects itself as a project" do
+    project = GemKit::Release.project(File.expand_path("../..", __dir__))
+    project.name.should == "gem_kit-release"
+    project.version.should == Gem::Version.new(GemKit::Release::VERSION)
+    project.require_path.should == "gem_kit/release"
+  end
+end

data/lib/rubygems/commands/kit_command.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "rubygems/command"
+
+module Gem
+  module Commands
+    # `gem kit <subcommand>` — the only command this gem registers.
+    #
+    # One registration rather than six keeps the toolchain under a name that is
+    # obviously ours, leaves `gem help commands` readable, and means nothing
+    # here can collide with a command RubyGems adds later.
+    #
+    # This class is a bridge and nothing else: it hands the argv to the dry-cli
+    # registry, which owns the parsing and the help pages, and turns the result
+    # into a RubyGems exit. handle_options is deliberately inert — parsing here
+    # would swallow flags meant for a subcommand.
+    class KitCommand < Gem::Command
+      def initialize
+        super("kit", "Versioning, changelog and deprecation gates for this gem")
+      end
+
+      def arguments
+        <<~TXT
+          setup         copy DEPRECATIONS.md and RELEASE.md into this project
+          bump          move the version, refusing to bump onto a deprecation deadline
+          changelog     lint CHANGELOG.md, or have an AI CLI write this version's entry
+          deprecations  list the deprecations this gem has not yet honoured
+          release       gate, build and push this gem
+          tag           tag the current version in git
+        TXT
+      end
+
+      def usage = "#{program_name} SUBCOMMAND [options]"
+
+      def defaults_str = "(lists the subcommands)"
+
+      def description
+        <<~TXT
+          A deprecation is a dated promise: it names its replacement and the version
+          the old name stops existing in. These commands keep those promises — `bump`
+          refuses to move onto a deadline, and `release` refuses to ship a version with
+          an unkept promise or no changelog entry of its own.
+
+          Everything is read from the .gemspec in the working directory, so there is
+          nothing to configure in the common case.
+
+          Run `gem kit SUBCOMMAND --help` for one subcommand's arguments, options and
+          examples.
+        TXT
+      end
+
+      # Inert on purpose: the dry-cli registry parses the argv, including the
+      # subcommand's own flags.
+      def handle_options(args)
+        @argv = args.dup
+      end
+
+      def execute
+        # require_relative, not require: this resolves whether or not the gem
+        # is installed, which keeps the command testable from the repo.
+        require_relative "../../gem_kit/release/cli"
+
+        terminate_interaction(GemKit::Release::CLI.run(@argv || []))
+      end
+    end
+  end
+end
+
+__END__
+
+describe "rubygems/commands/kit_command" do
+  require_relative "../../../spec/support/gem_kit_release_spec"
+  extend GemKitReleaseSpec
+
+  it "dispatches to a subcommand, passing its arguments through" do
+    with_gem do |dir|
+      status, out, _err = invoke(["bump", "minor"], dir)
+
+      status.should == 0
+      out.should.match(/1\.2\.3 -> 1\.3\.0/)
+      File.read(File.join(dir, "lib/demo/version.rb")).should.match(/"1\.3\.0"/)
+    end
+  end
+
+  it "passes flags through to the subcommand's own parser" do
+    with_gem do |dir|
+      status, out, _err = invoke(["bump", "major", "--force"], dir,
+                                 deprecations: [["Old", "New", "2.0"]])
+
+      status.should == 0
+      out.should.match(/--force given/)
+    end
+  end
+
+  it "propagates a subcommand's failure as a non-zero status" do
+    with_gem do |dir|
+      status, _out, err = invoke(["changelog", "9.9.9"], dir)
+      status.should == 1
+      err.should.match(/no section for 9\.9\.9/)
+    end
+  end
+
+  it "describes itself for `gem help kit`" do
+    command = Gem::Commands::KitCommand.new
+
+    command.command.should == "kit"
+    command.usage.should.match(/gem kit SUBCOMMAND/)
+    command.arguments.should.match(/deprecations/)
+    command.description.should.match(/dated promise/)
+  end
+end

data/lib/rubygems_plugin.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# RubyGems loads this file from every installed gem's lib/ on every `gem`
+# invocation, which is how `gem kit` becomes a real command. Keep it to the
+# require and the registration — anything heavier is a tax on `gem list`.
+
+require "rubygems/command_manager"
+
+require_relative "rubygems/commands/kit_command"
+
+Gem::CommandManager.instance.register_command :kit