Merge pull request #3848 from rubygems/rubygems_changelog

Unify changelog handling for rubygems & bundler

(cherry picked from commit 5294c86)

.changelog.yml

@@ -0,0 +1,34 @@
+---
+
+header_template: "=== %new_version / %release_date"
+
+entry_template: "* %pull_request_title. Pull request #%pull_request_number by %pull_request_author"
+
+release_date_format: "%Y-%m-%-d"
+
+entry_wrapping: 74
+
+changelog_label_mapping:
+  "rubygems: security fix": "Security fixes:"
+  "rubygems: breaking change": "Breaking changes:"
+  "rubygems: major enhancement": "Major enhancements:"
+  "rubygems: deprecation": "Deprecations:"
+  "rubygems: feature": "Features:"
+  "rubygems: performance": "Performance:"
+  "rubygems: minor enhancement": "Minor enhancements:"
+  "rubygems: bug fix": "Bug fixes:"
+  "rubygems: documentation": "Documentation:"
+  "rubygems: backport": null
+
+patch_level_labels:
+  - "rubygems: security fix"
+  - "rubygems: minor enhancement"
+  - "rubygems: bug fix"
+  - "rubygems: backport"
+
+minor_level_labels:
+  - "rubygems: major enhancement"
+  - "rubygems: deprecation"
+  - "rubygems: feature"
+  - "rubygems: performance"
+  - "rubygems: documentation"

History.txt

@@ -1,5 +1,3 @@
-# coding: UTF-8
-
 === 3.2.0.rc.1 / 2020-07-04
 
 Major enhancements:

Rakefile

@@ -108,6 +108,13 @@ task :clear_package do
   rm_rf "pkg"
 end
 
+desc "Generates the changelog for a specific target version"
+task :generate_changelog, [:version] do |_t, opts|
+  require_relative "util/changelog"
+
+  Changelog.for_rubygems(opts[:version]).cut!
+end
+
 desc "Release rubygems-#{v}"
 task :release => :prerelease do
   Rake::Task["package"].invoke
@@ -271,50 +278,7 @@ namespace 'blog' do
     name  = `git config --get user.name`.strip
     email = `git config --get user.email`.strip
 
-    history = File.read 'History.txt'
-
-    history.force_encoding Encoding::UTF_8
-
-    _, change_log, = history.split %r{^===\s*\d.*}, 3
-
-    change_types = []
-
-    lines = change_log.strip.lines
-    change_log = []
-
-    while line = lines.shift do
-      case line
-      when /(^[A-Z].*)/ then
-        change_types << $1
-        change_log << "_#{$1}_\n"
-      when /^\*/ then
-        entry = [line.strip]
-
-        while /^  \S/ =~ lines.first do
-          entry << lines.shift.strip
-        end
-
-        change_log << "#{entry.join ' '}\n"
-      else
-        change_log << line
-      end
-    end
-
-    change_log = change_log.join
-
-    change_types = change_types.map do |change_type|
-      change_type.downcase.tr '^a-z ', ''
-    end
-
-    last_change_type = change_types.pop
-
-    if change_types.empty?
-      change_types = ''
-    else
-      change_types = change_types.join(', ') << ' and '
-    end
-
-    change_types << last_change_type
+    history = Changelog.for_rubygems(v.to_s)
 
     require 'tempfile'
 
@@ -327,7 +291,7 @@ author: #{name}
 author_email: #{email}
 ---
 
-RubyGems #{v} includes #{change_types}.
+RubyGems #{v} includes #{history.change_types_for_blog}.
 
 To update to the latest RubyGems you can run:
 
@@ -337,7 +301,7 @@ If you need to upgrade or downgrade please follow the [how to upgrade/downgrade
 RubyGems][upgrading] instructions.  To install RubyGems by hand see the
 [Download RubyGems][download] page.
 
-#{change_log}
+#{history.release_notes_for_blog.join("\n")}
 
 SHA256 Checksums:
 

bundler/.changelog.yml

@@ -0,0 +1,32 @@
+---
+
+header_template: "# %new_version (%release_date)"
+
+entry_template: "  - %pull_request_title [#%pull_request_number](%pull_request_url)"
+
+release_date_format: "%B %-d, %Y"
+
+changelog_label_mapping:
+  "bundler: security fix": "## Security fixes:"
+  "bundler: breaking change": "## Breaking changes:"
+  "bundler: major enhancement": "## Major enhancements:"
+  "bundler: deprecation": "## Deprecations:"
+  "bundler: feature": "## Features:"
+  "bundler: performance": "## Performance:"
+  "bundler: minor enhancement": "## Minor enhancements:"
+  "bundler: bug fix": "## Bug fixes:"
+  "bundler: documentation": "## Documentation:"
+  "bundler: backport": null
+
+patch_level_labels:
+  - "bundler: security fix"
+  - "bundler: minor enhancement"
+  - "bundler: bug fix"
+  - "bundler: backport"
+
+minor_level_labels:
+  - "bundler: major enhancement"
+  - "bundler: deprecation"
+  - "bundler: feature"
+  - "bundler: performance"
+  - "bundler: documentation"

bundler/CHANGELOG.md

@@ -1,5 +1,3 @@
-# (Unreleased)
-
 # 2.2.0.rc.1 (July 2, 2020)
 
 ## Major enhancements:
@@ -63,7 +61,7 @@
   - Fix `bundle install` unintentionally copying `with` and `without` global config to local configuration [#3666](https://github.com/rubygems/rubygems/pull/3666). This PR also address the `BUNDLE_WITH` environment variable unintentionally being persisted to configuration in a similar way ([#3708](https://github.com/rubygems/rubygems/issues/3708))
   - Fix race condition in `bundle install` that could "empty" exceptions to be raised [#3669](https://github.com/rubygems/rubygems/pull/3669)
   - Fix `--no-cache` to `bundle install` being unintentionally deprecated [#3688](https://github.com/rubygems/rubygems/pull/3688)
-  - Avoid calling `LoadError#message` to fix performance regression in future ruby 2.8 [#3762](https://github.com/rubygems/rubygems/pull/3762)
+  - Avoid calling `LoadError#message` to fix performance regression in future ruby 3.0 [#3762](https://github.com/rubygems/rubygems/pull/3762)
 
 # 2.1.4 (January 5, 2020)
 

bundler/doc/playbooks/MERGING_A_PR.md

@@ -10,8 +10,8 @@ release, make sure the following information is accurate:
 * The PR has a good descriptive title. That will be the wording for the
   corresponding changelog entry.
 
-* The PR has an accurate label. If a PR is to be included in a release, the
-  label must be one of the following:
+* The PR has an accurate label. If a PR is to be included in the changelog since
+  it has user visible changes, the label must be one of the following:
 
   * "bundler: security fix"
   * "bundler: breaking change"
@@ -23,7 +23,11 @@ release, make sure the following information is accurate:
   * "bundler: minor enhancement"
   * "bundler: bug fix"
 
-  This label will indicate the section in the changelog that the PR will take.
+  This label will indicate the section in the changelog that the PR will take,
+  and it will also be automatically used by our release tasks for backporting.
+  The labels that should be backported only to patch level releases, and to
+  either patch level or minor releases can be configured in the `.changelog.yml`
+  file.
 
   If for some reason you need a PR to be backported to a stable branch, but it
   doesn't have any user visible changes, apply the "bundler: backport" label to

bundler/doc/playbooks/RELEASING.md

@@ -29,11 +29,29 @@ behaviors that will change.
 We try very hard to only release breaking changes when incrementing the _major_
 version of Bundler.
 
-### Cherry picking
+### Patch && minor releases
 
-Patch releases are made by cherry-picking bug fixes from `master`.
+While pushing a gem version to RubyGems.org is as simple as `bin/rake release`,
+releasing a new version of Bundler includes a lot of communication: team consensus,
+git branching, documentation site updates, and a blog post.
+
+Patch and minor releases are made by cherry-picking pill requests from `master`.
 
-When we cherry-pick, we cherry-pick the merge commits using the following command:
+There is a `bin/rake release:prepare[<target_version>]` rake task that helps
+with creating a release. It takes a single argument, the _exact_ release being
+made (e.g.  `2.2.3`). This task checks out the appropriate stable branch
+(`3.2`), grabs all merged but unreleased PRs from GitHub that are compatible
+with the target release level, 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, synchronizes the changelog to include all
+backported changes and commits that change on top of the cherry-picks.
+
+Note that this task requires all user facing pull requests to be tagged with
+specific labels. See [Merging a PR](/bundler/doc/playbooks/MERGING_A_PR.md) for
+details.
+
+Also note that when this task cherry-picks, it cherry-picks the merge commits
+using the following command:
 
 ```bash
 $ git cherry-pick -m 1 MERGE_COMMIT_SHAS
@@ -48,30 +66,20 @@ using:
 $ git cherry-pick -m 1 dd6aef9
 ```
 
-The `bin/rake release:prepare_patch` command will automatically handle
-cherry-picking, and is further detailed below.
-
-## Releases
-
-### Minor releases
-
-While pushing a gem version to RubyGems.org is as simple as `bin/rake release`,
-releasing a new version of Bundler includes a lot of communication: team consensus,
-git branching, documentation site updates, and a blog post.
-
-Dizzy yet? Us too.
+After running the task, you'll 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 `bin/rake
+release` from the updated stable branch.
 
 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)
-* [ ] Create a PR to the stable branch that:
-  * [ ] Updates `version.rb` to a prerelease number, e.g. `1.12.pre.1`
-  * [ ] Updates `CHANGELOG.md` to include a release header for the new version, leaving the "(Unreleased)" section empty.
+* [ ] Run `bin/rake release:prepare[<target_pre_version>]` and create a PR to
+  the stable branch with the generated changes.
 * [ ] Get the PR reviewed, make sure CI is green, and merge it.
-* [ ] Pull the updated stable brnach, wait for CI to complete on it and get excited.
+* [ ] Pull the updated stable branch, wait for CI to complete on it and get excited.
 * [ ] Run `bin/rake release` from the updated stable branch, tweet, blog, let people know about the prerelease!
 * [ ] Wait a **minimum of 7 days**
 * [ ] If significant problems are found, increment the prerelease (i.e. 2.2.pre.2)
@@ -80,13 +88,16 @@ Here's the checklist for releasing new minor versions:
 
 Wait! You're not done yet! After your prelease looks good:
 
-* [ ] Update `version.rb` to a final version (i.e. 2.2.0)
+* [ ] Run `bin/rake release:prepare[<target_version>]` and create a PR to the
+  stable branch.
+* [ ] Get the PR reviewed, make sure CI is green, and merge it.
 * [ ] In the [rubygems/bundler-site](https://github.com/rubygems/bundler-site) repo,
   copy the previous version's docs to create a new version (e.g. `cp -r v2.1 v2.2`)
 * [ ] 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
+* [ ] Pull the updated stable branch, wait for CI to complete on it and get excited.
 * [ ] Run `bin/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
@@ -120,32 +131,6 @@ That is to say, changes to `master` by default _won't_ make their way into any
 `2.2` 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 `bin/rake release` from the appropriate 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 (`3.2`).
-
-There is a `bin/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.
-`2.2.3`), but if not given it will bump the tiny version number by one. This
-task checks out the appropriate stable branch (`3.2`), grabs all patch-level
-compatible merged but unreleased PRs from GitHub, 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, synchronizes the changelog to
-include all backported changes 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 `bin/rake release` from the updated
-stable branch.
-
 ## Beta testing
 
 Early releases require heavy testing, especially across various system setups.

bundler/spec/support/path.rb

@@ -34,7 +34,7 @@ def test_gemfile
     end
 
     def dev_gemfile
-      @dev_gemfile ||= source_root.join("dev_gems.rb")
+      @dev_gemfile ||= git_root.join("dev_gems.rb")
     end
 
     def bindir