kettle-dev 2.2.12 → 2.2.14

data/README.md

@@ -10,9 +10,9 @@
 
 `if ci_badges.map(&:color).all? { it == "green"}` 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.
 
-[![OpenCollective Backers][🖇osc-backers-i]][🖇osc-backers] [![OpenCollective Sponsors][🖇osc-sponsors-i]][🖇osc-sponsors] [![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Donate on PayPal][🖇paypal-img]][🖇paypal] [![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate at ko-fi.com][🖇kofi-img]][🖇kofi]
+[![OpenCollective Backers][🖇osc-backers-i]][🖇osc-backers] [![OpenCollective Sponsors][🖇osc-sponsors-i]][🖇osc-sponsors] [![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Donate on PayPal][🖇paypal-img]][🖇paypal] [![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate at ko-fi.com][🖇kofi-img]][🖇kofi]
 
-<details>
+<details markdown="1">
  <summary>👣 How will this project approach the September 2025 hostile takeover of RubyGems? 🚑️</summary>
 
 I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-takeover-of-rubygems-my-thoughts-5hlo).
@@ -22,7 +22,7 @@ I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-ta
 ## 🌻 Synopsis <a href="https://discord.gg/3qme4XHNKN"><img alt="Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0" src="https://logos.galtzo.com/assets/images/galtzo-floss/avatar-128px.svg" width="8%" align="right"/></a> <a href="https://ruby-toolbox.com"><img alt="ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5" src="https://logos.galtzo.com/assets/images/ruby-lang/avatar-128px.svg" width="8%" align="right"/></a>
 
 Kettle::Dev is the development, CI, changelog, and release harness used by
-kettle-rb gems. It installs rake tasks when loaded from a project's `Rakefile`,
+kettle-dev gems. It installs rake tasks when loaded from a project's `Rakefile`,
 and it ships command-line tools for changelog preparation, release automation,
 multi-forge git remotes, commit-message hooks, and Open Collective README
 updates.
@@ -42,14 +42,14 @@ require "kettle/dev"
 ```
 
 For RSpec projects, use the matching test harness from
-[kettle-test](https://github.com/kettle-rb/kettle-test):
+[kettle-test](https://github.com/kettle-dev/kettle-test):
 
 ```ruby
 require "kettle/test/rspec"
 ```
 
 Project setup and template refreshes are now owned by
-[kettle-jem](https://github.com/kettle-rb/kettle-jem), not kettle-dev:
+[kettle-jem](https://github.com/kettle-dev/kettle-jem), not kettle-dev:
 
 ```console
 gem install kettle-jem
@@ -77,7 +77,7 @@ bin/kettle-release
 - Rake task loading from `require "kettle/dev"`.
 - RuboCop Gradual, Reek, YARD, appraisal, local CI, benchmark, and coverage task wiring.
 - `kettle-changelog` for moving Unreleased changelog notes into a versioned release section with coverage and documentation stats.
-- `kettle-release` for the canonical kettle-rb release flow.
+- `kettle-release` for the canonical kettle-dev release flow.
 - `kettle-pre-release` for release readiness checks.
 - `kettle-dvcs` for normalizing GitHub, GitLab, Codeberg, and aggregate remotes.
 - `kettle-commit-msg` for shared commit-message hook behavior.
@@ -88,9 +88,9 @@ bin/kettle-release
 
 | Tokens to Remember | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace] |
 |-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Works with JRuby | [![JRuby 9.2 Compat][💎jruby-9.2i]][🚎jruby-9.2-wf] [![JRuby 9.3 Compat][💎jruby-9.3i]][🚎jruby-9.3-wf] <br/> [![JRuby 9.4 Compat][💎jruby-9.4i]][🚎jruby-9.4-wf] [![JRuby current Compat][💎jruby-c-i]][🚎10-j-wf] [![JRuby HEAD Compat][💎jruby-headi]][🚎3-hd-wf]|
-| Works with Truffle Ruby | [![Truffle Ruby 22.3 Compat][💎truby-22.3i]][🚎truby-22.3-wf] [![Truffle Ruby 23.0 Compat][💎truby-23.0i]][🚎truby-23.0-wf] [![Truffle Ruby 23.1 Compat][💎truby-23.1i]][🚎truby-23.1-wf] <br/> [![Truffle Ruby 24.2 Compat][💎truby-24.2i]][🚎truby-24.2-wf] [![Truffle Ruby 25.0 Compat][💎truby-25.0i]][🚎truby-25.0-wf] [![Truffle Ruby current Compat][💎truby-c-i]][🚎9-t-wf]|
-| Works with MRI Ruby 4 | [![Ruby 4.0 Compat][💎ruby-4.0i]][🚎11-c-wf] [![Ruby current Compat][💎ruby-c-i]][🚎11-c-wf] [![Ruby HEAD Compat][💎ruby-headi]][🚎3-hd-wf]|
+| Works with JRuby | [![JRuby 9.2 Compat][💎jruby-9.2i]][🚎jruby-9.2-wf] [![JRuby 9.3 Compat][💎jruby-9.3i]][🚎jruby-9.3-wf] <br/> [![JRuby 9.4 Compat][💎jruby-9.4i]][🚎jruby-9.4-wf] [![JRuby 10.0 Compat][💎jruby-10.0i]][🚎jruby-10.0-wf] [![JRuby current Compat][💎jruby-c-i]][🚎10-j-wf] [![JRuby HEAD Compat][💎jruby-headi]][🚎3-hd-wf]|
+| Works with Truffle Ruby | [![Truffle Ruby 22.3 Compat][💎truby-22.3i]][🚎truby-22.3-wf] [![Truffle Ruby 23.0 Compat][💎truby-23.0i]][🚎truby-23.0-wf] [![Truffle Ruby 23.1 Compat][💎truby-23.1i]][🚎truby-23.1-wf] <br/> [![Truffle Ruby 24.2 Compat][💎truby-24.2i]][🚎truby-24.2-wf] [![Truffle Ruby 25.0 Compat][💎truby-25.0i]][🚎truby-25.0-wf] [![Truffle Ruby 33.0 Compat][💎truby-33.0i]][🚎truby-33.0-wf] [![Truffle Ruby current Compat][💎truby-c-i]][🚎9-t-wf] [![Truffle Ruby HEAD Compat][💎truby-headi]][🚎3-hd-wf]|
+| Works with MRI Ruby 4 | [![Ruby current Compat][💎ruby-c-i]][🚎11-c-wf] [![Ruby HEAD Compat][💎ruby-headi]][🚎3-hd-wf]|
 | Works with MRI Ruby 3 | [![Ruby 3.0 Compat][💎ruby-3.0i]][🚎ruby-3.0-wf] [![Ruby 3.1 Compat][💎ruby-3.1i]][🚎ruby-3.1-wf] [![Ruby 3.2 Compat][💎ruby-3.2i]][🚎ruby-3.2-wf] [![Ruby 3.3 Compat][💎ruby-3.3i]][🚎ruby-3.3-wf] [![Ruby 3.4 Compat][💎ruby-3.4i]][🚎ruby-3.4-wf]|
 | Works with MRI Ruby 2 | [![Ruby 2.4 Compat][💎ruby-2.4i]][🚎ruby-2.4-wf] [![Ruby 2.5 Compat][💎ruby-2.5i]][🚎ruby-2.5-wf] [![Ruby 2.6 Compat][💎ruby-2.6i]][🚎ruby-2.6-wf] [![Ruby 2.7 Compat][💎ruby-2.7i]][🚎ruby-2.7-wf]|
 | Support & Community | [![Join Me on Daily.dev's RubyFriends][✉️ruby-friends-img]][✉️ruby-friends] [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork] [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor] |
@@ -109,9 +109,24 @@ This test floor is configured by `ruby.test_minimum` in `.kettle-jem.yml` and
 may be higher than the gem's runtime compatibility floor when legacy Rubies are
 not practical for the current toolchain.
 
-| 🚚 _Amazing_ test matrix was brought to you by | 🔎 appraisal2 🔎 and the color 💚 green 💚 |
-|------------------------------------------------|--------------------------------------------------------|
-| 👟 Check it out! | ✨ [github.com/appraisal-rb/appraisal2][💎appraisal2] ✨ |
+<a href="https://github.com/kettle-dev"><img alt="kettle-dev Logo by Aboling0, CC BY-SA 4.0" src="https://logos.galtzo.com/assets/images/kettle-dev/avatar-128px.svg" width="14%" align="right"/></a>
+
+The _amazing_ test matrix is powered by the kettle-dev stack.
+
+<details markdown="1">
+<summary>How kettle-dev manages complexity in tests</summary>
+
+| Gem | Source | Role | Daily download rank |
+|-----|--------|------|---------------------|
+| [appraisal2](https://bestgems.org/gems/appraisal2) | [GitHub](https://github.com/appraisal-rb/appraisal2) | multi-dependency Appraisal matrix generation | [![Daily download rank for appraisal2](https://img.shields.io/gem/rd/appraisal2.svg?style=flat-square)](https://bestgems.org/gems/appraisal2) |
+| [appraisal2-rubocop](https://bestgems.org/gems/appraisal2-rubocop) | [GitHub](https://github.com/appraisal-rb/appraisal2-rubocop) | RuboCop Appraisal generator integration | [![Daily download rank for appraisal2-rubocop](https://img.shields.io/gem/rd/appraisal2-rubocop.svg?style=flat-square)](https://bestgems.org/gems/appraisal2-rubocop) |
+| [kettle-jem](https://bestgems.org/gems/kettle-jem) | [GitHub](https://github.com/kettle-dev/kettle-jem) | Appraisals & CI workflow templates | [![Daily download rank for kettle-jem](https://img.shields.io/gem/rd/kettle-jem.svg?style=flat-square)](https://bestgems.org/gems/kettle-jem) |
+| [kettle-soup-cover](https://bestgems.org/gems/kettle-soup-cover) | [GitHub](https://github.com/kettle-dev/kettle-soup-cover) | SimpleCov coverage policy and reporting | [![Daily download rank for kettle-soup-cover](https://img.shields.io/gem/rd/kettle-soup-cover.svg?style=flat-square)](https://bestgems.org/gems/kettle-soup-cover) |
+| [kettle-test](https://bestgems.org/gems/kettle-test) | [GitHub](https://github.com/kettle-dev/kettle-test) | standard test runner and coverage harness | [![Daily download rank for kettle-test](https://img.shields.io/gem/rd/kettle-test.svg?style=flat-square)](https://bestgems.org/gems/kettle-test) |
+| [rubocop-lts](https://bestgems.org/gems/rubocop-lts) | [GitHub](https://github.com/rubocop-lts/rubocop-lts) | Ruby-version-aware linting | [![Daily download rank for rubocop-lts](https://img.shields.io/gem/rd/rubocop-lts.svg?style=flat-square)](https://bestgems.org/gems/rubocop-lts) |
+| [turbo_tests2](https://bestgems.org/gems/turbo_tests2) | [GitHub](https://github.com/galtzo-floss/turbo_tests2) | parallel test execution | [![Daily download rank for turbo_tests2](https://img.shields.io/gem/rd/turbo_tests2.svg?style=flat-square)](https://bestgems.org/gems/turbo_tests2) |
+
+</details>
 
 ### Federated DVCS
 
@@ -187,7 +202,7 @@ require "kettle/dev"
 
 ### RSpec
 
-This gem integrates tightly with [kettle-test](https://github.com/kettle-rb/kettle-test).
+This gem integrates tightly with [kettle-test](https://github.com/kettle-dev/kettle-test).
 
 ```ruby
 require "kettle/test/rspec"
@@ -375,7 +390,8 @@ What it does:
 
 - Script: `exe/kettle-release` (run as `kettle-release`)
 - Purpose: guided release helper that:
-    - Runs `kettle-pre-release` before the numbered release steps on full releases, aborting before release setup if any pre-release gate fails.
+    - Runs `kettle-pre-release` as step 0 on full releases, aborting before release setup if any pre-release gate fails.
+    - Skips pre-release checks for any `start_step` greater than `0`, so resumptions begin directly at the requested numbered step.
     - Runs sanity checks (`bin/setup`, `bin/rake`), confirms version/changelog, optionally updates Appraisals, regenerates docs via `bin/rake yard`, commits “🔖 Prepare release vX.Y.Z”.
     - Optionally runs your CI locally with `act` before any push:
         - Enable with env: `K_RELEASE_LOCAL_CI="true"` (run automatically) or `K_RELEASE_LOCAL_CI="ask"` (prompt \[Y/n\]).
@@ -385,7 +401,8 @@ What it does:
     - Exports `SOURCE_DATE_EPOCH`, builds (optionally signed), creates gem checksums, and runs `bundle exec rake release` (prompts for signing key + RubyGems MFA OTP as needed).
 - Options:
     - `start_step` map (skip directly to a phase):
-        1.  Verify Bundler \>= 2.7 (always runs; start at 1 to do everything)
+        0.  Run `kettle-pre-release` gates
+        1.  Verify Bundler \>= 2.7 (start at 1 to skip pre-release checks)
         2.  Detect version; RubyGems sanity check; confirm CHANGELOG/version; sync copyright years; update badges/headers
         3.  Run bin/setup
         4.  Run bin/rake (default task)
@@ -406,7 +423,8 @@ What it does:
         19. Push tags to remotes (final)
 - Examples:
     - After intermittent CI failure, restart from monitoring: `bundle exec kettle-release start_step=10`
-    - After fixing a failed pre-release gate, rerun from the top: `bundle exec kettle-release`
+    - After fixing a failed pre-release gate, rerun from step 0: `bundle exec kettle-release`
+    - After intentionally handling a failed pre-release gate, skip it and start numbered release steps: `bundle exec kettle-release start_step=1`
 - Tips:
     - The commit message helper `exe/kettle-commit-msg` prefers project-local `.git-hooks` (then falls back to `~/.git-hooks`).
     - The goalie file `commit-subjects-goalie.txt` controls when a footer is appended; customize `footer-template.erb.txt` as you like.
@@ -524,7 +542,7 @@ What it does:
     - Sponsors (Organizations): `<!-- <TAG>-ORGANIZATIONS:START --> … <!-- <TAG>-ORGANIZATIONS:END -->`
 - Handle resolution:
     1.  `OPENCOLLECTIVE_HANDLE` environment variable, if set
-    2.  `opencollective.yml` in the project root (e.g., `collective: "kettle-rb"` in this repo)
+    2.  `opencollective.yml` in the project root (e.g., `collective: "kettle-dev"` in this repo)
 - Usage:
     - `exe/kettle-readme-backers`
     - `OPENCOLLECTIVE_HANDLE=my-collective exe/kettle-readme-backers`
@@ -590,7 +608,7 @@ Made with [contributors-img][🖐contrib-rocks].
 
 Also see GitLab Contributors: [https://gitlab.com/kettle-dev/kettle-dev/-/graphs/main][🚎contributors-gl]
 
-<details>
+<details markdown="1">
  <summary>⭐️ Star History</summary>
 
 <a href="https://star-history.com/kettle-dev/kettle-dev&Date">
@@ -687,12 +705,8 @@ Thanks for RTFM. ☺️
 [🖇sponsor-img]: https://img.shields.io/badge/Sponsor_Me!-pboling.svg?style=social&logo=github
 [🖇sponsor-bottom-img]: https://img.shields.io/badge/Sponsor_Me!-pboling-blue?style=for-the-badge&logo=github
 [🖇sponsor]: https://github.com/sponsors/pboling
-[🖇polar-img]: https://img.shields.io/badge/polar-donate-a51611.svg?style=flat
-[🖇polar]: https://polar.sh/pboling
 [🖇kofi-img]: https://img.shields.io/badge/ko--fi-%E2%9C%93-a51611.svg?style=flat
 [🖇kofi]: https://ko-fi.com/pboling
-[🖇patreon-img]: https://img.shields.io/badge/patreon-donate-a51611.svg?style=flat
-[🖇patreon]: https://patreon.com/galtzo
 [🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-%E2%9C%93-a51611.svg?style=flat
 [🖇buyme-img]: https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20latte&emoji=&slug=pboling&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff
 [🖇buyme]: https://www.buymeacoffee.com/pboling
@@ -782,11 +796,13 @@ Thanks for RTFM. ☺️
 [🚎jruby-9.2-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/jruby-9.2.yml
 [🚎jruby-9.3-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/jruby-9.3.yml
 [🚎jruby-9.4-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/jruby-9.4.yml
+[🚎jruby-10.0-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/jruby-10.0.yml
 [🚎truby-22.3-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/truffleruby-22.3.yml
 [🚎truby-23.0-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/truffleruby-23.0.yml
 [🚎truby-23.1-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/truffleruby-23.1.yml
 [🚎truby-24.2-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/truffleruby-24.2.yml
 [🚎truby-25.0-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/truffleruby-25.0.yml
+[🚎truby-33.0-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/truffleruby-33.0.yml
 [🚎2-cov-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/coverage.yml
 [🚎2-cov-wfi]: https://github.com/kettle-dev/kettle-dev/actions/workflows/coverage.yml/badge.svg
 [🚎3-hd-wf]: https://github.com/kettle-dev/kettle-dev/actions/workflows/heads.yml
@@ -814,7 +830,6 @@ Thanks for RTFM. ☺️
 [💎ruby-3.2i]: https://img.shields.io/badge/Ruby-3.2-CC342D?style=for-the-badge&logo=ruby&logoColor=white
 [💎ruby-3.3i]: https://img.shields.io/badge/Ruby-3.3-CC342D?style=for-the-badge&logo=ruby&logoColor=white
 [💎ruby-3.4i]: https://img.shields.io/badge/Ruby-3.4-CC342D?style=for-the-badge&logo=ruby&logoColor=white
-[💎ruby-4.0i]: https://img.shields.io/badge/Ruby-4.0-CC342D?style=for-the-badge&logo=ruby&logoColor=white
 [💎ruby-c-i]: https://img.shields.io/badge/Ruby-current-CC342D?style=for-the-badge&logo=ruby&logoColor=green
 [💎ruby-headi]: https://img.shields.io/badge/Ruby-HEAD-CC342D?style=for-the-badge&logo=ruby&logoColor=blue
 [💎truby-22.3i]: https://img.shields.io/badge/Truffle_Ruby-22.3-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
@@ -822,10 +837,13 @@ Thanks for RTFM. ☺️
 [💎truby-23.1i]: https://img.shields.io/badge/Truffle_Ruby-23.1-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
 [💎truby-24.2i]: https://img.shields.io/badge/Truffle_Ruby-24.2-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
 [💎truby-25.0i]: https://img.shields.io/badge/Truffle_Ruby-25.0-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
+[💎truby-33.0i]: https://img.shields.io/badge/Truffle_Ruby-33.0-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
 [💎truby-c-i]: https://img.shields.io/badge/Truffle_Ruby-current-34BCB1?style=for-the-badge&logo=ruby&logoColor=green
+[💎truby-headi]: https://img.shields.io/badge/Truffle_Ruby-HEAD-34BCB1?style=for-the-badge&logo=ruby&logoColor=blue
 [💎jruby-9.2i]: https://img.shields.io/badge/JRuby-9.2-FBE742?style=for-the-badge&logo=ruby&logoColor=red
 [💎jruby-9.3i]: https://img.shields.io/badge/JRuby-9.3-FBE742?style=for-the-badge&logo=ruby&logoColor=red
 [💎jruby-9.4i]: https://img.shields.io/badge/JRuby-9.4-FBE742?style=for-the-badge&logo=ruby&logoColor=red
+[💎jruby-10.0i]: https://img.shields.io/badge/JRuby-10.0-FBE742?style=for-the-badge&logo=ruby&logoColor=red
 [💎jruby-c-i]: https://img.shields.io/badge/JRuby-current-FBE742?style=for-the-badge&logo=ruby&logoColor=green
 [💎jruby-headi]: https://img.shields.io/badge/JRuby-HEAD-FBE742?style=for-the-badge&logo=ruby&logoColor=blue
 [🤝gh-issues]: https://github.com/kettle-dev/kettle-dev/issues
@@ -854,7 +872,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.266-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.411-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-dev/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
@@ -882,7 +900,7 @@ Thanks for RTFM. ☺️
 | Package | kettle-dev |
 | Description | 🍲 Kettle::Dev is a meta tool from kettle-rb to streamline development and testing. Acts as a shim dependency, pulling in many other dependencies, to give you OOTB productivity with a RubyGem, or Ruby app project. Configures a complete set of Rake tasks, for all the libraries is brings in, so they arrive ready to go. Fund overlooked open source projects - bottom of stack, dev/test dependencies: floss-funding.dev |
 | Homepage | https://github.com/kettle-dev/kettle-dev |
-| Source | https://github.com/kettle-dev/kettle-dev/tree/v2.2.4 |
+| Source | https://github.com/kettle-dev/kettle-dev |
 | License | `AGPL-3.0-only` |
-| Funding | https://github.com/sponsors/pboling, https://issuehunt.io/u/pboling, https://ko-fi.com/pboling, https://liberapay.com/pboling/donate, https://opencollective.com/kettle-dev, https://opencollective.com/kettle-rb, https://patreon.com/galtzo, https://polar.sh/pboling, https://thanks.dev/u/gh/pboling, https://tidelift.com/funding/github/rubygems/kettle-dev, https://www.buymeacoffee.com/pboling |
+| Funding | https://github.com/sponsors/pboling, https://ko-fi.com/pboling, https://liberapay.com/pboling/donate, https://opencollective.com/kettle-dev, https://thanks.dev/u/gh/pboling, https://tidelift.com/funding/github/rubygems/kettle-dev, https://www.buymeacoffee.com/pboling |
 <!-- kettle-jem:metadata:end -->

data/exe/kettle-changelog

@@ -55,7 +55,7 @@ end
 begin
   if ARGV.include?("-h") || ARGV.include?("--help")
     puts <<~USAGE
-      Usage: kettle-changelog [--version VERSION] [--update-prep] [--pending-release] [--release-state] [--json] [--no-strict] [--no-coverage-threshold]
+      Usage: kettle-changelog [--version VERSION] [--update-prep] [--pending-release] [--release-state] [--add-unreleased-entry --section SECTION --entry TEXT] [--json] [--no-strict] [--no-coverage-threshold]
 
       Detects the current version from lib/**/version.rb, the latest live release, and
       the most recent CHANGELOG.md release section, then prompts to confirm the selected plan:
@@ -70,6 +70,9 @@ begin
         --pending-release         Query whether the changelog has release work pending; exits 0 for yes, 1 for no
         --release-state,
         --release-status          Print changelog release state, including latest published release and pending sources
+        --add-unreleased-entry    Add one entry to an existing section under ## [Unreleased]
+        --section SECTION         Unreleased section to receive the entry (Added, Changed, Deprecated, Removed, Fixed, Security)
+        --entry TEXT              Changelog entry text; "- " is added when omitted
         --json                    Print query output as JSON
         --no-strict               Allow missing coverage and yard data (warnings only, no errors)
         --no-coverage-threshold   Generate coverage without hard-failing below configured thresholds
@@ -128,11 +131,42 @@ begin
   update_prep = ARGV.delete("--update-prep")
   pending_release_query = ARGV.delete("--pending-release")
   release_state_query = ARGV.delete("--release-state") || ARGV.delete("--release-status")
+  add_unreleased_entry = ARGV.delete("--add-unreleased-entry") || ARGV.delete("--add-changelog-entry")
   json_output = ARGV.delete("--json")
   coverage_threshold_disabled = ARGV.include?("--no-coverage-threshold") || ARGV.include?("--no-coverage-thresholds")
   coverage_hard = !coverage_threshold_disabled && ENV.fetch("K_CHANGELOG_COVERAGE_HARD", "true").downcase != "false"
   version_override = extract_version_arg!(ARGV)
 
+  def extract_option_arg!(argv, name)
+    value = nil
+    if (idx = argv.index(name))
+      value = argv[idx + 1]
+      Kettle::Dev::ExitAdapter.abort("#{name} requires a value") if value.to_s.empty?
+      argv.slice!(idx, 2)
+    end
+    argv.delete_if do |arg|
+      if arg.start_with?("#{name}=")
+        value = arg.split("=", 2)[1]
+        true
+      else
+        false
+      end
+    end
+    value
+  end
+
+  if add_unreleased_entry
+    section = extract_option_arg!(ARGV, "--section")
+    entry = extract_option_arg!(ARGV, "--entry")
+    Kettle::Dev::ExitAdapter.abort("--section is required with --add-unreleased-entry") if section.to_s.empty?
+    Kettle::Dev::ExitAdapter.abort("--entry is required with --add-unreleased-entry") if entry.to_s.empty?
+
+    result = Kettle::Dev::ChangelogEntryAdder.new(section: section, entry: entry).run
+    message = (result == :changed) ? "CHANGELOG.md updated under Unreleased #{section}." : "CHANGELOG.md already contains that Unreleased #{section} entry."
+    puts(json_output ? JSON.pretty_generate({changed: result == :changed, section: section, entry: entry}) : message)
+    exit(0)
+  end
+
   cli = Kettle::Dev::ChangelogCLI.new(strict: strict_mode, enforce_coverage_thresholds: coverage_hard, update_prep: update_prep, version: version_override)
   if release_state_query
     state = cli.release_state

data/exe/kettle-release

@@ -43,16 +43,17 @@ end
 # Do not guard with __FILE__ == $PROGRAM_NAME because binstubs use Kernel.load.
 if ARGV.include?("-h") || ARGV.include?("--help")
   puts <<~USAGE
-    Usage: kettle-release [--version VERSION] [--local-ci] [start_step=<1-19>]
+    Usage: kettle-release [--version VERSION] [--local-ci] [start_step=<0-19>]
 
     Automates the release flow for a Ruby gem in the host project.
 
-    Full releases run `kettle-pre-release` before step 1 and abort if any
-    pre-release gate fails. Resume with start_step > 1 only after the gate has
-    passed or after intentionally handling the failure.
+    Full releases start at step 0 and run `kettle-pre-release` before the
+    numbered release steps. Any start_step greater than 0 skips pre-release
+    checks and resumes directly at the requested numbered step.
 
     Start steps (use start_step=<n> to begin at that step):
-      1. Verify Bundler >= 2.7 (always runs; start at 1 to do everything)
+      0. Run kettle-pre-release gates
+      1. Verify Bundler >= 2.7 (start at 1 to skip pre-release checks)
       2. Detect version; RubyGems sanity check; confirm CHANGELOG/version; sync copyright years; update badges/headers
       3. Run bin/setup
       4. Run bin/rake (default task)
@@ -88,8 +89,9 @@ if ARGV.include?("-h") || ARGV.include?("--help")
       DEBUG=true                  # Print backtraces on errors
 
     Examples:
-      kettle-release                       # full flow from the top (start_step=1)
+      kettle-release                       # full flow from the top (start_step=0)
       kettle-release --local-ci            # run local act CI, publish gem, then push commits/tags
+      kettle-release start_step=1          # skip pre-release checks and start numbered release steps
       kettle-release start_step=10         # resume by monitoring CI for the current branch
       SKIP_GEM_SIGNING=true kettle-release start_step=14  # build+release without signing
   USAGE
@@ -117,7 +119,7 @@ end
 
 local_ci = ARGV.include?("--local-ci")
 start_step_arg = ARGV.find { |a| a.start_with?("start_step=") }
-start_step = start_step_arg ? start_step_arg.split("=", 2)[1].to_i : 1
+start_step = start_step_arg ? start_step_arg.split("=", 2)[1].to_i : 0
 version_override = extract_version_arg!(ARGV)
 
 begin

data/lib/kettle/dev/changelog_cli.rb

@@ -14,6 +14,8 @@ module Kettle
     # includes coverage and YARD stats, and updates link references.
     class ChangelogCLI
       UNRELEASED_SECTION_HEADING = "[Unreleased]:"
+      CHANGELOG_VERSION_PATTERN = /\d+\.\d+\.\d+(?:[.-][0-9A-Za-z]+)*/
+      CHANGELOG_VERSION_PATTERN_SOURCE = CHANGELOG_VERSION_PATTERN.source
       # Matches a Markdown link-reference definition line, e.g. `[key]: https://...`
       LINK_REF_DEF_RE = /^\s*\[[^\]]+\]:\s+\S+/
       # Matches an ATX heading at H4 or deeper (####, #####, ...)
@@ -435,7 +437,7 @@ module Kettle
 
       def detect_previous_version(after_text)
         # after_text begins with the first released section following Unreleased
-        m = after_text.match(/^## \[(\d+\.\d+\.\d+)\]/)
+        m = after_text.match(/^## \[(#{CHANGELOG_VERSION_PATTERN_SOURCE})\]/o)
         return m[1] if m
 
         nil
@@ -445,7 +447,7 @@ module Kettle
         unreleased_block, before, after = extract_unreleased(changelog)
         abort("Could not find '## [Unreleased]' section in CHANGELOG.md") if unreleased_block.nil?
 
-        release_heading = after.to_s.match(/\A## \[(\d+\.\d+\.\d+)\][^\n]*\n/)
+        release_heading = after.to_s.match(/\A## \[(#{CHANGELOG_VERSION_PATTERN_SOURCE})\][^\n]*\n/o)
         abort("Could not find a prepared release section after '## [Unreleased]' in CHANGELOG.md") unless release_heading
 
         prepared_version = release_heading[1]
@@ -790,16 +792,16 @@ module Kettle
         non_t_tag_refs = {}
         lines[scan_start..-1].to_a.each do |l|
           # Case A: explicit tag ref key like [1.2.3t]: ...
-          if (m = l.match(/^\[(\d+\.\d+\.\d+)t\]:\s+(\S+)/))
+          if (m = l.match(/^\[(#{CHANGELOG_VERSION_PATTERN_SOURCE})t\]:\s+(\S+)/o))
             t_versions[m[1]] = true
             next
           end
           # Case B: non-t ref that nevertheless points to a tag URL (GitHub or GitLab)
-          if (m2 = l.match(/^\[(\d+\.\d+\.\d+)\]:\s+(\S+)/))
+          if (m2 = l.match(/^\[(#{CHANGELOG_VERSION_PATTERN_SOURCE})\]:\s+(\S+)/o))
             url = m2[2]
             # Accept only when the URL clearly points to a tag for the SAME version
             # Support both GitHub and GitLab style tag URLs
-            if (murl = url.match(%r{/(?:releases/)?tags?/v(\d+\.\d+\.\d+)}i))
+            if (murl = url.match(%r{/(?:releases/)?tags?/v(#{CHANGELOG_VERSION_PATTERN_SOURCE})}io))
               version_in_url = murl[1]
               if version_in_url == m2[1]
                 non_t_tag_refs[m2[1]] = url
@@ -817,7 +819,7 @@ module Kettle
         while i < lines.length
           line = lines[i]
           # Case 1: Heading contains legacy tag suffix we should convert
-          m = line.match(/^## \[(\d+\.\d+\.\d+)\](.*)\(\[tag\]\[(\d+\.\d+\.\d+)t\]\)\s*$/i)
+          m = line.match(/^## \[(#{CHANGELOG_VERSION_PATTERN_SOURCE})\](.*)\(\[tag\]\[(#{CHANGELOG_VERSION_PATTERN_SOURCE})t\]\)\s*$/io)
           if m && m[1] == m[3]
             ver = m[1]
             middle = m[2]
@@ -837,7 +839,7 @@ module Kettle
           end
 
           # Case 2: Heading does NOT contain suffix, but a matching tag ref exists; ensure a TAG list item
-          if (m2 = line.match(/^## \[(\d+\.\d+\.\d+)\](.*)$/))
+          if (m2 = line.match(/^## \[(#{CHANGELOG_VERSION_PATTERN_SOURCE})\](.*)$/o))
             ver2 = m2[1]
             # Skip Unreleased heading and non-release headings
             unless ver2.nil?
@@ -858,7 +860,7 @@ module Kettle
           # Footer duplication: if we are in the footer block and encounter a non-t tag-ref
           # without a matching t-ref, emit the t-ref immediately after with the same URL.
           if i >= scan_start
-            if (mref = line.match(/^\[(\d+\.\d+\.\d+)\]:\s+(\S+)/))
+            if (mref = line.match(/^\[(#{CHANGELOG_VERSION_PATTERN_SOURCE})\]:\s+(\S+)/o))
               vref = mref[1]
               mref[2]
               if non_t_tag_refs[vref] && !t_versions[vref]
@@ -949,9 +951,9 @@ module Kettle
         compares = {}
         tags = {}
         by_key.each do |k, v|
-          if k =~ /^(\d+\.\d+\.\d+)$/
+          if k =~ /^(#{CHANGELOG_VERSION_PATTERN_SOURCE})$/o
             compares[$1] = v
-          elsif k =~ /^(\d+\.\d+\.\d+)t$/
+          elsif k =~ /^(#{CHANGELOG_VERSION_PATTERN_SOURCE})t$/o
             tags[$1] = v
           end
         end

data/lib/kettle/dev/changelog_entry_adder.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Dev
+    class ChangelogEntryAdder
+      SECTIONS = %w[Added Changed Deprecated Removed Fixed Security].freeze
+
+      def initialize(section:, entry:, root: Kettle::Dev::CIHelpers.project_root)
+        @root = root
+        @section = section.to_s
+        @entry = normalize_entry(entry)
+        @changelog_path = File.join(@root, "CHANGELOG.md")
+      end
+
+      def run
+        raise Error, "unsupported changelog section #{@section.inspect}" unless SECTIONS.include?(@section)
+        raise Error, "missing CHANGELOG.md in #{Kettle::Dev.display_path(@root)}" unless File.file?(@changelog_path)
+
+        require_markly_crispr!
+        source = File.read(@changelog_path)
+        context = Ast::Crispr::Markdown::Markly.document_context(content: source, source_label: @changelog_path)
+        sections = context.structural_owners(owner_scope: :heading_sections)
+        unreleased = find_unreleased_heading!(sections)
+        target = find_unreleased_section!(sections, unreleased)
+        slice = target_slice(source, target)
+        return :unchanged if entry_present?(slice)
+
+        updated = insert_entry(source, target)
+        File.write(@changelog_path, updated)
+        :changed
+      end
+
+      private
+
+      def normalize_entry(entry)
+        text = entry.to_s.strip
+        raise Error, "changelog entry must not be empty" if text.empty?
+
+        text.start_with?("- ") ? text : "- #{text}"
+      end
+
+      def require_markly_crispr!
+        require "ast/crispr/markdown/markly"
+      rescue LoadError => error
+        raise Error, "kettle-changelog add-unreleased-entry requires ast-crispr-markdown-markly (#{error.message})"
+      end
+
+      def find_heading!(sections, heading_text:, level:)
+        matches = sections.select { |owner| owner.heading_text.to_s.strip == heading_text && owner.level == level }
+        raise Error, "expected exactly one #{heading(level, heading_text)} section in CHANGELOG.md, found #{matches.length}" unless matches.length == 1
+
+        matches.first
+      end
+
+      def find_unreleased_heading!(sections)
+        matches = sections.select do |owner|
+          owner.level == 2 && owner.heading_source.to_s.strip == "## [Unreleased]"
+        end
+        raise Error, "expected exactly one ## [Unreleased] section in CHANGELOG.md, found #{matches.length}" unless matches.length == 1
+
+        matches.first
+      end
+
+      def find_unreleased_section!(sections, unreleased)
+        matches = sections.select do |owner|
+          owner.heading_text.to_s.strip == @section &&
+            owner.level == 3 &&
+            owner.location.start_line > unreleased.location.start_line &&
+            owner.location.end_line <= unreleased.location.end_line
+        end
+        raise Error, "expected exactly one #{heading(3, @section)} section under ## [Unreleased] in CHANGELOG.md, found #{matches.length}" unless matches.length == 1
+
+        matches.first
+      end
+
+      def heading(level, text)
+        "#{"#" * level} #{text}"
+      end
+
+      def target_slice(source, target)
+        lines = source.lines
+        lines[(target.location.start_line - 1)...target.location.end_line].to_a.join
+      end
+
+      def entry_present?(slice)
+        slice.lines.any? { |line| line.chomp == @entry }
+      end
+
+      def insert_entry(source, target)
+        lines = source.lines
+        insertion_index = insertion_index(lines, target)
+        payload = entry_payload(lines, insertion_index, target)
+        lines.insert(insertion_index, payload)
+        lines.join
+      end
+
+      def insertion_index(lines, target)
+        first_content_index = target.location.start_line
+        index = target.location.end_line
+        while index > first_content_index && lines.fetch(index - 1).strip.empty?
+          index -= 1
+        end
+        index
+      end
+
+      def entry_payload(lines, insertion_index, target)
+        previous_line = lines[insertion_index - 1].to_s
+        next_line = lines[insertion_index].to_s
+        before = previous_line.strip.empty? ? "" : "\n"
+        after = (next_line.empty? || next_line.strip.empty?) ? "" : "\n"
+        "#{before}#{@entry}\n#{after}"
+      end
+    end
+  end
+end