doc/playbooks/RELEASING.md
Bundler uses Semantic Versioning.
Note: In the documentation listed below, the current minor version number is 1.11 and the next minor version number is 1.12
Regardless of the version, all releases must update the CHANGELOG.md and lib/bundler/version.rb
files. The changelog for the first stable minor release (1.12.0) is a sum of all
the preceding pre-release versions (1.12.pre.1, 1.12.pre.2, etc) for that
minor version. The changelog for the first stable minor release is left blank
unless there are fixes included since the last pre/rc release.
In general, master will accept PRs for:
Bundler cares a lot about preserving compatibility. As a result, changes that break backwards compatibility should (whenever this is possible) include a feature release that is backwards compatible, and issue warnings for all options and behaviors that will change.
We try very hard to only release breaking changes when incrementing the major version of Bundler.
Patch releases are made by cherry-picking bug fixes from master.
When we cherry-pick, we cherry-pick the merge commits using the following command:
$ git cherry-pick -m 1 MERGE_COMMIT_SHAS
For example, for PR #5029, we cherry picked commit dd6aef9, not 4fe9291 using:
$ git cherry-pick -m 1 dd6aef9
The rake release:prepare_patch command will automatically handle
cherry-picking, and is further detailed below.
Bundler maintains a list of changes present in each version in the CHANGELOG.md file.
Entries should not be added in pull requests, but are rather written by the Bundler
maintainers before the release.
To fill in the changelog, maintainers can go through the relevant PRs using the
rake release:open_unreleased_prs and manually add a changelog entry for each
PR that it's about to be released.
If you're releasing a patch level version, you can use rake release:open_unreleased_prs to instead label each relevant PR with the proper
milestone of the version to be release. Then the rake release:patch task will
go only through those PRs, and prompt you to add a changelog entry for each of
them.
While pushing a gem version to RubyGems.org is as simple as rake release,
releasing a new version of Bundler includes a lot of communication: team consensus,
git branching, changelog writing, documentation site updates, and a blog post.
Dizzy yet? Us too.
Here's the checklist for releasing new minor versions:
version.rb to a prerelease number, e.g. 1.12.pre.1CHANGELOG.md to include all of the features, bugfixes, etc for that
version.rake release, tweet, blog, let people know about the prerelease!.pre.2 as a patch release. In general, once a stable
branch has been cut from master, it should not have master merged back into it.Wait! You're not done yet! After your prelease looks good:
version.rb to a final version (i.e. 1.12.0)cp -r v1.11 v1.12)rake release in the bundler repo, tweet, link to the blog post, etc.At this point, you're a release manager! Pour yourself several tasty drinks and think about taking a vacation in the tropics.
Beware, the first couple of days after the first non-prerelease version in a minor version series can often yield a lot of bug reports. This is normal, and doesn't mean you've done anything wrong as the release manager.
Minor releases of the next version start with a new release branch from the
current state of master: 1-12-stable, and are immediately followed by a .pre.1 release.
Once that -stable branch has been cut from master, changes for that minor
release series (1.12) will only be made intentionally, via patch releases.
That is to say, changes to master by default won't make their way into any
1.12 version, and development on master will be targeting the next minor
or major release.
Releasing new bugfix versions is really straightforward. Increment the tiny version
number in lib/bundler/version.rb, and in CHANGELOG.md add one bullet point
per bug fixed. Then run rake release from the -stable branch,
and pour yourself a tasty drink!
PRs containing regression fixes for a patch release of the current minor version
are merged to master. These commits need to be cherry-picked from master onto
the minor branch (1-12-stable).
There is a rake release:prepare_patch rake task that helps with creating a patch
release. It takes a single argument, the exact patch release being made (e.g.
1.12.3), but if not given it will bump the tiny version number by one. This
task checks out the appropriate stable branch (1-12-stable), grabs the
1.12.3 milestone from GitHub, ensures all PRs are closed, and then
cherry-picks those changes (and only those changes) to a new branch based off
the stable branch. Then bumps the version in the version file and commits that
change on top of the cherry-picks.
Now you have a release branch ready to be merged into the stable branch. You'll
want to open a PR from this branch into the stable branch and provided CI is
green, you can go ahead, merge the PR and run rake release from the updated
stable branch.
Early releases require heavy testing, especially across various system setups.
We :heart: testers, and are big fans of anyone who can run gem install bundler --pre
and try out upcoming releases in their development and staging environments.
There may not always be prereleases or beta versions of Bundler. The Bundler team will tweet from the @bundlerio account when a prerelease or beta version becomes available. You are also always welcome to try checking out master and building a gem yourself if you want to try out the latest changes.