Document the release process

[segiddins]

Let's try and reduce our bus factor by a bit...

• Branching stable versions
• Backporting commits from master to stable
• Compiling a CHANGELOG
• Releasing the gem

[indirect]

RELEASING.md

Bugfix releases

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 and pour yourself a tasty drink. 🍹 🎊

Feature releases

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.

Here's the checklist for releasing new minor versions:

[ ] Check with the core team to ensure that there is consensus around shipping a feature release. As a general rule, this should always be okay, since features should never break backwards compatibility.
[ ] Create a new stable branch from master. For example, version 1.11 would mean branching as 1-11-stable
[ ] Update version.rb to a prerelease number, e.g. 1.11.pre.1
[ ] Update CHANGELOG.md to include all of the features, bugfixes, etc for that version.
[ ] Run rake release, tweet, blog, let people know about the prerelease
[ ] Wait a minimum of 7 days
[ ] If significant problems are found, increment the prerelease (i.e. 1.11.pre.2) and repeat
[ ] Update version.rb to a final version (i.e. 1.11.0)
[ ] In the bundler/bundler-site repo, copy the previous version's docs to create a new version (e.g. cp -r v1.10 v1.11)
[ ] Update the new docs as needed, paying special attention to the "What's new" page for this version
[ ] Write a blog post announcing the new version, highlighting new features and notable bugfixes
[ ] Run rake release, 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 🐠 🌴 🌊.

Breaking releases

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, but issues warnings for all options and behaviors that will change.

[coilysiren]

required background: Semantic Versioning

• minor releases start with creating a release branch (1-11-stable) from the current state of master
• from that release branch, we create the first pre-release (1.11.0.pre.1) for that minor version
• from this point, master will accept feature merges for the next minor (1.12) and regression fix merges for a patch release on the current minor (1.11)
• regression fix merge commits for the current minor are cherry-picked from master onto the minor branch (1-11-stable)
• patch releases are created from the diff (v1.11.0.pre.1...v1.11.0.pre.2) between the last release (1.11.0.pre.1), and the minor branch (1-11-stable)

---

• all releases (1.11.0.pre.1, 1.11.2) update the changelog and version files
• the changelog for the first stable minor release (1.11.0) is a sum of all the preceding pre-release versions (1.11.pre.1, 1.11.pre.2, ...) for that minor, so it is left blank unless there are fixes included since the last pre/rc release

---

• we cherry pick the merge commits dd6aef9 (git cherry-pick -m 1 MERGE_COMMIT_SHAS)
• as opposed to these ones 4fe9291

[slothelle]

I'm going to start drafting a larger piece for this using the notes from here, I'll mention y'all when I am missing some critical knowledge 🎩!

[colby-swandale]

This task seems to have been completed