diff options
author | David RodrÃguez <deivid.rodriguez@riseup.net> | 2019-08-08 19:18:58 +0200 |
---|---|---|
committer | David RodrÃguez <deivid.rodriguez@riseup.net> | 2019-08-27 20:28:26 +0200 |
commit | 9db9403daebeae0d8866975478a6f41930fff4a2 (patch) | |
tree | 9d57b49f8517519db5f3646192f8d3e3ff24ba28 | |
parent | 8d1df7feb5f902888b9b5b1147f6b1749869619a (diff) | |
download | bundler-9db9403daebeae0d8866975478a6f41930fff4a2.tar.gz |
Changelog for 2.1.0.pre.1changelog_for_next_release
It also includes an upgrading document with some explanations about the
new deprecations and how they map to breaking changes in bundler 3.
-rw-r--r-- | CHANGELOG.md | 103 | ||||
-rw-r--r-- | UPGRADING.md | 234 |
2 files changed, 334 insertions, 3 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index 2392844047..61ad4e1d4c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,100 @@ +## 2.1.0.pre.1 + +One of the biggest changes in bundler 2.1.0 is that deprecations for upcoming +breaking changes in bundler 3 will be turned out by default. We do this to grab +feedback and comunicate early to our users to kind of changes we're intending to +make in bundler 3. See [#6965](https://github.com/bundler/bundler/pull/6965). + +Another important improvement is a better coexistence between bundler +installations and the default copy of bundler that comes with ruby installed as +a default gem. Since bundler is shipped as a default gem with ruby, a number of +users have been affected by issues where bundler ends up failing due to version +mismatches, because at some point of the execution, bundler switches to run the +default copy instead of the expected version. A number of PRs have been focused +on minimizing (hopefully eliminating) this, such as +[#7100](https://github.com/bundler/bundler/pull/7100), +[#7137](https://github.com/bundler/bundler/pull/7137), +[#6996](https://github.com/bundler/bundler/pull/6996), +[#7056](https://github.com/bundler/bundler/pull/7056), +[#7062](https://github.com/bundler/bundler/pull/7062), +[#7193](https://github.com/bundler/bundler/pull/7193), +[#7216](https://github.com/bundler/bundler/pull/7216), +[#7274](https://github.com/bundler/bundler/pull/7274) + +Deprecations: + + * See the [the upgrading document](UPGRADING.md) for a detailed explanation of + the deprecations that are getting enabled in bundler 2.1, and the future + breaking changes in bundler 3. + +Features: + + - Reimplement `config` command using subcommands ([#5981](https://github.com/bundler/bundler/pull/5981)) + - Add `bundle plugin list` command ([#6120](https://github.com/bundler/bundler/pull/6120)) + - Introduce a `bundle lock --gemfile` flag ([#6748](https://github.com/bundler/bundler/pull/6748)) + - Add local git repository source option (`--local_git`) to plugin installation ([#6749](https://github.com/bundler/bundler/pull/6749)) + - Add `quiet` flag to inline bundler ([#6828](https://github.com/bundler/bundler/pull/6828)) + - Introduce a `prefer_patch` configuration that makes `bundle update` behave like `bundle update --patch` ([#6931](https://github.com/bundler/bundler/pull/6931)) + - Introduce `Bundler.original_system` and `Bundler.original_exec` to shell out or exec to external programs using the original environment before bundler was loaded ([#7052](https://github.com/bundler/bundler/pull/7052)) + - Add feature parity to `bundle info GEM` with respect to the old deprecated command `bundle show GEM` [#7026](https://github.com/bundler/bundler/pull/7026) + - `bundle list` is introduced to list groups of gems in your Gemfile. This command was actually documented, but was just working as an alias to `bundle show` so this could also be considered a bug fix :) [#7072](https://github.com/bundler/bundler/pull/7072) + - Introduce `bundle outdated --filter-strict` as an alias to `bundle outdated --strict` [#6030](https://github.com/bundler/bundler/pull/6030) + - Add `:git` and `:branch` options to `bundle add` ([#7127](https://github.com/bundler/bundler/pull/7127)) + - Add `:ruby_26` as a valid value to the `:platform(s)` dsl ([#7155](https://github.com/bundler/bundler/pull/7155)) + - `bundle cache` now includes all features provided by `bundle package` ([#7249](https://github.com/bundler/bundler/pull/7249)) + - Several improvements on new gem templates ([#6924](https://github.com/bundler/bundler/pull/6924), [#6968](https://github.com/bundler/bundler/pull/6968), [#7209](https://github.com/bundler/bundler/pull/7209), [#7222](https://github.com/bundler/bundler/pull/7222), [#7238](https://github.com/bundler/bundler/pull/7238)) + - Add `--[no-]git` option to `bundle gem` to generate non source control gems. Useful for monorepos, for example ([#7263](https://github.com/bundler/bundler/pull/7263)) + +Bugfixes: + + - Raise when the same gem is available in multiple sources, and show a suggestion to solve it ([#5985](https://github.com/bundler/bundler/pull/5985)) + - Validate that bundler has permissions to write to the tmp directory, and raise with a meaningful error otherwise ([#5954](https://github.com/bundler/bundler/pull/5954)) + - Remove downloaded `.gem` file from the cache if it's corrupted ([#6010](https://github.com/bundler/bundler/pull/6010)) + - Fix generated README in new gems to explicitly suggest running `bundle install`, so that the outcome is independent from the major version of bundler being run ([#6068](https://github.com/bundler/bundler/pull/6068)) + - Fix `bundle outdated --group NAME` when the group is listed second in the Gemfile ([#6116](https://github.com/bundler/bundler/pull/6116)) + - Improve conflict resolution messages by not calling "ruby" a gem when conflict happens in the required_ruby_version, and by filtering out requirements that didn't contribute to the conflict ([#6647](https://github.com/bundler/bundler/pull/6647)) + - Avoid fetching and rebuilding git gems whenever any gem is changed in the Gemfile ([#6711](https://github.com/bundler/bundler/pull/6711)) + - Include the exact bundler version in the lock file in the suggested command when bundler warnings about version mismatches of itself [#6971](https://github.com/bundler/bundler/pull/6971) + - Fix plugins being installed every time a command is run #[#6978](https://github.com/bundler/bundler/pull/6978) + - Fallback to sequentially fetching specs on 429s [#6728](https://github.com/bundler/bundler/pull/6728) + - Make `bundle clean` also clean native extensions for gems with a git source [#7058](https://github.com/bundler/bundler/pull/7058) + - Fix `bundle info bundler` to show the correct path to the bundler gem [#7026](https://github.com/bundler/bundler/pull/7026) + - Fix `bundle config build.<gem>` not sending multiple parameters to `extconf.rb` correctly [#7023](https://github.com/bundler/bundler/pull/7023) + - Fix bad error message on Gemfile errors under ruby 2.7 (still unreleased, but it's a bugfix for beta testers after all) [#7038](https://github.com/bundler/bundler/pull/7038) + - Warn about situations where multiple gems provide the same executable ([#7075](https://github.com/bundler/bundler/pull/7075)) + - Ignore `frozen` setting in inline mode ([#7125](https://github.com/bundler/bundler/pull/7125)) + - Fix incorrect "bundler attempted to update GEM but version stayed the same" when updating git sourced gems ([#6325](https://github.com/bundler/bundler/pull/6325)) + - Don't check for existance of a writable home directory if `BUNDLE_USER_HOME` is set ([#6885](https://github.com/bundler/bundler/pull/6885)) + - Fix error message when server would respond to a bad username/password requiest with a 401 ([#6928](https://github.com/bundler/bundler/pull/6928)) + - Fix `bundle outdated` pluralization when multiple groups are requested ([#7063](https://github.com/bundler/bundler/pull/7063)) + - Fix `bundle install` not updating conservatively when gemspec is changed ([#7143](https://github.com/bundler/bundler/pull/7143)) + - Fix `bundle exec` not respecting custom process titles inside scripts ([#7140](https://github.com/bundler/bundler/pull/7140)) + - Fix `bundle update` message about exclude groups saying "installed" instead of "updated" ([#7150](https://github.com/bundler/bundler/pull/7150)) + - Fix `bundle licenses` not show correct information about bundler itself ([#7147](https://github.com/bundler/bundler/pull/7147)) + - Fix installation path not including ruby scope when `BUNDLE_PATH` was set ([#7163](https://github.com/bundler/bundler/pull/7163)) + - Fix `bundle clean` incorrectly removing git depedencies present in the Gemfile when rubygems 3.0+ was used and path involved a symlink ([#7211](https://github.com/bundler/bundler/pull/7211)) + - Fix platform specific gems always being re-resolved when bundler was not running under that platform ([#7212](https://github.com/bundler/bundler/pull/7212)) + - Fix `bundle package --all-platforms` causing `bundle install` to ignore `--with` and `--without` ([#6113](https://github.com/bundler/bundler/pull/6113)) + - Fix `MissingRevision` git errors to include the specific `git` command that failed under the hood ([#7225](https://github.com/bundler/bundler/pull/7225)) + - Fix using gemspec & `force_ruby_platform` on Windows ([#6809](https://github.com/bundler/bundler/pull/6809)) + - bundler's binstub checks on bundler version are now consisten with rubygems `BundlerVersionFinder` ([#7259](https://github.com/bundler/bundler/pull/7259)) + - Fix `bundle install` and `bundle update` generating different lockfiles when `path:` gems with relative paths starting with "./" were used ([#7264](https://github.com/bundler/bundler/pull/7264)) + - Give a proper error when user tries to `bundle open` a default gem ([#7288](https://github.com/bundler/bundler/pull/7288)) + - Fix `bundle doctor` command ([#7309](https://github.com/bundler/bundler/pull/7309)) + - Fix bundler giving an unclear recommendation when duplicated gems are found in the Gemfile ([#7302](https://github.com/bundler/bundler/pull/7302)) + +Documentation: + + - Fix typo on a file extension in `bundle.ronn` [#7146](https://github.com/bundler/bundler/pull/7146) + - Fix incorrect default value for `cache_path` configuration ([#7229](https://github.com/bundler/bundler/pull/7229)) + - Binstubs documentation has been improved ([#5889](https://github.com/bundler/bundler/pull/5889)) + - Fix incorrect sections when explaining `:git`, `:branch`, and `:ref` options ([#7265](https://github.com/bundler/bundler/pull/7265)) + - Fix mentions to remembered options in docs to explain the current state ([#7242](https://github.com/bundler/bundler/pull/7242)) + +Internally, there's also been a bunch of improvements in our development +environment, test suite, policies, contributing docs, and a bunch of cleanups of +old compatibility code. + ## 2.0.2 (2019-06-13) Changes: @@ -63,8 +160,8 @@ Note: To upgrade your Gemfile to Bundler 2 you will need to run `bundle update - Breaking Changes: - - Dropped support for versions of Ruby < 2.3 - - Dropped support for version of RubyGems < 2.5 + - Dropped support for versions of Ruby under 2.3 + - Dropped support for version of RubyGems under 2.5 - Moved error messages from STDOUT to STDERR Note: To upgrade your Gemfile to Bundler 2 you will need to run `bundle update --bundler` @@ -2812,7 +2909,7 @@ isolation. - Fixes an obscure bug where switching the source of a gem could fail to correctly change the source of its dependencies - Support multiple version dependencies in the Gemfile - (gem "rails", ">= 3.0.0.beta1", "<= 3.0.0") + (`gem "rails", ">= 3.0.0.beta1", "<= 3.0.0"`) - Raise an exception for ambiguous uses of multiple declarations of the same gem (for instance, with different versions or sources). - Fix cases where the same dependency appeared several times in the Gemfile.lock diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 0000000000..4a7e5c55e7 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,234 @@ +# Upgrading + +## Bundler 3 + +The following is a summary of the changes that we plan to introduce in Bundler +3, why we will be making those changes, and what the deprecation process will +look like. All these deprecations will be printed by default in the upcoming +Bundler 2.1 release. + +If you don't want to deal with deprecations right now and want to toggle them +off, you can do it through configuration. Set the `BUNDLE_SILENCE_DEPRECATIONS` +environment variable to "true", or configure it through `bundle config` either +globally through `bundle config set silence_deprecations true` command, or +locally through `bundle config set --local silence_deprecations true`. From now +on in this document we will assume that all three of these configuration options +are available, but will only mention `bundle config set <option> <value>`. + +As a general note, these changes are intended to improve the experience using +bundler for _new_ users, who have no existing usage routines nor possibly biased +opinions about how the tool should work based on how it has historically worked. +We do understand that changing behaviour that have been existing for years can +be annoying for old users, that's why we intend to make this process as smooth +as possible for everyone. + +I'll be dividing the deprecations into three groups: CLI deprecations, DSL +deprecations, and misc deprecations. Let's dive into each of them. + +#### CLI deprecations + +The CLI defines a set of commands and options that can be used by our users to +create command lines that bundler can understand. There's a number of changes +that we plan to make to this set of commands and options. + +* Flags passed to `bundle install` that relied on being remembered across invokations have been deprecated. + + In particular, the `--clean`, `--deployment`, `--frozen`, `--no-cache`, + `--no-prune`, `--path`, `--shebang`, `--system`, `--without`, and `--with` + options to `bundle install`. + + Remembering CLI options has been a source of historical confusion and bug + reports, not only for beginners but also for experienced users. A CLI tool + should not behave differently accross exactly the same invokations _unless_ + explicitly configured to do so. This is what configuration is about after all, + and things should never be silently configured without the user knowing about + it. + + The problem with changing this behavior is that very common workflows are + relying on it. For example, when you run `bundle install --without + development:test` in production, those flags are persisted in the app's + configuration file and further `bundle` invokations will happily ignore + development and test gems. This magic will disappear from bundler 3, and + you will explicitly need to configure it, either through environment + variables, application configuration, or machine configuration. For example, + with `bundle config set without development test`. + +* The `--force` flag to `bundle install` and `bundle update` has been renamed to `--redownload`. + + This is just a simple renaming of the flag, to make more apparent what it + actually does. This flag forces redownloading every gem, it doesn't "force" + anything else. + +* `bundle viz` will be removed and extracted to a plugin. + + This is the only bundler command requiring external dependencies, both an OS + dependency (the `graphviz` package) a gem dependency (the `ruby-graphviz` + gem). Removing these dependencies will make development easier and it was also + seen by the bundler team as an opportunity to develop a [bundler plugin] that + it's officially maintained by the bundler team, and that users can take as a + reference to develop their own plugins. The plugin contains the same code as + the old core command, the only difference being that the command is now + implemented as `bundle graph` which is much easier to understand. Have a look + at https://github.com/bundler/bundle-viz for more information about how to + install and use the new plugin. + +* The `bundle console` will be removed and replaced with `bin/console`. + + Over time we found `bundle console` hard to maintain because every user would + want to add her own specific tweaks to it. In order to ease maintainance and + reduce bikeshedding discussions, we're removing the `bundle console` command + in favor of a `bin/console` script created by `bundle gem` on gem generation + that users can tweak to their needs. + + [NOTE: Should we provide an easy way to add `bin/console` to an existing gem?] + +* The `bundle update` command will no longer update all gems, you'll need to pass `--all` to it. + + [NOTE: I'm not elaborating on this change yet because I have hesitations about + it which I've mentioned in https://github.com/bundler/bundler/pull/7008. After + reading up on it a bit more and seeing that it all starts with "many people + think that they should run bundle update after git pull", I wonder even more. + Why is this? Isn't this a documentation issue that shouldn't make us change + bundler?] + +* The `bundle install` command will no longer accept a `--binstubs` flag. + + [NOTE: I'm not sure if I got the rationale for this one right, and I couln't + find any related Github discussion other than an upgrading document in the + 2-0-stable flag that mentions it. Please double check this] + + The `--binstubs` option has been removed from `bundle install` and replaced + with the `bundle binstubs` command. The `--binstubs` flag would create + binstubs for all executables present inside the gems in the project. This was + hardly useful since most users will only use a subset of all the binstubs + available to them. Also, it would force the introduction of a bunch of most + likely unused files into source control. Because of this, binstubs now must + must be created and checked into version control individually. + +* The `bundle config` command has a new subcommand-based interface. + + We believe the old interface where the kind of operation was guessed from the + combination of flags and number of arguments being passed to the command was + confusing. Instead we have introduced a compulsory subcommand argument that + can be either `list`, `get`, `set` or `unset`. We believe this will make the + `config` command much easier to interact with. The old interface is + deprecated, but we are giving suggestions about the new commands that should + be used along with the deprecation messages. + +* The `bundle inject` command is deprecated and replaced with `bundle add`. + + We believe the new command fits the user's mental model better and it supports + a wider set of use cases. The interface supported by `bundle inject` works + exactly the same in `bundle add`, so it should be easy to migrate to the new + command. + +#### Helper deprecations + +* `Bundler.clean_env`, `Bundler.with_clean_env`, `Bundler.clean_system`, and `Bundler.clean_exec` are deprecated. + + All of these helpers ultimately use `Bundler.clean_env` under the hood, which + makes sure all bundler-related environment are removed inside the block it + yields. + + After quite a lot user reports, we noticed that users don't usually want this + but instead want the bundler environment as it was before the current process + was started. Thus, `Bundler.with_original_env`, `Bundler.original_system`, and + `Bundler.original_exec` were born. They all use the new `Bundler.original_env` + under the hood. + + There's however some specific cases where the good old `Bundler.clean_env` + behavior can be useful. For example, when testing Rails generators, you really + want an environment where `bundler` is out of the picture. This is why we + decided to keep the old behavior under a new more clear name, because we + figured the word "clean" was too ambiguous. So we have introduced + `Bundler.unbundled_env`, `Bundler.with_unbundled_env`, + `Bundler.unbundled_system`, and `Bundler.unbundled_exec`. + +* `Bundler.environment` is deprecated in favor of `Bundler.load`. + + We're not sure how people might be using this directly but we have removed the + `Bundler::Environment` class which was instantiated by `Bundler.environment` + since we realized the `Bundler::Runtime` class was the same thing. During the + transition `Bundler.environment` will delegate to `Bundler.load`, which holds + the reference to the `Bundler::Environment`. + +#### DSL deprecations + +The following deprecations in bundler's DSL are meant to prepare for the strict +source pinning in bundler 3, where the source for every dependency will be +unambiguously defined. + +* Multiple global Gemfile sources will no longer be supported. + + Instead of something like this: + + ```ruby + source "https://main_source" + source "https://another_source" + + gem "dependency1" + gem "dependency2" + ``` + + do something like this: + + ```ruby + source "https://main_source" + + gem "dependency1" + + source "https://another_source" do + gem "dependency2" + end + ``` + +* Global `path` and `git` sources will no longer be supported. + + Instead of something like this: + + ```ruby + path "/my/path/with/gems" + git "https://my_git_repo_with_gems" + + gem "dependency1" + gem "dependency2" + ``` + + do something like this: + + ```ruby + gem "dependency1", path: "/my/path/with/gems" + gem "dependency2", git: "https://my_git_repo_with_gems" + ``` + + or use the block forms: + + ```ruby + path "/my/path/with/gems" do + # gem "dependency1" + # ... + # gem "dependencyn" + end + + git "https://my_git_repo_with_gems" do + # gem "dependency1" + # ... + # gem "dependencyn" + end + ``` + + if you have multiple gems for each source and you want to be a bit DRYer. + +#### Misc deprecations + +* Deployment helpers for `vlad` and `capistrano` are being removed. + + These are natural deprecations since the `vlad` tool has had no activity for + years whereas `capistrano` 3 has built-in Bundler integration in the form of + the `capistrano-bundler` gem, and everyone using Capistrano 3 should be + already using that instead. If for some reason, you are still using Capistrano + 2, feel free to copy the Capistrano tasks out of the Bundler 2 file + `bundler/deployment.rb` and put them into your app. + + In general, we don't want to maintain integrations for every deployment system + out there, so that's why we are removing these. |