From 4487dca5aab92508a99ffdae1cd541e1a36592aa Mon Sep 17 00:00:00 2001 From: Liz Abinante Date: Mon, 12 Dec 2016 20:54:46 -0800 Subject: [PATCH 1/2] wip - documenting release process --- RELEASING.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 RELEASING.md diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 00000000000..bdafa9ed2bf --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,107 @@ +# Releasing + +Bundler users [Semantic Versioning](http://semver.org/). + +_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 `CHANGELOG.md` and `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. + +## Workflow + +In general, `master` will accept PRs for: + +* feature merges for the next minor version (1.12) +* regression fix merges for a patch release on the current minor version (1.11) + +### 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, and issue warnings for all options and +behaviors that will change. + +### Cherry picking + +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](https://github.com/bundler/bundler/pull/5029), we +cherry picked commit [dd6aef9](https://github.com/bundler/bundler/commit/dd6aef97a5f2e7173f406267256a8c319d6134ab), +not [4fe9291](https://github.com/bundler/bundler/commit/4fe92919f51e3463f0aad6fa833ab68044311f03) +using: + +``` +$ git cherry-pick -m 1 dd6aef9 +``` + +## Releases + +### Minor 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. + +Dizzy yet? Us too. + +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 (see **Branching** below) +- [ ] Update `version.rb` to a prerelease number, e.g. `1.12.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.12.pre.2) +and repeat + +Wait! You're not done yet! After your prelease looks good: + +- [ ] Update `version.rb` to a final version (i.e. 1.12.0) +- [ ] In the [bundler/bundler-site](https://github.com/bundler/bundler-site) repo, +copy the previous version's docs to create a new version (e.g. `cp -r v1.11 v1.12`) +- [ ] 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. + +#### Branching + +Minor releases of the next version start with a new release branch from the +current state of master: `1-12-stable` + +From that release branch, we create the first pre-release branch for that minor +version: `1-12-0-pre-1`. Until `1-12-0-pre-1` is ready for release, all active +development is done in that branch. + +If `1-12-0-pre-1` is released with bugs and another prerelease version is needed, +**WAIT REALLY HOW DOES THE BRANCHING WORK HERE**????? + +### Patch releases (bug fixes!) + +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! + +PRs containing regression fixes for a patch release of the current minor version +are merged to master. These commits are then cherry-picked from master onto the +minor branch (`1-12-stable`). + +Patch releases are created from the diff between the last release (`1-12-0-pre-1`) +and the current minor branch (`1-12-stable`). + From 05819a2abd84240b58921caf7dc5aaaa49a7bb0c Mon Sep 17 00:00:00 2001 From: Samuel Giddins Date: Sat, 30 Jun 2018 20:43:34 -0700 Subject: [PATCH 2/2] Update for release automation --- RELEASING.md | 107 -------------------------- doc/development/RELEASING.md | 144 ++++++++++++++++++++++++++++++++++- 2 files changed, 141 insertions(+), 110 deletions(-) delete mode 100644 RELEASING.md diff --git a/RELEASING.md b/RELEASING.md deleted file mode 100644 index bdafa9ed2bf..00000000000 --- a/RELEASING.md +++ /dev/null @@ -1,107 +0,0 @@ -# Releasing - -Bundler users [Semantic Versioning](http://semver.org/). - -_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 `CHANGELOG.md` and `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. - -## Workflow - -In general, `master` will accept PRs for: - -* feature merges for the next minor version (1.12) -* regression fix merges for a patch release on the current minor version (1.11) - -### 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, and issue warnings for all options and -behaviors that will change. - -### Cherry picking - -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](https://github.com/bundler/bundler/pull/5029), we -cherry picked commit [dd6aef9](https://github.com/bundler/bundler/commit/dd6aef97a5f2e7173f406267256a8c319d6134ab), -not [4fe9291](https://github.com/bundler/bundler/commit/4fe92919f51e3463f0aad6fa833ab68044311f03) -using: - -``` -$ git cherry-pick -m 1 dd6aef9 -``` - -## Releases - -### Minor 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. - -Dizzy yet? Us too. - -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 (see **Branching** below) -- [ ] Update `version.rb` to a prerelease number, e.g. `1.12.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.12.pre.2) -and repeat - -Wait! You're not done yet! After your prelease looks good: - -- [ ] Update `version.rb` to a final version (i.e. 1.12.0) -- [ ] In the [bundler/bundler-site](https://github.com/bundler/bundler-site) repo, -copy the previous version's docs to create a new version (e.g. `cp -r v1.11 v1.12`) -- [ ] 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. - -#### Branching - -Minor releases of the next version start with a new release branch from the -current state of master: `1-12-stable` - -From that release branch, we create the first pre-release branch for that minor -version: `1-12-0-pre-1`. Until `1-12-0-pre-1` is ready for release, all active -development is done in that branch. - -If `1-12-0-pre-1` is released with bugs and another prerelease version is needed, -**WAIT REALLY HOW DOES THE BRANCHING WORK HERE**????? - -### Patch releases (bug fixes!) - -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! - -PRs containing regression fixes for a patch release of the current minor version -are merged to master. These commits are then cherry-picked from master onto the -minor branch (`1-12-stable`). - -Patch releases are created from the diff between the last release (`1-12-0-pre-1`) -and the current minor branch (`1-12-stable`). - diff --git a/doc/development/RELEASING.md b/doc/development/RELEASING.md index eb496470dc1..afa689eaad7 100644 --- a/doc/development/RELEASING.md +++ b/doc/development/RELEASING.md @@ -1,9 +1,147 @@ # Releasing -_Release process documentation is in progress, see [PR 5252](https://github.com/bundler/bundler/pull/5252)._ +Bundler users [Semantic Versioning](https://semver.org/). + +_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. + +## Workflow + +In general, `master` will accept PRs for: + +* feature merges for the next minor version (1.12) +* regression fix merges for a patch release on the current minor version (1.11) +* feature-flagged development for the next major version (2.0) + +### 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, 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. + +### Cherry picking + +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: + +```bash +$ git cherry-pick -m 1 MERGE_COMMIT_SHAS +``` + +For example, for PR [#5029](https://github.com/bundler/bundler/pull/5029), we +cherry picked commit [dd6aef9](https://github.com/bundler/bundler/commit/dd6aef97a5f2e7173f406267256a8c319d6134ab), +not [4fe9291](https://github.com/bundler/bundler/commit/4fe92919f51e3463f0aad6fa833ab68044311f03) +using: + +```bash +$ git cherry-pick -m 1 dd6aef9 +``` + +The `rake release:patch` command will automatically handle cherry-picking, and is further detailed below. + +## Changelog + +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 in the [bundler-changelog repo](https://github.com/bundler/bundler-changelog). +That reposity tracks changes by pull requests, with each entry having an associated version, +PR, section, author(s), issue(s) closed, and message. + +Ensure that repo has been updated with all new PRs before releasing a new version, +and copy over the new sections to the `CHANGELOG.md` in the Bundler repo. + +## Releases + +### Minor 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. + +Dizzy yet? Us too. + +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 (see **Branching** below) +* [ ] Update `version.rb` to a prerelease number, e.g. `1.12.pre.1` +* [ ] Update `CHANGELOG.md` to include all of the features, bugfixes, etc for that + version, from the [bundler-changelog](https://github.com/bundler/bundler-changelog) + repo. +* [ ] 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.12.pre.2) + and repeat, but treating `.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: + +* [ ] Update `version.rb` to a final version (i.e. 1.12.0) +* [ ] In the [bundler/bundler-site](https://github.com/bundler/bundler-site) repo, + copy the previous version's docs to create a new version (e.g. `cp -r v1.11 v1.12`) +* [ ] 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` 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. + +#### Branching + +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.0` 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. + +### Patch releases (bug fixes!) + +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 are then cherry-picked from master onto the +minor branch (`1-12-stable`). + +There is a `rake release:patch` rake task that automates creating a patch release. +It takes a single argument, the _exact_ patch release being made (e.g. `1.12.3`), +and 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 the stable branch. The task then bumps the version in the +version file, prompts you to update the `CHANGELOG.md`, then will commit those changes +and run `rake release`! ## Beta testing -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. +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](http://twitter.com/bundlerio) 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. +There may not always be prereleases or beta versions of Bundler. +The Bundler team will tweet from the [@bundlerio account](http://twitter.com/bundlerio) +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.