📝 Kettle::Changelog

if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know on Discord or RubyForum, as I may have missed the 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.

🌻 Synopsis

kettle-changelog prepares and maintains CHANGELOG.md files for Ruby gems. It moves entries from Unreleased into a versioned release section, adds coverage and documentation statistics, updates comparison links, and can emit structured release events for orchestration tools.

💡 Info you can shake a stick at

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

Compatibility

The gem's declared runtime compatibility floor is MRI Ruby 4.0.0+, with concordant releases of JRuby and TruffleRuby. CI workflows and Appraisals are generated for MRI Ruby 4.0.0+. The current MRI CI lane runs on Linux and macOS. The test floor is configured by ruby.test_minimum in .kettle-jem.yml. When it is higher than the runtime floor, older runtime-compatible Rubies are not covered by the generated CI or Appraisal matrix.

The amazing test matrix is powered by the kettle-dev stack.

How kettle-dev manages complexity in tests

Gem	Source	Role	Total downloads
appraisal2	GitHub	multi-dependency Appraisal matrix generation
appraisal2-rubocop	GitHub	RuboCop Appraisal generator integration
kettle-dev	GitHub	development, release, and CI workflow tooling
kettle-jem	GitHub	Appraisals & CI workflow templates
kettle-soup-cover	GitHub	SimpleCov coverage policy and reporting
kettle-test	GitHub	standard test runner and coverage harness
rubocop-lts	GitHub	Ruby-version-aware linting
turbo_tests2	GitHub	parallel test execution

Federated DVCS

Find this repo on federated forges (Coming soon!)

Federated DVCS Repository	Status	Issues	PRs	Wiki	CI
🧪 kettle-dev/kettle-changelog on GitLab	The Truth	💚	💚	💚	🐭 Tiny Matrix
🧊 kettle-dev/kettle-changelog on CodeBerg	An Ethical Mirror (Donate)	💚	💚	➖	⭕️ No Matrix
🐙 kettle-dev/kettle-changelog on GitHub	Another Mirror	💚	💚	💚	💯 Full Matrix

Enterprise Support

For enterprise support from the maintainer, use Upwork or CodeMentor.

Other support channels:

• 
• 

✨ Installation

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

bundle add kettle-changelog

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

gem install kettle-changelog

⚙️ Configuration

kettle-changelog has no project configuration file. Configure project-specific paths and release behavior with environment variables:

• K_CHANGELOG_PATH selects a changelog outside the current project root.
• K_CHANGELOG_COVERAGE_ROOT selects the project root used for coverage generation.
• K_CHANGELOG_COVERAGE_GEMFILE selects the target-project Gemfile used for coverage generation. It is resolved relative to the coverage root; absent an explicit setting, gemfiles/coverage.gemfile is preferred when generated by Appraisal, then the root Gemfile is used.
• K_CHANGELOG_VERSION_FILE selects the version file when the project has more than one version tree.
• K_CHANGELOG_GEM_NAME overrides the gem name used for release lookups.
• K_CHANGELOG_STRICT=false allows missing coverage or YARD data.
• K_CHANGELOG_COVERAGE_HARD=false disables hard coverage-threshold failures.
• KETTLE_GEM_COOP_REFRESH=true refreshes cached gem metadata.

🔧 Basic Usage

Run the release preparation command from the gem root:

bundle exec kettle-changelog

Use --coverage-gemfile PATH to select a different target-project coverage bundle for one invocation. This is intentionally separate from BUNDLE_GEMFILE, which may be required to run kettle-changelog itself from a release bundle.

Use --yes for non-interactive release automation. Add a note without preparing a release with:

bundle exec kettle-changelog --add-unreleased-entry --section Fixed --entry "Describe the fix."

Extract a specific release without modifying the changelog:

bundle exec kettle-changelog --release v1.2.3 --file CHANGELOG.md
# Or pipe Markdown to stdin:
cat CHANGELOG.md | bundle exec kettle-changelog --release 1.2.3
# Select every release in a major or minor version:
bundle exec kettle-changelog --release v3.2 --file CHANGELOG.md
# Select the first published release instead:
bundle exec kettle-changelog --latest --file CHANGELOG.md

--latest and --release are mutually exclusive. A one- or two-segment version (such as 3 or v3.2) returns an array of matching releases in changelog order; full versions and --latest return one object. Both forms accept an optional v prefix. No matches exit nonzero. The command prints JSON with version, date, tag, markdown, coverage, branch_coverage, and documented. Missing metadata is null. The Markdown body excludes the release heading and contains its referenced link definitions, found anywhere in the changelog. Shared definitions are included independently in each matching release. Release headings must be level two and contain a three-part version, optionally prefixed with v and followed by a date and tag link. A subsequent level-two heading or a level-three community, sponsorship, funding, contributing, acknowledgments, or license heading ends the release. Missing or ambiguous releases and invalid input exit nonzero. The Ruby API is Kettle::Changelog::Release.extract(content: markdown, version: "1.2.3") and raises Kettle::Changelog::Error on failure.

Useful queries and maintenance commands include --pending-release, --release-state, --release-stats, --reformat, --update-prep, --json, and --events=changelog. Run bundle exec kettle-changelog --help for the complete option list.

🔐 Security

See SECURITY.md.

🤝 Contributing

If you need some ideas of where to help, you could work on adding more code coverage, 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

🪇 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-dev/kettle-changelog/-/graphs/main

📌 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-changelog", "~> 1.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"

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.

Copyright holders

• Copyright (c) 2026 Peter H. Boling

🤑 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, use the RubyForum or Discord.

To say "thanks!" ☝️ Join the community 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-changelog
Description	📝 kettle-changelog formats release sections, manages Unreleased entries, and emits machine-readable release events for Ruby gems.
Homepage	https://github.com/kettle-dev/kettle-changelog
Source	https://github.com/kettle-dev/kettle-changelog
License	AGPL-3.0-only
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://www.buymeacoffee.com/pboling