This document is an attempt to record the policies and processes that are used to govern the Bundler project–it’s not fixed or permanent, and will likely evolve as events warrant.
These policies are intended to be examples of how to apply these goals, and we realize that we can’t possibly cover every edge case or loophole. In any case where policies turn out to conflict with these goals, the goals should win.
Bundler tries for perfect backwards compatibility. That means that if something worked in version 1.x, it should continue to work in 1.y and 1.z. That thing may or may not continue to work in 2.x. We may not always get it right, and there may be extenuating circumstances that force us into choosing between different kinds of breakage, but compatibility is very important to us. Infrastructure should be as unsurprising as possible.
As of August, 2022, the Bundler team ships features and bugfixes as 2.3.x versions, and may exceptionally backport security fixes to older series shipped with supported Rubies by default, namely, Bundler 2.1 (shipped with Ruby 2.7) and Bundler 2.2 (shipped with Ruby 3.0).
As a August, 2022, Bundler supports Ruby and RubyGems versions all the way back to Ruby 2.3, for backwards compatibility reasons. Several improvements have been introduced to not break anything when dropping support for old Rubies, so we’re aiming at dropping support for old Rubies at Christmas 2022, and follow the Ruby core team support policy more closely from then on.
These policies are not a guarantee that any particular fix will be backported. Instead, this is a way for us to set an upper limit on the versions of Ruby, RubyGems, and Bundler that we have to consider while making changes. Without the limit, the number of versions grows exponentially over time and quickly becomes overwhelming, which leads to maintainer burnout. We want to avoid that.
tl;dr: Majors about once per year, minors for any finished features with docs, patches for any committed bugfix.
Patch (bugfix) releases should generally be cut as soon as possible. A patch release for a single bugfix PR is totally okay.
Minor (feature) releases can be cut anytime at least one new feature is ready, but don’t have to be. Minor version releases must update their major version’s man pages and docs website as needed, and should each have their own “What’s new?” section.
Major (breaking) version releases should be cut no more than once per year, and must include a new section of the docs website dedicated to that major version. Ideally, major releases will happen after a Ruby version loses support in February or March, to help us stay in sync with Ruby versions supported by the core team.
Breaking changes other than dropping support for old Ruby versions should be avoided whenever possible, but may be included in major releases. In general, breaking changes should include at least one major version (and one year elapsed) with a deprecation warning before the breaking change takes effect.
The experience of using Bundler should not include surprises. If users are surprised, we did something wrong, and we should fix it. There are no user errors, only UX design failures. Warnings should always include actionable instructions to resolve them. Errors should include instructions, helpful references, or other information to help users attempt to debug.
Changing existing behavior is also surprising. If reducing user surprise will result in a backwards-incompatible change, that change should include at least one major version of deprecation warning before the breaking change is made.
Anyone is welcome to open an issue, or comment on an issue. Issue comments without useful content (like “me too”) may be removed.
Opening an issue to ask for help may eventually get you help, but chances are help will arrive faster if you post on Stack Overflow or ask in the Bundler Slack.
Issues will be handled as soon as possible, which may take some time. Including a script that can be used to reproduce your issue is a great way to help maintainers help you. If you can, writing a failing test for your issue is even more helpful.
Anyone is welcome to contribute to Bundler. Contributed code will be released under the same license as the existing codebase.
Pull requests must have passing tests to be merged. Code changes must also include tests for the new behavior. Squashing commits is not required.
Every pull request should explain:
Large changes often benefit from being written out more completely, read by others, and discussed. The Bundler RFC repo is the preferred place for that to happen.
Always create pull requests rather than pushing directly to the primary branch. Try to get code review and merge approval from someone other than yourself whenever possible.
Contributors who have contributed regularly for more than six months (or implemented a completely new feature for a minor release) are eligible to join the maintainer team. Unless vetoed by an existing maintainer, these contributors will be asked to join the maintainer team. If they accept, new maintainers will be given permissions to view maintainer playbooks, accept pull requests, and release new versions.
First off, Bundler’s policies and enforcement of those policies are subsidiary to Bundler’s code of conduct in any case where they conflict. The first priority is treating human beings with respect and empathy, and figuring out project guidelines and sticking to them will always come after that.
When it comes to carrying out our own policies, we’re all regular humans trying to do the best we can. There will probably be times when we don’t stick to our policies or goals. If you notice a discrepancy between real-life actions and these policies and goals, please bring it up! We want to make sure that our actions and our policies line up, and that our policies exemplify our goals.
Policies are not set in stone, and may be revised if policy violations are found to be in the spirit of the project goals. Likewise, actions that violate the spirit of the project goals will be considered policy violations, and enforcement action will be taken. We’re not interested in rules-lawyering, and we will take action when needed to ensure that everyone feels safe and included.
If you are comfortable reporting issues to the entire Bundler team, please send an email to team@bundler.io. If you are not comfortable reporting to the entire team, for any reason, please check the maintainers team list and use email, Twitter, or Slack to report to a single maintainer of your choice. Anyone violating a policy or goal is expected to cooperate with the team (and the reporter, if they request it) to resolve the issue in a way that follows the project goals.