rubygems-update 3.5.6 → 3.5.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 441d0ff90372c26b0c6ecb291af1dffa910597060b81e655cd17fdd0f28f0fac
-  data.tar.gz: bd7079f9e2f60401c275254d5418986baadc1578788cfb4ed20dd9c163d00df7
+  metadata.gz: 97995bf356031d7683c1336089b3520a4604416619ce917d5efb42f628c8abc2
+  data.tar.gz: 3f66e1705ddc62583b44bebedd33089c7edbb6ba27f4ecfee984069a53f97548
 SHA512:
-  metadata.gz: 58c8b6329079a1a2b8849fd17167e31fd7bb9dc255b226489db1be189ec245b004bc49bd58e6e336608260c24e88a40003e903b35445d3b8f5bf546be2e06a92
-  data.tar.gz: a4154c7e57d48f9c88e25ef975340b49b51195455ae1548285439bc0fd776019f3c4d250f170b743cfe83ac4132b2165f39d528bbd73470c65008792ac092fea
+  metadata.gz: e92f698093d5c671bb617ecb0d5b25e3803b55f182e3cf523e4a2490278ece4a9ed0aa4d984d54ae2f0703847d2b63c50557d1fc05d84b2cd40b6d87c85fe105
+  data.tar.gz: 520eead8b68e27c40f18e54976aac985e1d52baed43b080bbb54a7ab43d6c3f936f8a0d57a0c1fe797e17bdf0a189f4d920e0876b2f938f6ebd571e391c74a28

data/CHANGELOG.md

@@ -1,3 +1,206 @@
+# 3.5.16 / 2024-07-18
+
+## Enhancements:
+
+* Installs bundler 2.5.16 as a default gem.
+
+## Bug fixes:
+
+* Fix gemspec `require_paths` validation. Pull request
+  [#7866](https://github.com/rubygems/rubygems/pull/7866) by
+  deivid-rodriguez
+* Fix loading of nested `gemrc` config keys when specified as symbols.
+  Pull request [#7851](https://github.com/rubygems/rubygems/pull/7851) by
+  moofkit
+
+## Performance:
+
+* Use `caller_locations` instead of splitting `caller`. Pull request
+  [#7708](https://github.com/rubygems/rubygems/pull/7708) by nobu
+
+# 3.5.15 / 2024-07-09
+
+## Enhancements:
+
+* Installs bundler 2.5.15 as a default gem.
+
+## Bug fixes:
+
+* Restrict generic `arm` to only match 32-bit arm. Pull request
+  [#7830](https://github.com/rubygems/rubygems/pull/7830) by ntkme
+* Protect creating binstubs with a file lock. Pull request
+  [#7806](https://github.com/rubygems/rubygems/pull/7806) by
+  deivid-rodriguez
+
+## Documentation:
+
+* Make it clearer that `add_dependency` is the main way to add
+  non-development dependencies. Pull request
+  [#7800](https://github.com/rubygems/rubygems/pull/7800) by jeromedalbert
+
+# 3.5.14 / 2024-06-21
+
+## Enhancements:
+
+* Installs bundler 2.5.14 as a default gem.
+
+## Bug fixes:
+
+* Make "bundler? update --bundler" behave identically. Pull request
+  [#7778](https://github.com/rubygems/rubygems/pull/7778) by x-yuri
+
+# 3.5.13 / 2024-06-14
+
+## Enhancements:
+
+* Installs bundler 2.5.13 as a default gem.
+
+## Bug fixes:
+
+* Never remove executables that may belong to a default gem. Pull request
+  [#7747](https://github.com/rubygems/rubygems/pull/7747) by
+  deivid-rodriguez
+
+# 3.5.12 / 2024-06-13
+
+## Enhancements:
+
+* Installs bundler 2.5.12 as a default gem.
+
+## Bug fixes:
+
+* Fix `gem uninstall` unresolved specifications warning. Pull request
+  [#7667](https://github.com/rubygems/rubygems/pull/7667) by
+  deivid-rodriguez
+* Fix `gem pristine` sometimes failing to pristine user installed gems.
+  Pull request [#7664](https://github.com/rubygems/rubygems/pull/7664) by
+  deivid-rodriguez
+
+# 3.5.11 / 2024-05-28
+
+## Enhancements:
+
+* Update SPDX license list as of 2024-05-22. Pull request
+  [#7689](https://github.com/rubygems/rubygems/pull/7689) by
+  github-actions[bot]
+* Fix the update_rubygems inconsistency (--disable-gems). Pull request
+  [#7658](https://github.com/rubygems/rubygems/pull/7658) by x-yuri
+* Accept WASI as an OS name in Gem::Platform. Pull request
+  [#7629](https://github.com/rubygems/rubygems/pull/7629) by kateinoigakukun
+* Warn if RubyGems version explicitly set in gemspec does not match
+  running version. Pull request
+  [#7460](https://github.com/rubygems/rubygems/pull/7460) by
+  deivid-rodriguez
+* Installs bundler 2.5.11 as a default gem.
+
+## Bug fixes:
+
+* Fix binstubs sometimes not getting regenerated when `--destdir` is
+  given. Pull request
+  [#7660](https://github.com/rubygems/rubygems/pull/7660) by
+  deivid-rodriguez
+* Fix `gem uninstall --user-install`  for symlinked HOME. Pull request
+  [#7645](https://github.com/rubygems/rubygems/pull/7645) by
+  deivid-rodriguez
+* Fix issue when plugin stubs would sometimes not be properly removed by
+  `gem uninstall`. Pull request
+  [#7631](https://github.com/rubygems/rubygems/pull/7631) by
+  deivid-rodriguez
+* Fix plugins uninstallation for user installed gems. Pull request
+  [#6456](https://github.com/rubygems/rubygems/pull/6456) by voxik
+
+## Performance:
+
+* Use a constant empty tar header to avoid extra allocations. Pull request
+  [#7484](https://github.com/rubygems/rubygems/pull/7484) by segiddins
+
+## Documentation:
+
+* Recommend `bin/rake` over `rake` in contributing docs. Pull request
+  [#7648](https://github.com/rubygems/rubygems/pull/7648) by
+  deivid-rodriguez
+
+# 3.5.10 / 2024-05-03
+
+## Security:
+
+* Add a limit to the size of the metadata and checksums files in a gem
+  package. Pull request
+  [#7568](https://github.com/rubygems/rubygems/pull/7568) by segiddins
+
+## Enhancements:
+
+* Don't fully require `rubygems` from `rubygems/package` to prevent some
+  circular require warnings when using Bundler. Pull request
+  [#7612](https://github.com/rubygems/rubygems/pull/7612) by
+  deivid-rodriguez
+* Installs bundler 2.5.10 as a default gem.
+
+## Bug fixes:
+
+* Rename credential email to identifier in WebAuthn poller. Pull request
+  [#7623](https://github.com/rubygems/rubygems/pull/7623) by jenshenny
+
+# 3.5.9 / 2024-04-12
+
+## Enhancements:
+
+* Installs bundler 2.5.9 as a default gem.
+
+# 3.5.8 / 2024-04-11
+
+## Security:
+
+* Respect global umask when writing regular files. Pull request
+  [#7518](https://github.com/rubygems/rubygems/pull/7518) by
+  deivid-rodriguez
+
+## Enhancements:
+
+* Allow string keys with gemrc. Pull request
+  [#7543](https://github.com/rubygems/rubygems/pull/7543) by hsbt
+* [Experimental] Add "gem rebuild" command. Pull request
+  [#4913](https://github.com/rubygems/rubygems/pull/4913) by duckinator
+* Installs bundler 2.5.8 as a default gem.
+
+## Bug fixes:
+
+* Fix NoMethodError crash when building errors about corrupt package
+  files. Pull request
+  [#7539](https://github.com/rubygems/rubygems/pull/7539) by jez
+* Fix resolver to properly intersect Arrays of `Gem::Resolver::Activation`
+  objects. Pull request
+  [#7537](https://github.com/rubygems/rubygems/pull/7537) by
+  deivid-rodriguez
+
+# 3.5.7 / 2024-03-22
+
+## Enhancements:
+
+* Warn on empty or open required_ruby_version specification attribute.
+  Pull request [#5010](https://github.com/rubygems/rubygems/pull/5010) by
+  simi
+* Control whether YAML aliases are enabled in Gem::SafeYAML.safe_load via
+  attribute. Pull request
+  [#7464](https://github.com/rubygems/rubygems/pull/7464) by segiddins
+* Update SPDX license list as of 2024-02-08. Pull request
+  [#7468](https://github.com/rubygems/rubygems/pull/7468) by
+  github-actions[bot]
+* Installs bundler 2.5.7 as a default gem.
+
+## Bug fixes:
+
+* Allow prerelease activation (even if requirement is not explicit about
+  it) when it's the only possibility. Pull request
+  [#7428](https://github.com/rubygems/rubygems/pull/7428) by kimesf
+
+## Documentation:
+
+* Fix a typo. Pull request
+  [#7505](https://github.com/rubygems/rubygems/pull/7505) by hsbt
+* Use https instead of http in documentation links. Pull request
+  [#7481](https://github.com/rubygems/rubygems/pull/7481) by hsbt
+
 # 3.5.6 / 2024-02-06
 
 ## Enhancements:
@@ -5868,7 +6071,7 @@ There has been some minor usability enhancements and changes ...
   This *greatly* speeds up gem commands run in non-admin mode when the
   site-wide cache is out of date.
 * The gem command now used an HTTP HEAD command to detect if the
-  server's source index needs to be downloaed.
+  server's source index needs to be downloaded.
 * gem check gemname --test will run unit tests on installed gems that
   have unit tests.
 * Multiple gem names are allowed on the gem install command line.

data/CODE_OF_CONDUCT.md

@@ -2,80 +2,131 @@
 
 ## Our Pledge
 
-We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
 
-We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
 
 ## Our Standards
 
-Examples of behavior that contributes to a positive environment for our community include:
+Examples of behavior that contributes to a positive environment for our
+community include:
 
 * Demonstrating empathy and kindness toward other people
 * Being respectful of differing opinions, viewpoints, and experiences
 * Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall community
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
 * Trolling, insulting or derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing others' private information, such as a physical or email address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
 
 ## Enforcement Responsibilities
 
-Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
 
-Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
 
 ## Scope
 
-This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at team@bundler.io, or directly contacting project team members via email or Slack. All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+team@bundler.io.
+All complaints will be reviewed and investigated promptly and fairly.
 
-All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
 
 ## Enforcement Guidelines
 
-Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
 
 ### 1. Correction
 
-**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
 
-**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
 
 ### 2. Warning
 
-**Community Impact**: A violation through a single incident or series of actions.
+**Community Impact**: A violation through a single incident or series of
+actions.
 
-**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
 
 ### 3. Temporary Ban
 
-**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
 
-**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
 
 ### 4. Permanent Ban
 
-**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
 
-**Consequence**: A permanent ban from any sort of public interaction within the community.
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
-available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
 
-Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
-
-[homepage]: https://www.contributor-covenant.org
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -31,7 +31,7 @@ here: https://guides.rubygems.org/contributing/
 
 ### Installing dependencies
 
-    rake setup
+    bin/rake setup
 
 > **NOTE**: If the above fails with permission related errors, you're most
 > likely using a global Ruby installation (like the one packaged by your OS),
@@ -58,7 +58,7 @@ To run commands like `bundle install` from the repo:
 
 To run the entire test suite you can use:
 
-    rake test
+    bin/rake test
 
 To run an individual test file located for example in `test/rubygems/test_deprecate.rb` you can use:
 

data/Manifest.txt

@@ -54,6 +54,7 @@ bundler/lib/bundler/compact_index_client.rb
 bundler/lib/bundler/compact_index_client/cache.rb
 bundler/lib/bundler/compact_index_client/cache_file.rb
 bundler/lib/bundler/compact_index_client/gem_parser.rb
+bundler/lib/bundler/compact_index_client/parser.rb
 bundler/lib/bundler/compact_index_client/updater.rb
 bundler/lib/bundler/constants.rb
 bundler/lib/bundler/current_ruby.rb
@@ -164,6 +165,7 @@ bundler/lib/bundler/plugin/events.rb
 bundler/lib/bundler/plugin/index.rb
 bundler/lib/bundler/plugin/installer.rb
 bundler/lib/bundler/plugin/installer/git.rb
+bundler/lib/bundler/plugin/installer/path.rb
 bundler/lib/bundler/plugin/installer/rubygems.rb
 bundler/lib/bundler/plugin/source_list.rb
 bundler/lib/bundler/process_lock.rb
@@ -383,6 +385,7 @@ lib/rubygems/commands/pristine_command.rb
 lib/rubygems/commands/push_command.rb
 lib/rubygems/commands/query_command.rb
 lib/rubygems/commands/rdoc_command.rb
+lib/rubygems/commands/rebuild_command.rb
 lib/rubygems/commands/search_command.rb
 lib/rubygems/commands/server_command.rb
 lib/rubygems/commands/setup_command.rb
@@ -424,6 +427,7 @@ lib/rubygems/gemcutter_utilities.rb
 lib/rubygems/gemcutter_utilities/webauthn_listener.rb
 lib/rubygems/gemcutter_utilities/webauthn_listener/response.rb
 lib/rubygems/gemcutter_utilities/webauthn_poller.rb
+lib/rubygems/gemspec_helpers.rb
 lib/rubygems/install_default_message.rb
 lib/rubygems/install_message.rb
 lib/rubygems/install_update_options.rb
@@ -431,9 +435,7 @@ lib/rubygems/installer.rb
 lib/rubygems/installer_uninstaller_utils.rb
 lib/rubygems/local_remote_options.rb
 lib/rubygems/name_tuple.rb
-lib/rubygems/net/http.rb
 lib/rubygems/openssl.rb
-lib/rubygems/optparse.rb
 lib/rubygems/package.rb
 lib/rubygems/package/digest_io.rb
 lib/rubygems/package/file_source.rb
@@ -514,13 +516,12 @@ lib/rubygems/source_list.rb
 lib/rubygems/spec_fetcher.rb
 lib/rubygems/specification.rb
 lib/rubygems/specification_policy.rb
+lib/rubygems/specification_record.rb
 lib/rubygems/ssl_certs/.document
 lib/rubygems/ssl_certs/rubygems.org/GlobalSignRootCA.pem
 lib/rubygems/ssl_certs/rubygems.org/GlobalSignRootCA_R3.pem
 lib/rubygems/stub_specification.rb
 lib/rubygems/text.rb
-lib/rubygems/timeout.rb
-lib/rubygems/tsort.rb
 lib/rubygems/uninstaller.rb
 lib/rubygems/unknown_command_spell_checker.rb
 lib/rubygems/update_suggestion.rb
@@ -608,6 +609,10 @@ lib/rubygems/vendor/uri/lib/uri/version.rb
 lib/rubygems/vendor/uri/lib/uri/ws.rb
 lib/rubygems/vendor/uri/lib/uri/wss.rb
 lib/rubygems/vendored_molinillo.rb
+lib/rubygems/vendored_net_http.rb
+lib/rubygems/vendored_optparse.rb
+lib/rubygems/vendored_timeout.rb
+lib/rubygems/vendored_tsort.rb
 lib/rubygems/version.rb
 lib/rubygems/version_option.rb
 lib/rubygems/yaml_serializer.rb

data/POLICIES.md

@@ -65,6 +65,59 @@ Bundler:
     have to work on weekends.
 *   Continue with the regular release process below.
 
+### Branching
+
+Bundler releases are synchronized with rubygems releases at the moment. That
+means that releases for both share the same stable branch, and they should
+generally happen together.
+
+The current conventional naming for stable branches is `x+1.y`, where `x.y` is
+the version of `bundler` that will be released. This is because `rubygems-x+1.y`
+will be released at the same time.
+
+For example, `rubygems-3.2.0` and `bundler-2.2.0` were both released from the
+`3.2` stable branch.
+
+Once a stable branch has been cut from `master`, changes for that minor release
+series are only made _intentionally_, via patch releases. That is to say,
+changes to `master` by default _won't_ make their way into the current stable
+branch, and development on `master` will be targeting the next minor
+or major release.
+
+There is a `rake prepare_release[<target_rubygems_version>]` rake task
+that helps with creating a release. It takes a single argument, the _exact
+rubygems release_ being made (e.g.  `3.2.3` when releasing bundler `2.2.3`).
+This task checks out the appropriate stable branch (`3.2`, for example), grabs
+all merged but unreleased PRs from both bundler & rubygems 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 all version files, synchronizes both changelogs 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
+```
+
+For example, for PR [#5029](https://github.com/rubygems/bundler/pull/5029), we
+cherry picked commit [dd6aef9](https://github.com/rubygems/bundler/commit/dd6aef97a5f2e7173f406267256a8c319d6134ab),
+not [4fe9291](https://github.com/rubygems/bundler/commit/4fe92919f51e3463f0aad6fa833ab68044311f03)
+using:
+
+```bash
+$ git cherry-pick -m 1 dd6aef9
+```
+
+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 release tasks
+as specified below from the updated stable branch.
+
 ### Automatic changelog and backport generation
 
 PR labels and titles are used to automatically generate changelogs for patch and
@@ -85,12 +138,28 @@ backporting a PR generates conflicts that are solved by backporting another PR
 with no user visible changes. You can use these special labels to also backport
 the other PR and not get any conflicts.
 
+### Breaking changes
+
+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 only release major breaking changes when incrementing the _major_ version of
+Bundler and RubyGems. However, experience shows that almost every single part of
+Bundler and RubyGems is depended on by someone in ways hard to anticipate. So if
+we were strict about breaking changes we'd need to hold on from making progress
+a lot, or continuously increment the major version, emptying "really major"
+versions from their meaning. Because of this, we also may release "small"
+breaking changes in minor releases. "Small" here means that we expect them to
+affect only very few users in rare cases.
+
 ### Steps for patch releases
 
 *   Confirm all PRs that you want backported are properly tagged with `rubygems:
     <type>` or `bundler: <type>` labels at GitHub.
-*   Run `rake prepare_release[<target_version>]`. This will create a PR to the
-    stable branch with the backports included in the release, and proper
+*   Run `rake prepare_release[<target_rubygems_version>]`. This will create a PR
+    to the stable branch with the backports included in the release, and proper
     changelogs and version bumps. It will also create a PR to merge release
     changelogs into master.
 *   Once CI passes, merge the release PR, switch to the stable branch and pull
@@ -102,10 +171,10 @@ the other PR and not get any conflicts.
 
 *   Confirm all PRs that you want listed in changelogs are properly tagged with
     `rubygems: <type>` or `bundler: <type>` labels at GitHub.
-*   Run `rake prepare_release[<target_version>]`. This will create a new stable
-    branch off the master branch, and create a PR to it with the proper version
-    bumps and changelogs. It will also create a PR to merge release changelogs
-    into master.
+*   Run `rake prepare_release[<target_rubygems_version>]`. This will create a
+    new stable branch off the master branch, and create a PR to it with the
+    proper version bumps and changelogs. It will also create a PR to merge
+    release changelogs into master.
 *   Replace the stable branch in the workflows with the new stable branch, and
     push that change to the release PR.
 *   Replace version numbers with the next ".dev" version, and push that change