Make guides completely version independent

[tnir]

From #625 (review):

@deivid-rodriguez:

Make guides completely version independent. If the only difference between them is usage of modern hashes, I think we can add a note at the beginning that the guide does not work on old Rubies due to this, and that users of these Rubies should upgrade. From now on, if we introduced something version dependent to any guide, we can add a note about the version where the feature described was first introduced.

---

How different between 1.16 and the current (2.3)

(cd source/v1.16/guides; find . -type f) | sed 's/^.\///' | xargs -I {} diff -0 -u source/v{1.16,2.3}/guides/{}

--- source/v1.16/guides/bundler_plugins.html.haml       2022-07-08 07:52:54.000000000 +0000
+++ source/v2.3/guides/bundler_plugins.html.haml        2022-07-08 07:52:54.000000000 +0000
@@ -60 +60 @@
-        Plugins can be installed from RubyGems (default) or from a Git server. To use a gem on your machine, you can run <code>bundler plugin install <gem_name></code>. Once the plugin is installed, the commands will be available for use and the hooks will be automatically registered with Bundler.
+        Plugins can be installed from RubyGems (default) or from a Git server. To use a gem on your machine, you can run <code>bundler plugin install gem_name</code>. Once the plugin is installed, the commands will be available for use and the hooks will be automatically registered with Bundler.
@@ -64,0 +65,3 @@
+      %p
+        In Bundler 2.2.0, you can uninstall with <code>bundler plugin uninstall gem_name</code>.
+
@@ -124,0 +128,4 @@
+            if args.empty?
+              # Using BundlerError in plugins is recommended. See below.
+              raise BundlerError, 'My plugin requires arguments'
+            end
@@ -149,0 +157,7 @@
+
+      %h4#raising_errors
+        Raising Errors
+      %p
+        If something goes wrong, your plugins should raise a `BundlerError`. It's not recommended to raise e.g. `Exception` in a plugin, because that will cause Bundler to print its own bug report template, asking users to report the bug to Bundler itself.
+      %p
+        To see in detail how bundler rescues errors, check out `bundler/friendly_errors.rb`.
--- source/v1.16/guides/bundler_setup.html.haml 2022-07-08 07:52:54.000000000 +0000
+++ source/v2.3/guides/bundler_setup.html.haml  2022-07-08 07:52:54.000000000 +0000
@@ -62 +62 @@
-        This will automatically discover your <code>Gemfile</code>, and make all of the gems in
+        This will automatically discover your <code>Gemfile</code> and make all of the gems in
@@ -64 +64 @@
-        load path"). You can think of it as an adding some extra powers to <code>require
+        load path"). You can think of it as adding some extra powers to <code>require
--- source/v1.16/guides/bundler_sharing.html.haml       2022-07-08 07:52:54.000000000 +0000
+++ source/v2.3/guides/bundler_sharing.html.haml        2022-07-08 07:52:54.000000000 +0000
@@ -31 +31 @@
-        that it already has all of the dependencies you need, and skip the installation process.
+        that it already has all of the dependencies you need and skip the installation process.
@@ -34,2 +34,2 @@
-        Do not check in the <code>.bundle</code> directory, or any of the files inside it. Those
-        files are specific to each particular machine, and are used to persist installation options
+        Do not check in the <code>.bundle</code> directory or any of the files inside it. Those
+        files are specific to each particular machine and are used to persist installation options
@@ -43 +43 @@
-        step, and not recommended, due to the increase in size of your source control repository.
+        step and not recommended due to the increase in size of your source control repository.
@@ -61,3 +61,3 @@
-        1.2.1</code>. Even if the Rack team releases <code>rack 1.2.2</code>, bundler will
-        always install <code>1.2.1</code>, the exact version of the gem that we know works. This
-        relieves a large maintenance burden from application developers, because all machines
+        1.5.2</code>. Even if the Rack team releases <code>rack 1.5.3</code>, bundler will
+        always install <code>1.5.2</code>, the exact version of the gem that we know works. This
+        relieves a large maintenance burden from application developers because all machines
--- source/v1.16/guides/faq.html.haml   2022-07-08 07:52:54.000000000 +0000
+++ source/v2.3/guides/faq.html.haml    2022-07-08 07:52:54.000000000 +0000
@@ -178 +178,18 @@
-          Committing lockfiles in libraries
+          Using Gemfiles inside gems
+
+        %p
+          <strong>Q</strong>: What happens if I put a `Gemfile` in my gem?
+
+        %p
+          <strong>A</strong>: When someone installs your gem, the `Gemfile` and
+          `Gemfile.lock` files are completely ignored, even if you include them
+          inside the `.gem` file you upload to rubygems.org.
+
+          The `Gemfile` inside your gem is only to make it easy for developers
+          (like you) to install the dependencies needed to do development work
+          on your gem. The `Gemfile` also provides an easy way to track and
+          install development-only or test-only gems.
+
+          Read about Gemfiles in gems from the <a href="../rubygems.html">
+          Bundler in gems</a> page and the <a href="./creating_gem.html">
+          How to create a gem with Bundler</a> guide.
@@ -184,9 +201,33 @@
-          <strong>A</strong>: Yes. When Bundler first shipped, the
-          `Gemfile.lock` was gitignored inside gems.  Over time, however, it
-          became clear that this practice forces the pain of broken dependencies
-          onto new contributors, while leaving existing contributors potentially
-          unaware of the problem. Since `bundle install` is usually the first
-          step towards a contribution, the pain of broken dependencies would
-          discourage new contributors from contributing. As a result, we have
-          revised our guidance for gem authors to now recommend checking in the
-          lock for gems.
+          <strong>A</strong>: Yes, you should commit it. The presence of a
+          `Gemfile.lock` in a gem's repository ensures that a fresh checkout of
+          the repository uses the exact same set of dependencies every time. We
+          believe this makes repositories more friendly towards new and
+          existing contributors.
+
+          Ideally, anyone should be able to clone the repo, run `bundle
+          install`, and have passing tests. If you don't check in your
+          `Gemfile.lock`, new contributors can get different versions of your
+          dependencies, and run into failing tests that they don't know how to
+          fix.
+
+        %p
+          <strong>Q</strong>: But I have read that gems should not check in the
+          Gemfile.lock!
+
+        %p
+          <strong>A</strong>: The main advantage of not checking in your
+          Gemfile.lock is that new checkouts (including CI) will immediately
+          have failing tests if one of your dependencies changes in a breaking
+          way.
+
+          Instead of forcing every fresh checkout (and possible new
+          contributor) to encounter broken builds, the Bundler team recommends
+          either using a tool like <a href="https://dependabot.com">Dependabot
+          </a> to automatically create a PR and run the test suite any time
+          your dependencies release new versions.
+
+          If you don't want to use a dependency monitoring bot, we suggest
+          creating an additional daily CI build that deletes the Gemfile.lock
+          before running `bundle install`. That way you, and others monitoring
+          your CI status, will be the first to know about any failures from
+          dependency changes.
--- source/v1.16/guides/git.html.haml   2022-07-08 07:52:54.000000000 +0000
+++ source/v2.3/guides/git.html.haml    2022-07-08 07:52:54.000000000 +0000
@@ -69,3 +69,3 @@
-        gem 'nokogiri', git: 'https://github.com/rack/rack.git', ref: '0bd839d'
-        gem 'nokogiri', git: 'https://github.com/rack/rack.git', tag: '2.0.1'
-        gem 'nokogiri', git: 'https://github.com/rack/rack.git', branch: 'rack-1.5'
+        gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', ref: '0bd839d'
+        gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', tag: '2.0.1'
+        gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', branch: 'rack-1.5'
@@ -114 +113,0 @@
-        gem 'capistrano-sidekiq', github: 'seuros/capistrano-sidekiq'
@@ -115,0 +115 @@
+        gem 'my_gist', gist: '4815162342'
@@ -151 +151 @@
-        $ bundle config local.GEM_NAME /path/to/local/git/repository
+        $ bundle config set local.GEM_NAME /path/to/local/git/repository
@@ -156 +156 @@
-        $ bundle config local.rack ~/Work/git/rack
+        $ bundle config set local.rack ~/Work/git/rack
@@ -174,0 +175 @@
+          <strong>Please note!</strong>
@@ -176,2 +177,2 @@
-          invalid references. Particularly, we force a developer to specify
-          a branch in the <code>Gemfile</code> in order to use this feature. If the branch
+          invalid references. Particularly, <strong>we force a developer to specify
+          a branch in the <code>Gemfile</code> in order to use this feature</strong>. If the branch
@@ -192 +193 @@
-        $ bundle config disable_local_branch_check true
+        $ bundle config set disable_local_branch_check true
--- source/v1.16/guides/groups.html.haml        2022-07-08 07:52:54.000000000 +0000
+++ source/v2.3/guides/groups.html.haml 2022-07-08 07:52:54.000000000 +0000
@@ -34,3 +34,5 @@
-        Install all gems, except those in the
-        listed groups. Gems in at least one
-        non-excluded group will still be installed.
+        Configure bundler so that subsequent
+        `bundle install` invokations will install
+        all gems, except those in the listed
+        groups. Gems in at least one non-excluded
+        group will still be installed.
@@ -38 +40 @@
-        $ bundle install --without test development
+        $ bundle config set --local without test development
@@ -59 +61,10 @@
-        in these groups will be require'able
+        in these groups will be require'able.
+        Note though that `Bundler.setup` can be
+        called only once, all subsequent calls are
+        no-op. In particular, since running a
+        script through `bundle exec` already calls
+        `Bundler.setup`, any later calls inside
+        your user code will be ignored. In order to
+        control the groups that are loaded by
+        `bundle exec` you can use the `BUNDLE_WITH`
+        and `BUNDLE_WITHOUT` configurations.
@@ -70 +81 @@
-      Optional groups and <code>--with</code>
+      Optional groups and <code>BUNDLE_WITH</code>
@@ -73,2 +84,2 @@
-      Mark a group as optional using <code>group :name, optional: true do</code>, and then opt
-      into installing an optional group with <code>bundle install --with name</code>.
+      Mark a group as optional using <code>group :name, optional: true do</code> and then opt
+      into installing an optional group with <code>bundle config set --local with name</code>.
@@ -81 +92 @@
-        For instance, you might develop your app (at an early stage) using SQLite, but deploy it
+        For instance, you might develop your app (at an early stage) using SQLite but deploy it
@@ -83 +94 @@
-        or Postgres installed on your development machine, and want bundler to skip it.
+        or Postgres installed on your development machine and want bundler to skip it.
@@ -107 +118 @@
-        $ bundle install --without production
+        $ bundle config set --local without production
@@ -110,7 +121,8 @@
-        Bundler will remember that you installed the gems using <code>--without
-        production</code>. For curious readers, bundler stores the flag in
-        <code>APP_ROOT/.bundle/config</code>. You can see all of the settings that bundler saved
-        there by running <code>bundle config</code>, which will also print out global settings
-        (stored in <code>~/.bundle/config</code>), and settings set via environment variables.
-        For more information on configuring bundler, please see:
-        #{link_to_documentation "bundle_config"}
+        Bundler stores the flag in <code>APP_ROOT/.bundle/config</code> and the
+        next time you run `bundle install`, it will skip production gems.
+        Similarly, when you require `bundler/setup`, Bundler will ignore gems in
+        these groups. You can see all of the settings that Bundler saved there
+        by running <code>bundle config</code>, which will also print out global
+        settings (stored in <code>~/.bundle/config</code>) and settings set via
+        environment variables.  For more information on configuring Bundler,
+        please see: #{link_to_documentation "bundle_config"}
@@ -120,6 +131,0 @@
-        If you run <code>bundle install</code> later, without any flags, bundler will remember
-        that you last called <code>bundle install --without production</code>, and use that flag
-        again. When you <code>require 'bundler/setup'</code>, bundler will ignore gems in these
-        groups.
-
-      %p.description
@@ -129 +135 @@
-        bundler will <code>require</code> all the gems in the <code>:default</code> group, as
+        bundler will <code>require</code> all the gems in the <code>:default</code> group as
@@ -136 +142 @@
-        Rails environment), you can add them to the call to <code>Bundler.require</code>, if you
+        Rails environment), you can add them to the call to <code>Bundler.require</code> if you
@@ -140 +146 @@
-        Remember that you can always leave groups of gems out of <code>Bundler.require</code>,
+        Remember that you can always leave groups of gems out of <code>Bundler.require</code>
@@ -142 +148 @@
-        place in your app. You might do this because requiring a certain gem takes some time,
+        place in your app. You might do this because requiring a certain gem takes some time
--- source/v1.16/guides/rubygems_tls_ssl_troubleshooting_guide.html.md  2022-07-08 07:52:54.000000000 +0000
+++ source/v2.3/guides/rubygems_tls_ssl_troubleshooting_guide.html.md   2022-07-08 07:52:54.000000000 +0000
@@ -40 +40 @@
-      - [Debian or Ubuntu: Installed with `apt-get`][installed-with-apt-get]
+      - [Debian or Ubuntu 16.04: Installed with `apt-get`][installed-with-apt-get]
@@ -172 +172 @@
-First, [run this script](https://github.com/indirect/ruby-ssl-check/blob/master/check.rb) to
+First, [run this script](https://github.com/rubygems/ruby-ssl-check/blob/master/check.rb) to
@@ -175 +175 @@
-You can run the script immediately with this command:
+You can run the script immediately with this command (Windows 10 also):
@@ -177 +177 @@
-```$ ruby -ropen-uri -e 'eval open("https://git.io/vQhWq").read'```
+```$ curl -Lks 'https://git.io/rg-ssl' | ruby```
@@ -216 +216 @@
-If your system clock is set to a time in the past or future, your machine will not be able to establish a secure connection to RubyGems.org. To resolve the issue, you will need to set your system clock to the current time. In Linux, you can update the system c
lock by running `sudo ntpdate ntp.ubuntu.com`.
+If your system clock is set to a time in the past or future, your machine will not be able to establish a secure connection to RubyGems.org. To resolve the issue, you will need to set your system clock to the current time. In Linux, you can update the system c
lock by running `sudo ntpdate ntp.ubuntu.com`. 
@@ -290,2 +290,3 @@
-In the window, open the `ssl_certs` directory and drag your `.pem`
-file into it. It will be listed with other files like `AddTrustExternalCARoot.pem`.
+In the window, open the `ssl_certs` directory. Find other `.pem` files like
+`AddTrustExternalCARoot.pem` (may be located in subdirectories like `rubygems.org`)
+and drag your file beside them.
@@ -374 +375 @@
-#### Debian or Ubuntu: Installed with `apt-get`
+#### Debian or Ubuntu 16.04: Installed with `apt-get`
@@ -430 +431 @@
-(Create an issue in the [RubyGems issue tracker](https://github.com/rubygems/rubygems/issues/new?labels=Rubygems&template=rubygems-related-issue.md)
+(Create an issue in the [RubyGems issue tracker](https://github.com/rubygems/rubygems/issues)
@@ -432 +433 @@
-the [Bundler issue tracker](https://github.com/rubygems/rubygems/issues/new?labels=Bundler&template=bundler-related-issue.md).)
+the [Bundler issue tracker](https://github.com/bundler/bundler).)