From a35723e932760b723dd3d16d267b8f8791fbfb72 Mon Sep 17 00:00:00 2001 From: Takuya Noguchi Date: Tue, 3 Jan 2023 23:05:38 +0000 Subject: [PATCH] Rewrite updating_gems guide from HAML to Markdown Signed-off-by: Takuya Noguchi --- source/guides/updating_gems.html.haml | 117 -------------------------- source/guides/updating_gems.html.md | 105 +++++++++++++++++++++++ 2 files changed, 105 insertions(+), 117 deletions(-) delete mode 100644 source/guides/updating_gems.html.haml create mode 100644 source/guides/updating_gems.html.md diff --git a/source/guides/updating_gems.html.haml b/source/guides/updating_gems.html.haml deleted file mode 100644 index 190cff9c6b..0000000000 --- a/source/guides/updating_gems.html.haml +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: How to update gems with Bundler ---- -.container.guide - %h2 How to update gems with Bundler - .contents - .bullet - .description - %h3#updating-a-dependency - Updating a Dependency - - %p.description - Of course, at some point, you might want to update the version of a particular - dependency your application relies on. For instance, you might want to update - rails to 3.0.0 final. Importantly, just because you're - updating one dependency, it doesn't mean you want to re-resolve all of your dependencies - and use the latest version of everything. In our example, you only have three - dependencies, but even in this case, updating everything can cause complications. - - %p.description - To illustrate, the rails 3.0.0.rc gem depends on actionpack - 3.0.0.rc gem, which depends on rack ~> 1.2.1 (which means >= - 1.2.1 and < 1.3.0). The rack-cache gem depends on - rack >= 0.4. Let's assume that the rails 3.0.0 final gem also - depends on rack ~> 1.2.1, and that since the release of rails - 3.0.0, the Rack team released rack 1.2.2. - - %p.description - If we naïvely update all of our gems in order to update Rails, we'll get rack - 1.2.2, which satisfies the requirements of both rails 3.0.0 and - rack-cache. However, we didn't specifically ask to update - rack-cache, which may not be compatible with rack 1.2.2 (for - whatever reason). And while an update from rack 1.2.1 to rack - 1.2.2 probably won't break anything, similar scenarios can happen that involve - much larger jumps. (see [1] below for a larger discussion) - - %p.description - In order to avoid this problem, when you update a gem, bundler will not update a - dependency of that gem if another gem still depends on it. In this example, since - rack-cache still depends on rack, bundler will not update the - rack gem. This ensures that updating rails doesn't - inadvertently break rack-cache. Since rails 3.0.0's dependency - actionpack 3.0.0 remains compatible with rack 1.2.1, bundler - leaves it alone, and rack-cache continues to work even in the face of an - incompatibility with rack 1.2.2. - - %p.description - Since you originally declared a dependency on rails 3.0.0.rc, if you want - to update to rails 3.0.0, simply update your Gemfile to - gem 'rails', '3.0.0' and run: - - :code - $ bundle install - %p.description - As described above, the bundle install command always does a conservative - update, refusing to update gems (or their dependencies) that you have not explicitly - changed in the Gemfile. This means that if you do not modify - rack-cache in your Gemfile, bundler will treat it **and its - dependencies** (rack) as a single, unmodifiable unit. If rails - 3.0.0 was incompatible with rack-cache, bundler will report a - conflict between your snapshotted dependencies (Gemfile.lock) and your - updated Gemfile. - - %p.description - If you update your Gemfile, and your system already has all of the needed - dependencies, bundler will transparently update the Gemfile.lock when you - boot your application. For instance, if you add mysql to your - Gemfile, and have already installed it in your system, you can boot your - application without running bundle install, and bundler will persist the - "last known good" configuration to the Gemfile.lock snapshot. - - %p.description - This can come in handy when adding or updating gems with minimal dependencies (database - drivers, wirble, ruby-debug). It will probably fail if you - update gems with significant dependencies (rails), or that a lot of gems - depend on (rack). If a transparent update fails, your application will fail - to boot, and bundler will print out an error instructing you to run bundle - install. - - .bullet - .description - %h3#updating-a-gem-without-modifying-the-gemfile - Updating a Gem Without Modifying the Gemfile - - %p - Sometimes, you want to update a dependency without modifying the Gemfile. For example, - you might want to update to the latest version of rack-cache. Because you - did not declare a specific version of rack-cache in the - Gemfile, you might want to periodically get the latest version of - rack-cache. To do this, you want to use the bundle update - command: - - :code - $ bundle update rack-cache - %p - This command will update rack-cache and its dependencies to the latest - version allowed by the Gemfile (in this case, the latest version - available). It will not modify any other dependencies. - - %p - It will, however, update dependencies of other gems if necessary. For instance, if the - latest version of rack-cache specifies a dependency on rack >= - 1.2.2, bundler will update rack to 1.2.2 even though - you have not asked bundler to update rack. If bundler needs to update a - gem that another gem depends on, it will let you know after the update has completed. - - %p - If you want to update every gem in the Gemfile to the latest possible versions, run: - - :code - $ bundle update - %p - This will resolve dependencies from scratch, ignoring the Gemfile.lock. If - you do this, keep git reset --hard and your test suite in your back pocket. - Resolving all dependencies from scratch can have surprising results, especially if a - number of the third-party packages you depend on have released new versions since you - last did a full update. diff --git a/source/guides/updating_gems.html.md b/source/guides/updating_gems.html.md new file mode 100644 index 0000000000..6c20c5d731 --- /dev/null +++ b/source/guides/updating_gems.html.md @@ -0,0 +1,105 @@ +--- +title: How to update gems with Bundler +--- +## How to update gems with Bundler + +### Updating a Dependency + + +Of course, at some point, you might want to update the version of a particular +dependency your application relies on. For instance, you might want to update +`rails` to `3.0.0` final. Importantly, just because you're +updating one dependency, it doesn't mean you want to re-resolve all of your dependencies +and use the latest version of everything. In our example, you only have three +dependencies, but even in this case, updating everything can cause complications. + +To illustrate, the `rails 3.0.0.rc` gem depends on `actionpack +3.0.0.rc` gem, which depends on `rack ~> 1.2.1` (which means `>= +1.2.1` and `< 1.3.0`). The `rack-cache` gem depends on +`rack >= 0.4`. Let's assume that the `rails 3.0.0` final gem also +depends on `rack ~> 1.2.1`, and that since the release of `rails +3.0.0`, the Rack team released `rack 1.2.2`. + +If we naïvely update all of our gems in order to update Rails, we'll get `rack +1.2.2`, which satisfies the requirements of both `rails 3.0.0` and +`rack-cache`. However, we didn't specifically ask to update +`rack-cache`, which may not be compatible with `rack 1.2.2` (for +whatever reason). And while an update from `rack 1.2.1` to `rack +1.2.2` probably won't break anything, similar scenarios can happen that involve +much larger jumps. (see [1] below for a larger discussion) + +In order to avoid this problem, when you update a gem, bundler will not update a +dependency of that gem if another gem still depends on it. In this example, since +`rack-cache` still depends on `rack`, bundler will not update the +`rack` gem. This ensures that updating `rails` doesn't +inadvertently break `rack-cache`. Since `rails 3.0.0`'s dependency +`actionpack 3.0.0` remains compatible with `rack 1.2.1`, bundler +leaves it alone, and `rack-cache` continues to work even in the face of an +incompatibility with `rack 1.2.2`. + +Since you originally declared a dependency on `rails 3.0.0.rc`, if you want +to update to `rails 3.0.0`, simply update your `Gemfile` to +`gem 'rails', '3.0.0'` and run: + +~~~ +$ bundle install +~~~ + +As described above, the `bundle install` command always does a conservative +update, refusing to update gems (or their dependencies) that you have not explicitly +changed in the `Gemfile`. This means that if you do not modify +`rack-cache` in your `Gemfile`, bundler will treat it **and its +dependencies** (`rack`) as a single, unmodifiable unit. If `rails +3.0.0` was incompatible with `rack-cache`, bundler will report a +conflict between your snapshotted dependencies (`Gemfile.lock`) and your +updated `Gemfile`. + +If you update your `Gemfile`, and your system already has all of the needed +dependencies, bundler will transparently update the `Gemfile.lock` when you +boot your application. For instance, if you add `mysql` to your +`Gemfile`, and have already installed it in your system, you can boot your +application without running `bundle install`, and bundler will persist the +"last known good" configuration to the `Gemfile.lock` snapshot. + +This can come in handy when adding or updating gems with minimal dependencies (database +drivers, `wirble`, `ruby-debug`). It will probably fail if you +update gems with significant dependencies (`rails`), or that a lot of gems +depend on (`rack`). If a transparent update fails, your application will fail +to boot, and bundler will print out an error instructing you to run `bundle +install`. + +### Updating a Gem Without Modifying the Gemfile + + +Sometimes, you want to update a dependency without modifying the Gemfile. For example, +you might want to update to the latest version of `rack-cache`. Because you +did not declare a specific version of `rack-cache` in the +`Gemfile`, you might want to periodically get the latest version of +`rack-cache`. To do this, you want to use the `bundle update` +command: + +~~~ +$ bundle update rack-cache +~~~ + +This command will update `rack-cache` and its dependencies to the latest +version allowed by the `Gemfile` (in this case, the latest version +available). It will not modify any other dependencies. + +It will, however, update dependencies of other gems if necessary. For instance, if the +latest version of `rack-cache` specifies a dependency on `rack >= +1.2.2`, bundler will update `rack` to `1.2.2` even though +you have not asked bundler to update `rack`. If bundler needs to update a +gem that another gem depends on, it will let you know after the update has completed. + +If you want to update every gem in the Gemfile to the latest possible versions, run: + +~~~ +$ bundle update +~~~ + +This will resolve dependencies from scratch, ignoring the `Gemfile.lock`. If +you do this, keep `git reset --hard` and your test suite in your back pocket. +Resolving all dependencies from scratch can have surprising results, especially if a +number of the third-party packages you depend on have released new versions since you +last did a full update.