Merge pull request #425 from rubygems/migrate-bundler-guides

Import bundler guides from bundler.io/guides

Author: hsbt

_data/known_plugins.yml

@@ -0,0 +1,74 @@
+---
+- name: bootboot
+  summary: Dualbooting your ruby app made easy.
+  uri: https://github.com/shopify/bootboot
+- name: bundler-as_of
+  summary: Resolve gem dependencies as-of a date in the past.
+  uri: https://github.com/flavorjones/bundler-as_of
+- name: bundler-changelogs
+  summary: A bundler plugin that shows changelogs of your gem dependencies that specify
+    changelog urls [not yet filtered to git version updates].
+  uri: https://github.com/jdar/bundler-changelogs
+- name: bundler-commentate
+  summary: Bundler plugin to add gem summaries to a Gemfile
+  uri: https://gitlab.com/fjc/bundler-commentate
+- name: bundler-console
+  summary: A bundler plugin that starts a console session with your gem dependencies.
+  uri: https://github.com/kddnewton/bundler-console
+- name: bundler-ctags_generator
+  summary: Provides a hook after gem installation to generate ctags
+  uri: https://github.com/okuramasafumi/bundler-ctags_generator
+- name: bundler-dependency_graph
+  summary: Generate a visual representation of your gem dependencies.
+  uri: https://github.com/kerrizor/bundler-dependency_graph
+- name: bundler-download
+  summary: bundler-download is a Bundler plugin for auto-downloading specified extra
+    files on `bundle install`
+  uri: http://github.com/AndyObtiva/bundler-download
+- name: bundler-ecology
+  summary: Bundler plugin to avoid installing unwanted gems
+  uri: https://github.com/eco-rb/bundler-ecology
+- name: bundler-graph
+  summary: Generates a visual dependency graph for your Gemfile
+  uri: https://github.com/rubygems/bundler-graph
+- name: bundler-inject
+  summary: A bundler plugin that allows extension of a project with personal and
+    overridden gems
+  uri: https://github.com/ManageIQ/bundler-inject
+- name: bundler-install_dash_docs
+  summary: Bundler plugin to install gem documentation into the macOS documentation
+    browser Dash https://kapeli.com/dash
+  uri: https://github.com/e28eta/bundler-install_dash_docs
+- name: bundler-licensed
+  summary: A bundler hook for https://github.com/github/licensed
+  uri: https://github.com/sergey-alekseev/bundler-licensed
+- name: bundler-mac
+  summary: exclude your bundle from Time Machine and Spotlight on macOS
+  uri: https://github.com/indirect/bundler-mac
+- name: bundler-multilock
+  summary: Support Multiple Lockfiles
+  uri: https://github.com/instructure/bundler-multilock
+- name: bundler-override
+  summary: This bundler plugin allows to change dependencies for a gem. It can be
+    helpful in situation when a developer needs to use some other dependency than
+    default for the gem.
+  uri: https://github.com/tarnowsc/bundler-override
+- name: bundler-private_install
+  summary: A Bundler plugin that installs gems in an additional private Gemfile after
+    bundle install.
+  uri: https://github.com/fphilipe/bundler-private_install
+- name: bundler-source-aws-s3
+  summary: Add aws-s3 source to bundler via plugin.
+  uri: https://github.com/eki/bundler-source-aws-s3
+- name: bundler-symlink
+  summary: Post-install hook for bundler to symlink to all gems from a local directory
+  uri: https://github.com/petekinnecom/bundler-symlink
+- name: bundler-versions_report
+  summary: At the end of `bundle update` report all updated major and minor versions
+  uri: https://github.com/igneus/bundler-versions_report
+- name: bundler-why
+  summary: Explains the presence of a dependency.
+  uri: https://github.com/jaredbeck/bundler-why
+- name: extended_bundler-errors
+  summary: Extended Errors for Bundler
+  uri: http://github.com/jules2689/extended_bundler-errors

_layouts/default.html

@@ -134,6 +134,33 @@
             </ul>
             <li><a class="nav--v__link" href="/credits">Credits</a></li>
 
+            <li class="nav--v__header"><strong>Bundler</strong></li>
+            <li><a class="nav--v__link" href="/rubygems">Bundler in gems</a></li>
+            <li><a class="nav--v__link" href="/faq">Frequently Asked Questions</a></li>
+            <li><a class="nav--v__link" href="/gemfile">Gemfiles</a></li>
+            <li><a class="nav--v__link" href="/getting_started">Getting Started</a></li>
+            <li><a class="nav--v__link" href="/bundler_2_upgrade">How to Upgrade to Bundler 2</a></li>
+            <li><a class="nav--v__link" href="/creating_gem.en">How to create a Ruby gem with Bundler</a></li>
+            <li><a class="nav--v__link" href="/deploying">How to deploy bundled applications</a></li>
+            <li><a class="nav--v__link" href="/git">How to install gems from git repositories</a></li>
+            <li><a class="nav--v__link" href="/using_bundler_in_applications.en">How to manage application dependencies with Bundler</a></li>
+            <li><a class="nav--v__link" href="/groups">How to manage groups of gems</a></li>
+            <li><a class="nav--v__link" href="/bundler_sharing">How to package and share code using a Gemfile</a></li>
+            <li><a class="nav--v__link" href="/rubygems_tls_ssl_troubleshooting_guide">How to troubleshoot RubyGems and Bundler TLS/SSL Issues</a></li>
+            <li><a class="nav--v__link" href="/updating_gems">How to update gems with Bundler</a></li>
+            <li><a class="nav--v__link" href="/bundler_in_a_single_file_ruby_script">How to use Bundler in a single-file Ruby script</a></li>
+            <li><a class="nav--v__link" href="/bundler_docker_guide">How to use Bundler with Docker</a></li>
+            <li><a class="nav--v__link" href="/rails">How to use Bundler with Rails</a></li>
+            <li><a class="nav--v__link" href="/bundler_setup">How to use Bundler with Ruby</a></li>
+            <li><a class="nav--v__link" href="/rubymotion">How to use Bundler with RubyMotion</a></li>
+            <li><a class="nav--v__link" href="/sinatra">How to use Bundler with Sinatra</a></li>
+            <li><a class="nav--v__link" href="/git_bisect">How to use git bisect with Bundler</a></li>
+            <li><a class="nav--v__link" href="/bundler_plugins">How to write a Bundler plugin</a></li>
+            <li><a class="nav--v__link" href="/bundler_known_plugins">Known Plugins</a></li>
+            <li><a class="nav--v__link" href="/bundler_workflow">Recommended Workflow with Version Control</a></li>
+            <li><a class="nav--v__link" href="/gemfile_ruby">Ruby Directive</a></li>
+            <li><a class="nav--v__link" href="/rationale">Why Bundler exists</a></li>
+
           </ul>
         </div>
         <div class="l-colspan--r">

bundler_2_upgrade.md

@@ -0,0 +1,106 @@
+---
+layout: default
+title: How to Upgrade to Bundler 2
+url: /bundler_2_upgrade
+previous: /getting_started
+next: /creating_gem.en
+---
+
+# How to Upgrade to Bundler 2
+
+So! You’ve heard that [Bundler 2 was released](https://bundler.io/blog/2019/01/03/announcing-bundler-2.html)! If you want to try out Bundler 2 for yourself, this guide will help you do that.
+
+Bundler 2 is almost entirely the same as the previous version, 1.17. The big change is that Bundler now requires at least Ruby 2.3.0 and RubyGems 2.5.0.
+
+### Prerequisites
+Before you upgrade to Bundler 2, make sure you have the right Ruby and RubyGems. You need to be using Ruby 2.3.0 or higher, and you need to have RubyGems 2.5.0 or higher.
+
+You can check your Ruby version by running `ruby --version`, and you can check your RubyGems version by running `gem --version`. If you need to upgrade Ruby, use your ruby version manager’s instructions. If you need to upgrade RubyGems, run `gem update --system`.
+
+All set? Ruby and RubyGems versions new enough? Great. Keep going.
+
+### Installing Bundler 2
+The first step in upgrading to Bundler 2 is installing the Bundler 2 gem. To install it the usual way, run `gem install bundler` and RubyGems will install the latest version of Bundler.
+
+### Version Autoswitch
+Now that you have Bundler 2 installed, you should know that Bundler will automatically switch between version 1 and version 2 based on your application’s `Gemfile.lock`. If your lockfile was created by Bundler 1, your commands will be run by Bundler 1. If your lockfile was created by Bundler 2, your commands will be run by Bundler 2.
+
+Here's an example Gemfile.lock that was created with Bundler 1.17.1.
+
+    GEM
+      remote: https://rubygems.org/
+      specs:
+        rack (2.2.4)
+
+    PLATFORMS
+      ruby
+
+    DEPENDENCIES
+      rack
+
+    BUNDLED WITH
+       1.17.1
+
+The version of Bundler in the `BUNDLED WITH` section is read by Bundler to determine which version of Bundler should run. Using the example lock above, Bundler 1 will be used, as you can see here:
+
+    $ grep -A 1 "BUNDLED WITH" Gemfile.lock
+    BUNDLED WITH
+       1.17.1
+
+    $ bundle version
+    Bundler version 1.17.1
+
+When a Gemfile has been created by Bundler 2, or manually upgraded by a developer from Bundler 1 to Bundler 2, then commands will be run by the latest installed Bundler 2. Here’s an example of what that looks like:
+
+    $ grep -A 1 "BUNDLED WITH" Gemfile.lock
+    BUNDLED WITH
+       2.0.0
+
+    $ bundle version
+    Bundler version 2.0.0
+
+When Bundler is used outside of an application, the latest version that is installed will always be used.
+
+    $ ls -a
+    .	..
+
+    $ bundle version
+    Bundler version 2.0.0
+
+### Upgrading applications from Bundler 1 to Bundler 2
+Your existing applications will continue to use Bundler 1. Bundler will never change your application to a new major version until you choose to do so. If your application is ready, you can upgrade that application to the latest installed version of Bundler by running `bundle update --bundler`.
+
+We recommend committing your Gemfile.lock before you upgrade. That way, if something goes wrong or doesn’t work, you can always revert to the previous lockfile and go back to using Bundler 1.
+
+### Using Bundler 2 with new applications
+When you create a new application, using `bundle init`, `rails new`, or something like that, your application will use the newest version of Bundler that is currently installed. If you have Bundler 2 installed, your application will be locked to Bundler 2. You can verify this by reading the lockfile, looking for the section named `BUNDLED WITH`.
+
+## FAQ
+
+### Why does Bundler have automatic version switching?
+Many Ruby developers have more than one application on their machines. If we forced all applications on one machine to use either Bundler 1 or Bundler 2 exclusively, it would cause everyone a huge amount of pain.
+
+Version switching allows everyone to have some applications use Bundler 1 while other applications can use Bundler 2, on the same machine, at the same time. Each application can be upgraded to Bundler 2 whenever it makes the most sense for that particular application to upgrade.
+
+### What happens if my application needs Bundler 2, but I only have Bundler 1 installed?
+If you try to use Bundler 1 on an application that requires Bundler 2, you’ll see an error message explaining that you need to install Bundler 2. Go ahead and run `gem install bundler`, and then it should work.
+
+### What happens if my application needs Bundler 1, but I only have Bundler 2 installed?
+If you try to use Bundler 2 on an application that needs Bundler 1, and you also don’t have Bundler 1 installed at all, you’ll see an error message asking you to install Bundler 1. Go ahead and run `gem install bundler -v "~>1.0"` to install the latest 1.x version of Bundler, and then try your command again.
+
+### Can I downgrade my application from Bundler 2 to Bundler 1?
+Bundler 2 does not provide a way to downgrade a Gemfile back to Bundler 1. Instead, we recommend checking in your `Gemfile` and `Gemfile.lock` before you upgrade your application. That way, if something goes wrong, you can revert to the previous commit and go back to using Bundler 1.
+
+### There was an issue upgrading my application to Bundler 2
+Oh no! Sorry about that. Please head over to our [troubleshooting guide](https://github.com/rubygems/rubygems/blob/master/bundler/doc/TROUBLESHOOTING.md#other-problems) and open a ticket so that we can try to fix your problem ASAP.
+
+### Will Bundler 2 have any other notable changes?
+Bundler 2 includes these changes:
+
+* Remove support for deprecated versions of Ruby (\< 2.3)
+* Remove support for deprecated versions of RubyGems (\< 2.5.0)
+* Print Bundler errors to STDERR instead of STDOUT
+* The `github:` shortcut in the `Gemfile` will use `https` instead of `http`
+
+### Can I use Bundler 2 on Heroku?
+Yes you can! The Heroku team has upgraded the official Ruby buildpack to [support Bundler 2](https://devcenter.heroku.com/articles/ruby-support#libraries). See [Heroku's article on Bundler version](https://devcenter.heroku.com/articles/bundler-version) for more details.

bundler_docker_guide.md

@@ -0,0 +1,37 @@
+---
+layout: default
+title: How to use Bundler with Docker
+url: /bundler_docker_guide
+previous: /bundler_in_a_single_file_ruby_script
+next: /rails
+---
+
+# How to use Bundler with Docker
+
+## Introduction
+
+The official Docker images for Ruby assume that you will use only one application, with one Gemfile, and no other gems or Ruby applications will be installed or run in your container.
+
+If you want to install more than one Gemfile in your container, or simply install gems via RubyGems and use them as system gems, this situation is confusing, and has historically led to many confusing errors that appear to be bugs in Bundler.
+
+However, these errors ultimately come from the way the Dockerfile tells Bundler to create [binstubs](https://bundler.io/v1.16/man/bundle-binstubs.1.html) (which are linked to one application and Gemfile) in a single global place for the entire container. If you install two Gemfiles with `rake`, for example, running the `rake` command will always load the last Gemfile that was installed, and never any others.
+
+## Dockerfiles for multiple Ruby applications and gems
+
+To build a Docker container that can run more than one Ruby application or global commands installed with `gem install`, you will need to change some environment variables from the defaults set in the official Docker image for Ruby.
+
+In your Dockerfile, change the `PATH` and `GEM_HOME` so that Bundler will install all gems to the same location, and running commands will use the RubyGems binstubs instead of Bundler's application-locked binstubs:
+
+    ENV GEM_HOME="/usr/local/bundle"
+    ENV PATH $GEM_HOME/bin:$GEM_HOME/gems/bin:$PATH
+
+You will also need to unset `BUNDLE_PATH` and `BUNDLE_BIN`. Unsetting environment variables can be somewhat tricky in Docker, but the most common way is at the beginning of your `ENTRYPOINT` script:
+
+    #!/bin/bash
+
+    unset BUNDLE_PATH
+    unset BUNDLE_BIN
+
+    # your script goes here
+
+Once you've done that, you'll be able to run commands without a bundle by calling them directly, like `rake`. You'll be able to run commands in a specific bundle by `cd`ing to that bundle's directory and then using `bundle exec`. For example, to run rake inside your application bundle, you would use `bundle exec rake`.

bundler_in_a_single_file_ruby_script.md

@@ -0,0 +1,29 @@
+---
+layout: default
+title: How to use Bundler in a single-file Ruby script
+url: /bundler_in_a_single_file_ruby_script
+previous: /updating_gems
+next: /bundler_docker_guide
+---
+
+# How to use Bundler in a single-file Ruby script
+
+To use Bundler in a single-file script, add `require 'bundler/inline'` at the top of your Ruby file. Then, use the `gemfile` method to declare any gem sources and gems that you need. Here's an example:
+
+~~~ ruby
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'json', require: false
+  gem 'nap', require: 'rest'
+  gem 'cocoapods', '~> 0.34.1'
+end
+
+puts 'Gems installed and loaded!'
+puts "The nap gem is at version #{REST::VERSION}"
+~~~
+
+To run this script, including installing any missing gems, save the script into a file (for example, `bundler_inline_example.rb`) and then run the file with the command `ruby bundler_inline_example.rb`.
+
+Running the script will automatically install any missing gems, require the gems you listed, and then run your code.

bundler_known_plugins.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Known Plugins
+url: /bundler_known_plugins
+previous: /bundler_plugins
+next: /bundler_workflow
+---
+
+Known Plugins
+=============
+
+{% for plugin in site.data.known_plugins %}
+- [{{ plugin.name }}]({{ plugin.uri }}) - {{ plugin.summary }}
+{% endfor %}