🍲 Kettle::Dev

if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know, as I may have missed the discord notification.

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.

👣 How will this project approach the September 2025 hostile takeover of RubyGems? 🚑️

I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-takeover-of-rubygems-my-thoughts-5hlo).

🌻 Synopsis

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, and it ships command-line tools for changelog preparation, release automation, multi-forge git remotes, commit-message hooks, and Open Collective README updates.

Add it to a gem's development dependencies, then load the rake integration:

# Gemfile
group :development, :test do
  gem "kettle-dev", require: false
end

# Rakefile
require "kettle/dev"

For RSpec projects, use the matching test harness from kettle-test:

require "kettle/test/rspec"

Project setup and template refreshes are now owned by kettle-jem, not kettle-dev:

gem install kettle-jem
kettle-jem setup

Once a project is wired, the normal local development loop is:

bin/rake
bin/rake rubocop_gradual:autocorrect
bin/rake yard

And the maintainer release flow is:

bin/kettle-pre-release
bin/kettle-changelog
bin/kettle-release

What kettle-dev provides

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-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.
kettle-readme-backers for Open Collective README sections.
kettle-dev-setup as a deprecated compatibility executable that exits with instructions to use kettle-jem.

💡 Info you can shake a stick at

Tokens to Remember
Works with JRuby
Works with Truffle Ruby
Works with MRI Ruby 4
Works with MRI Ruby 3
Works with MRI Ruby 2
Support & Community
Source
Documentation
Compliance
Style
Maintainer 🎖️
`...` 💖	🧊 🐙 🛖 🧪

Compatibility

Compatible with MRI Ruby 2.4.0+, and concordant releases of JRuby, and TruffleRuby. CI workflows and Appraisals are generated for MRI Ruby 2.4+. 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 ✨

Federated DVCS

Find this repo on federated forges (Coming soon!)

| Federated [DVCS][💎d-in-dvcs] Repository | Status | Issues | PRs | Wiki | CI | Discussions | |-------------------------------------------------|-----------------------------------------------------------------------|---------------------------|--------------------------|---------------------------|--------------------------|------------------------------| | 🧪 [kettle-rb/kettle-dev on GitLab][📜src-gl] | The Truth | [💚][🤝gl-issues] | [💚][🤝gl-pulls] | [💚][📜gl-wiki] | 🐭 Tiny Matrix | ➖ | | 🧊 [kettle-rb/kettle-dev on CodeBerg][📜src-cb] | An Ethical Mirror ([Donate][🤝cb-donate]) | [💚][🤝cb-issues] | [💚][🤝cb-pulls] | ➖ | ⭕️ No Matrix | ➖ | | 🐙 [kettle-rb/kettle-dev on GitHub][📜src-gh] | Another Mirror | [💚][🤝gh-issues] | [💚][🤝gh-pulls] | [💚][📜gh-wiki] | 💯 Full Matrix | [💚][gh-discussions] | | 🎮️ [Discord Server][✉️discord-invite] | [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] | [Let's][✉️discord-invite] | [talk][✉️discord-invite] | [about][✉️discord-invite] | [this][✉️discord-invite] | [library!][✉️discord-invite] |

Enterprise Support

Available as part of the Tidelift Subscription.

Need enterprise-level guarantees?

The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. [![Get help from me on Tidelift][🏙️entsup-tidelift-img]][🏙️entsup-tidelift] - 💡Subscribe for support guarantees covering _all_ your FLOSS dependencies - 💡Tidelift is part of [Sonar][🏙️entsup-tidelift-sonar] - 💡Tidelift pays maintainers to maintain the software you depend on!
📊`@`Pointy Haired Boss: An [enterprise support][🏙️entsup-tidelift] subscription is "[never gonna let you down][🧮kloc]", and *supports* open source maintainers Alternatively: - [![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]

✨ Installation

Install the gem and add to the application's Gemfile by executing:

bundle add kettle-dev

If bundler is not being used to manage dependencies, install the gem by executing:

gem install kettle-dev

⚙️ Configuration

Kettle-dev has two integration surfaces:

Executable scripts in exe/, or binstubs generated from them, can run when kettle-dev is installed and loadable.
Rake tasks are registered by adding kettle-dev to the project's development dependencies and requiring kettle/dev from the project's Rakefile.

group :development, :test do
  gem "kettle-dev", require: false
end

require "kettle/dev"

RSpec

This gem integrates tightly with kettle-test.

require "kettle/test/rspec"

# ... any other config you need to do.

# NOTE: Gemfiles for older rubies (< 2.7) won't have kettle-soup-cover.
#       The rescue LoadError handles that scenario.
begin
  require "kettle-soup-cover"
  require "simplecov" if Kettle::Soup::Cover::DO_COV # `.simplecov` is run here!
rescue LoadError => error
  # check the error message, and re-raise if not what is expected
  raise error unless error.message.include?("kettle")
end

# This gem (or app)
require "gem-under-test"

Rakefile

Add to your Rakefile:

require "kettle/dev"

This loads the kettle-dev rake task set. Current project setup and template refreshes should be run through kettle-jem:

gem install kettle-jem
kettle-jem setup

kettle-dev-setup is still shipped for compatibility, but it now exits with a message explaining that setup and templating moved to kettle-jem.

Useful registered tasks include:

rubocop_gradual:autocorrect and rubocop_gradual:check
reek and reek:update
yard
appraisal:install, appraisal:generate, appraisal:update, and appraisal:reset
ci:act
bench
kettle:jem:template and kettle:jem:selftest, when kettle-jem's task integration is available

Install binstubs when a project wants local bin/kettle-* commands:

bundle binstubs kettle-dev --path bin

Environment Variables

Below are the primary environment variables recognized by kettle-dev (and its integrated tools). Unless otherwise noted, set boolean values to the string "true" to enable.

General/runtime

DEBUG: Enable extra internal logging for this library (default: false)
REQUIRE_BENCH: Enable require_bench to profile requires (default: false)
CI: When set to true, adjusts default rake tasks toward CI behavior

Coverage (kettle-soup-cover / SimpleCov)

K_SOUP_COV_DO: Enable coverage collection (default: true in .envrc)
K_SOUP_COV_FORMATTERS: Comma-separated list of formatters (html, xml, rcov, lcov, json, tty)
K_SOUP_COV_MIN_LINE: Minimum line coverage threshold (integer, e.g., 100)
K_SOUP_COV_MIN_BRANCH: Minimum branch coverage threshold (integer, e.g., 100)
K_SOUP_COV_MIN_HARD: Fail the run if thresholds are not met (true/false)
K_SOUP_COV_MULTI_FORMATTERS: Enable multiple formatters at once (true/false)
K_SOUP_COV_OPEN_BIN: Path to browser opener for HTML (empty disables auto-open)
MAX_ROWS: Limit console output rows for simplecov-console (e.g., 1)

Tip: When running a single spec file locally, you may want K_SOUP_COV_MIN_HARD=false to avoid failing thresholds for a partial run.

GitHub API and CI helpers

GITHUB_TOKEN or GH_TOKEN: Token used by ci:act and release workflow checks to query GitHub Actions status at higher rate limits
GITLAB_TOKEN or GL_TOKEN: Token used by ci:act and CI monitor to query GitLab pipeline status

Releasing and signing

SKIP_GEM_SIGNING: If set, skip gem signing during build/release
GEM_CERT_USER: Username for selecting your public cert in certs/<USER>.pem (defaults to $USER)
SOURCE_DATE_EPOCH: Reproducible build timestamp. kettle-release will set this automatically for the session.

Git hooks and commit message helpers (exe/kettle-commit-msg)

GIT_HOOK_BRANCH_VALIDATE: Branch name validation mode (e.g., jira) or false to disable
GIT_HOOK_FOOTER_APPEND: Append a footer to commit messages when goalie allows (true/false)
GIT_HOOK_FOOTER_SENTINEL: Required when footer append is enabled — a unique first-line sentinel to prevent duplicates
GIT_HOOK_FOOTER_APPEND_DEBUG: Extra debug output in the footer template (true/false)

For a quick starting point, this repository’s .envrc shows sane defaults, and .env.local can override them locally.

🔧 Basic Usage

Common local workflows:

bundle exec rake runs the curated default task set. Locally this favors autocorrection where supported; with CI=true it favors check-only behavior.
bin/rspec or bundle exec rspec runs specs.
K_SOUP_COV_MIN_HARD=false bin/rspec spec/path/to/file_spec.rb is useful for focused spec runs that should not fail whole-suite coverage thresholds.
bundle exec rake rubocop_gradual:autocorrect applies gradual RuboCop fixes.
bundle exec rake rubocop_gradual:check is the CI-friendly RuboCop Gradual task.
bundle exec rake reek and bundle exec rake reek:update run or refresh Reek.
bundle exec rake yard builds API documentation.
bundle exec rake appraisal:install performs first-time Appraisal setup.
bundle exec rake appraisal:generate regenerates Appraisal gemfiles.
bundle exec rake appraisal:update updates Appraisal locks and applies gradual RuboCop autocorrect.
bundle exec rake appraisal:reset removes Appraisal lockfiles below gemfiles/.

GitHub Actions local runner helper:

bundle exec rake ci:act opens an interactive workflow selector using .github/workflows and live CI status when tokens are available.
bundle exec rake ci:act[loc] selects by short code.
bundle exec rake ci:act[locked_deps.yml] selects by workflow filename.
Set GITHUB_TOKEN or GH_TOKEN for GitHub Actions API status.
Set GITLAB_TOKEN or GL_TOKEN for GitLab pipeline status.

Project automation and template refreshes:

Use kettle-jem setup for first-time setup and kettle-jem install for full template refreshes.
When kettle-jem's rake integration is installed, run bundle exec rake kettle:jem:template to refresh template-managed files.
kettle-dev-setup is deprecated and intentionally exits with a migration message pointing to kettle-jem.

kettle-dvcs (normalize multi-forge remotes)

Script: exe/kettle-dvcs (install binstubs for convenience: bundle binstubs kettle-dev --path bin)
Purpose: Normalize git remotes across GitHub, GitLab, and Codeberg, and create an all remote that pushes to all and fetches only from your chosen origin.
Assumptions: org and repo names are identical across forges. Usage:

kettle-dvcs [options] [ORG] [REPO]

Options:

--origin [github|gitlab|codeberg] Which forge to use as origin (default: github)
--protocol [ssh|https] URL style (default: ssh)
--github-name NAME Remote name for GitHub when not origin (default: gh)
--gitlab-name NAME Remote name for GitLab (default: gl)
--codeberg-name NAME Remote name for Codeberg (default: cb)
--force Non-interactive; accept defaults, and do not prompt for ORG/REPO Examples:
Default, interactive (infers ORG/REPO from an existing remote when possible): console kettle-dvcs
Non-interactive with explicit org/repo: console kettle-dvcs --force my-org my-repo
Use GitLab as origin and HTTPS URLs: console kettle-dvcs --origin gitlab --protocol https my-org my-repo

What it does:

Ensures remotes exist and have consistent URLs for each forge.
Renames existing remotes when their URL already matches the desired target but their name does not (e.g., gitlab -> gl).
Creates/refreshes an all remote that:
- fetches only from your chosen origin forge.
- has pushurls configured for all three forges so git push all <branch> updates all mirrors.
Prints git remote -v at the end.
Attempts to git fetch each forge remote to check availability:
- If all succeed, the README’s federated DVCS summary line has “(Coming soon!)” removed.
- If any fail, the script prints import links to help you create a mirror on that forge.

Releasing (maintainers)

Script: exe/kettle-release (run as kettle-release)
Purpose: guided release helper that:
- 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]).
  - Select workflow with K_RELEASE_LOCAL_CI_WORKFLOW (with or without .yml/.yaml). Defaults to locked_deps.yml if present; otherwise the first workflow discovered.
  - On failure, the release prep commit is soft-rolled-back (git reset --soft HEAD^) and the process aborts.
- Ensures trunk sync and rebases feature as needed, pushes, monitors GitHub Actions with a progress bar, and merges feature to trunk on success.
- 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)
  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)
  5. Run bin/rake appraisal:update if Appraisals present, then bin/rake yard
  6. Ensure git user configured; commit release prep
  7. Optional local CI with act (controlled by K_RELEASE_LOCAL_CI)
  8. Ensure trunk in sync across remotes; rebase feature as needed
  9. Push current branch to remotes (or 'all' remote)
  10. Monitor CI after push; abort on failures
  11. Merge feature into trunk and push
  12. Checkout trunk and pull latest
  13. Gem signing checks/guidance (skip with SKIP_GEM_SIGNING=true)
  14. Build gem (bundle exec rake build)
  15. Release gem (bundle exec rake release)
  16. Generate and validate checksums (bin/gem_checksums)
  17. Push checksum commit
  18. Create GitHub Release (requires GITHUB_TOKEN)
  19. Push tags to remotes (final)
Examples:
- After intermittent CI failure, restart from monitoring: bundle exec kettle-release start_step=10
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.

Changelog generator

Script: exe/kettle-changelog (run as kettle-changelog)
Purpose: Generates a new CHANGELOG.md section for the current version read from lib/**/version.rb, moves notes from the Unreleased section, and updates comparison links.
Prerequisites:
- coverage/coverage.json present (generate with: K_SOUP_COV_FORMATTERS="json" bin/rspec).
- bin/rake yard available, to compute documentation coverage.
Usage:
- kettle-changelog
Behavior:
- Reads version from the unique lib/**/version.rb in the project.
- Moves entries from the [Unreleased] section into a new [#.#.#] - YYYY-MM-DD section.
- Prepends 4 lines with TAG, line coverage, branch coverage, and percent documented.
- Converts any GitLab-style compare links at the bottom to GitHub style, adds new tag/compare links for the new release and a temporary tag reference [X.Y.Zt].

Pre-release checks

Script: exe/kettle-pre-release (run as kettle-pre-release)
Purpose: Run a suite of pre-release validations to catch avoidable mistakes (resumable by check number).
Usage:
- kettle-pre-release [--check-num N]
- Short option: kettle-pre-release -cN
Options:
- --check-num N Start from check number N (default: 1)
Checks:
- 1) Validate that all image URLs referenced by Markdown files resolve (HTTP HEAD)

Commit message helper (git hook)

Script: exe/kettle-commit-msg (run by git as .git/hooks/commit-msg)
Purpose: Append a standardized footer and optionally enforce branch naming rules when configured.
Usage:
- Git invokes this with the path to the commit message file: kettle-commit-msg .git/COMMIT_EDITMSG
- Install hook templates through kettle-jem setup/templating, then point git at the resulting hook path.
Behavior:
- When GIT_HOOK_BRANCH_VALIDATE=jira, validates the current branch matches the pattern: ^(hotfix|bug|feature|candy)/[0-9]{8,}-….
  - If it matches and the commit message lacks the numeric ID, appends [<type>][<id>].
- Always invokes Kettle::Dev::GitCommitFooter.render to potentially append a footer if allowed by the goalie.
- Prefers project-local .git-hooks templates; falls back to ~/.git-hooks.
Environment:
- GIT_HOOK_BRANCH_VALIDATE Branch rule (e.g., jira) or false to disable.
- GIT_HOOK_FOOTER_APPEND Enable footer auto-append when goalie allows (true/false).
- GIT_HOOK_FOOTER_SENTINEL Required marker to avoid duplicate appends when enabled.
- GIT_HOOK_FOOTER_APPEND_DEBUG Extra debug output in the footer template (true/false).

Project bootstrap installer

Script: exe/kettle-dev-setup (run as kettle-dev-setup)
Status: Deprecated compatibility shim.
Purpose: Direct users to kettle-jem, which now owns setup and templating.
Usage:
- kettle-dev-setup
Behavior:
- Prints migration instructions.
- Exits non-zero.
- Does not modify the destination repository.
Replacement:
- gem install kettle-jem
- kettle-jem setup

Open Collective README updater

Script: exe/kettle-readme-backers (run as kettle-readme-backers)
Purpose: Updates README sections for Open Collective backers (individuals) and sponsors (organizations) by fetching live data from your collective.
Tags updated in README.md (first match wins for backers):
- The default tag prefix is OPENCOLLECTIVE, and it is configurable:
  - ENV: KETTLE_DEV_BACKER_README_OSC_TAG="OPENCOLLECTIVE"
  - YAML (.opencollective.yml): readme-osc-tag: "OPENCOLLECTIVE"
  - The resulting markers become:  … ,  … , and  … .
  - ENV overrides YAML.
- Backers (Individuals):  …  or  … 
- Sponsors (Organizations):  … 
Handle resolution:
1. OPENCOLLECTIVE_HANDLE environment variable, if set
2. opencollective.yml in the project root (e.g., collective: "kettle-rb" in this repo)
Usage:
- exe/kettle-readme-backers
- OPENCOLLECTIVE_HANDLE=my-collective exe/kettle-readme-backers
Behavior:
- Writes to README.md only if content between the tags would change.
- If neither the backers nor sponsors tags are present, prints a helpful warning and exits with status 2.
- When there are no entries, inserts a friendly placeholder: "No backers yet. Be the first!" or "No sponsors yet. Be the first!".
- When updates are written and the repository is a git work tree, the script stages README.md and commits with a message thanking new backers and subscribers, including mentions for any newly added backers and subscribers (GitHub @handles when their website/profile is a github.com URL; otherwise their name).
- Customize the commit subject via env var: KETTLE_README_BACKERS_COMMIT_SUBJECT="💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜".
  - Or via .opencollective.yml: set readme-backers-commit-subject: "💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜".
  - Precedence: ENV overrides .opencollective.yml; if neither is set, a sensible default is used.
  - Note: When used with the provided .git-hooks, the subject should start with a gitmoji character (see gitmoji).
Tip:
- Run this locally before committing to keep your README current, or schedule it in CI to refresh periodically.
- It runs automatically on a once-a-week schedule by the .github/workflows/opencollective.yml workflow that is part of the kettle-jem template.
Authentication requirement:
- When running in CI with the provided workflow, you must provide an organization-level Actions secret named README_UPDATER_TOKEN.
  - Create it under your GitHub organization settings: https://github.com/organizations/<YOUR_ORG>/settings/secrets/actions.
  - The updater will look for REPO or GITHUB_REPOSITORY (both usually set by GitHub Actions) to infer <YOUR_ORG> for guidance.
  - If README_UPDATER_TOKEN is missing, the tool prints a helpful error to STDERR and aborts, including a direct link to the expected org settings page.

🔐 Security

See SECURITY.md.

🤝 Contributing

If you need some ideas of where to help, you could work on adding more code coverage, or if it is already 💯 (see below) check issues or PRs, or use the gem and think about how it could be better.

We so if you make changes, remember to update it.

See CONTRIBUTING.md for more detailed instructions.

🚀 Release Instructions

See CONTRIBUTING.md.

Code Coverage

Coverage service badges

[![Coverage Graph][🏀codecov-g]][🏀codecov] [![Coveralls Test Coverage][🏀coveralls-img]][🏀coveralls] [![QLTY Test Coverage][🏀qlty-covi]][🏀qlty-cov]

🪇 Code of Conduct

Everyone interacting with this project's codebases, issue trackers, chat rooms and mailing lists agrees to follow the .

🌈 Contributors

Made with contributors-img.

Also see GitLab Contributors: https://gitlab.com/kettle-rb/kettle-dev/-/graphs/main

⭐️ Star History

📌 Versioning

This library follows for its public API where practical. For most applications, prefer the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("kettle-dev", "~> 2.0")

📌 Is "Platform Support" part of the public API? More details inside.

Dropping support for a platform can be a breaking change for affected users. If a release changes supported platforms, it should be called out clearly in the changelog and versioned with that impact in mind. To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer: - ["Major Version Numbers are Not Sacred"][📌major-versions-not-sacred]

See CHANGELOG.md for a list of releases.

📄 License

The gem is available under the following license: AGPL-3.0-only. See LICENSE.md for details.

If none of the available licenses suit your use case, please contact us to discuss a custom commercial license.

© Copyright

See LICENSE.md for the official copyright notice.

🤑 A request for help

Maintainers have teeth and need to pay their dentists. After getting laid off in an RIF in March, and encountering difficulty finding a new one, I began spending most of my time building open source tools. I'm hoping to be able to pay for my kids' health insurance this month, so if you value the work I am doing, I need your support. Please consider sponsoring me or the project.

To join the community or get help 👇️ Join the Discord.

To say "thanks!" ☝️ Join the Discord or 👇️ send money.

💌 💌 💌

Please give the project a star ⭐ ♥.

Many parts of this project are actively managed by a kettle-jem smart template utilizing StructuredMerge.org merge contracts.

Thanks for RTFM. ☺️

Field	Value
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-rb/kettle-dev
Source	https://github.com/kettle-rb/kettle-dev/tree/v2.0.6
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-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