123456789_123456789_123456789_123456789_123456789_

Puma Support Policy

What

This document's purpose is to help users and contributors of this library make future plans based on the trajectory of this project. It is loosely worded and should be expected to change over time. Maintainers and contributors are encouraged to follow the guidance here but are not strictly bound by it.

What does "supported" mean?

Puma is a community-run project. "Support" means "what do the maintainers pay attention to and what are they likely to merge", and doesn't mean that we do anything by any particular date, or even at all. We may all jet off to a private island tomorrow and never speak again.

But, if we do decide to keep devoting our free time to open source software, we will support the Ruby versions, Ruby implementations, Rack versions, and operating systems which run on our CI, in any combination, even combinations that CI doesn't run directly.

If you open a PR or bug report for a combination of those factors outside of our CI matrix, we may still accept it if it's a small and low-risk fix.

We may add environments to CI at any time, but we only drop a supported environment in a minor or major release.

CI matrix

CI aims for the most coverage with the fewest jobs.

Every OS and architecture runs the oldest supported Ruby on its oldest runner image, and the newest Ruby on its newest image.

"Runner images" means every standard GitHub-hosted runner image currently listed inGitHub's runner docs, not only the images CI already uses.

On x64, a few more jobs fill in the gaps:

Versioning

Puma followsSemVer 2.0. Puma's public API is its HTTP serving behavior over the socket and its configuration. All of Puma's other Ruby APIs are private and may change in any release.

Puma is an HTTP/1.1 server, so any deviation from the relevant RFCs is a bug, which we may fix in a patch release.

PRs labeled breaking change are strong evidence that a major release is needed.

Puma release support policy

By default, Puma supports one release version, the latest release. That means if there is a bug in 3.2.1 (made-up numbers for example only), but the latest release is 4.3.2, the bug must be reproduced in 4.3.2 to qualify for support.

When a new major (and sometimes minor) version is released, Puma maintainers will try to preserve the status of the old version via branches and/or tags. Puma maintainers can choose to backport fixes to older versions and cut a release of older versions, but this behavior should not be assumed.

If a bug report cannot be reproduced with the latest Puma version, it may be closed.

Security fixes follow a separate policy; seeSECURITY.md.

Ruby version support policy

"Ruby version" refers to the https://github.com/ruby/ruby implementation. Puma also supports other Ruby implementations (the origin of Puma involves an alternate Ruby implementation, Rubinius); see below.

Ruby upstream support is documented at https://www.ruby-lang.org/en/downloads/branches/. A "minor" version is X.Y, with X.Y.Z being a patch release. Puma supports every Ruby minor version that is not EOL upstream. Puma may also continue to support older, EOL Ruby versions; the gemspec's required_ruby_version declares the oldest supported version. Maintainers decide when to raise that minimum. The Puma team recommends you always use the latest Ruby release.

When Puma supports a Ruby version, it will include that version in the CI matrix. CI runs only the most recent patch version of each supported Ruby minor version. If a bug is reported, the report must be reproducible using the most recent patch version of a currently supported Ruby minor version.

Puma may rely on upstream support to fix bugs in Ruby rather than working around them. That means, if a bug exists only in a Ruby version that is EOL upstream, it may be closed (it's not guaranteed that we will work around legacy Ruby issues).

When Puma does work around a bug in a specific Ruby patch version, the workaround stays until Puma drops support for that Ruby minor version.

Alternate implementations of Ruby (version support policy)

An example of an "alternate" implementation of Ruby is JRuby. Ruby implementations typically target a specific "spec" of ruby/ruby, for example, JRuby 10.0 targets ruby/ruby version 3.4. The target version of a supported implementation must be within the above "Ruby version support policy." Additionally, the implementation release must be supported upstream.

Puma supports the JRuby implementation. Puma supports the TruffleRuby implementation.

Rack (and SPEC) version support

From the current Rack documentation https://github.com/rack/rack?tab=readme-ov-file#version-support, Rack lists support levels to be:

Puma will support any Rack version that still accepts "bug fixes" in addition to security patches. Rack versions that receive only security patches, or are at end of support, are not supported.

Due to the need to support "hot" reloading applications (via phased restart) which might have different Rack versions,Puma cannot directly declare the minimum Rack version. Puma may use runtime or boot time checks to warn or error about Rack version support.

Bundler version support

Puma supports the Bundler version that ships with each supported Ruby version.

How to use this document

You can use the guidelines here to make suggestions to contributors (anyone reporting an issue, helping with via a comment, or opening a PR) or maintainers. For example, "I could not reproduce your issue using a currently supported Ruby version. Can you please update to version X.Y and verify the issue persists?" Please link to this doc, state what action you're requesting, and why you feel that action is supported by this document. Please act in "good faith" and do not "bikeshed" (the practice of focusing on non-structural or seemingly irrelevant details).

How to update this document?

Generally, you shouldn't suggest changes to policies in this document unless you have committed to the Puma project.

Non-committers:

Committers: