Documentation hierarchy with a sidebar for moving around — the current documentation means you get stuck in a mire after a couple of clicks.

Initial ideas for doc hierarchy:

• Get started
  • What does Bundler do?
  • Why do I care?
  • How do I use it?
• Commands
  • Install
  • Update
  • Config
  • Etc. …
• Learn more
  • Gemfile
  • Ruby version
  • Groups
  • Bundler.setup
  • Executables
  • Packing
  • Deployment
  • Standalone
  • Etc. …
• Use Bundler with
  • Rails (with a link link to the Rails 2.3 page from there)
  • Sinatra
  • Rubygems
  • RubyMotion

http://bundler.io/v1.3/index.html linked from the top menu says "Page not found".

Looks like https://github.com/bundler/bundler-site/tree/master/source/v1.3 is missing index.haml.

When I went to Japan, a lot of people I talked to were surprised to learn that the --full-index option exists, which downloads the entire rubygems index at once instead of making a lot of small requests. Because Japan is so far away from the rubygems server, this option made their installs much faster when they used it. I'd like to mention it on the FAQ page so that people will at least hopefully know that it is an option.

Tutorials: how to do a thing, like “create a gem with bundler”, or “work on an application and a gem it depends on at the same time”.

Guides: single topic deep dives, like “everything about git gems”, or “everything about gemfiles”.

Reference: exhaustive command reference, like “the bundle install command and every single flag and config option that impacts it”.

Help: how to get help and how to give help, so it should cover the ISSUES, CONTRIBUTING.md, and DEVELOPMENT.md files at least.

http://bundler.io/compatibility.html

Needs info for:

• Ruby 2.1
• Rubygems 2.1 and 2.2
• incompatible versions of 1.8 (see rubygems/bundler#2793)

The site should be able to build a perfectly reasonable issue-reporting page by inserting the issues.md file from the master branch into the site layout. Make sure that the build and/or release tasks update this so it's automatically in sync with the master branch on each deploy.

@neoeno did a great job inspecting the --source option and explained it in this issue rubygems/bundler#3759.

Wether this functionality will be renamed in the future or not, this knowledge should be shared on the website.

Site on which the --source option is mentioned: http://bundler.io/v1.10/bundle_update.html

Source file to be updated: https://github.com/bundler/bundler-site/blob/master/source/v1.10/bundle_update.haml

@indirect do you agree?

Hi there.
I noticed an strange (kinda unnecessary) margin-top in the .license class in http://bundler.io/conduct.html.

Scroll down to the License h3 element and inspect element.
There is a gap between the h3 and the p (which has the license class) caused by the margin-top in the license class.
See here: https://github.com/bundler/bundler-site/blob/master/source/stylesheets/application.scss#L499-L500

Is that meant to be like that? Not sure if it is some weird requirement for License sections.

If that is not, I can send the PR (https://github.com/heliocola/bundler-site/commit/1481f3caddd18416ca15a4180210aa949ad78cdf).

Add a footer that contains all the links. Maybe In organized columns?

Turns out the man pages are significantly different between 1.0 and 1.1, but right now there's only one set of man pages shared by both 1.0 and 1.1. We should "version" the man pages by dropping them into /v1.0/man and /v1.1/man, and then tweak the rake task to generate the man pages for each version from the 1-0-stable and 1-1-stable branches of the main bundler repository, respectively.

This can probably be deleted or just included in the other issue:
Generate pages for each command from the manpages

http://bundler.io/v1.3/bundle_install.html#no-cache

Add Examples for each of these:

• Example with --binstubs
• Example with --clean
• Example with --frozen
• Example with --full-index
• Example with --gemfile
• Example with --local
• Example with --no-cache
• Example with --no-prune
• Example with --quiet
• Example with --shebang
• Example with --standalone
• Example with --system

http://bundler.io/v1.3/bundle_open.html

• bundle open Detailed description
• bundleopen Example with default options

A few things that may not be obvious are needed for git bisect to work in a project that uses Bundler:

1. The Gemfile.lock needs to be in the git repo, so that each commit will load the same dependencies every time.
2. Each step during the bisect needs to run bundle install first, so that the correct dependencies are installed and available to be loaded.
3. After determining if the commit is good or bad, each step needs to git reset. If bundle install or running the test can cause changes on the file system, which would prevent git checkout of the next commit to test if they are not reset.

Here's a minimal example script that runs the rake task spec:

#!/bin/bash
bundle install
bin/rake spec
status=$?
git reset --hard HEAD
exit $status

See also the discussion at rubygems/bundler#3726.

The Google group would be easier to find if it was mentioned on the gembundler.com site.

Originally reported in: rubygems/bundler#1023

Completely agree with this. Too many issues are open on the Bundler issue tracker that should be discussions in the mailing list.

Right now there are separate docsite pages and man pages for each command. We should generate the docsite pages from the man pages (custom ronn template maybe?) and migrate the content that isn't in the man pages into them.

The titles are a bit misleading. The content doesn't actually go over why bundler exists but gives a brief overview of its functionality.

Hi,
At http://bundler.io/v1.9/deploying.html (EDIT by @tnir in 2022-09 https://bundler.io/guides/deploying.html is the current canonical URL for it), it says "If you use Capistrano, you should symlink vendor/bundle to shared/vendor_bundle"

1. do you mean shared/bundle rather than shared/vendor_bundle?
2. do you really need to symlink if .bundle/config has BUNDLE_PATH: ../shared/bundle already, and it will have that via capistrano with require 'bundler/capistrano'. it's already pointing to the shared location. Or you could add BUNDLE_PATH manually, as another option.

http://bundler.io/bundler_setup.html says:

Bundler.require(:default)

...is exactly equivalent to:

...
require 'rack-cache'
...

...To tell bundler to use require 'rack/cache', update your Gemfile:

...
gem 'rack-cache', :require => 'rack/cache'
...

(end of quote)

This doesn't look accurate to me: nobody needs to do that. Even if rack-cache didn't include lib/rack-cache.rb as a fallback, Bundle.require(:default) would require it correctly. At least, Bundler 1.6.2 does.

In the Rails guide, we ask users to run bundle exec rails new, which makes sense if you need to generate a Rails app from a specific version of Rails—after the Rails app is generated, though, users should run bin/rails rather than bundle exec rails. Let's document that.

The existing explanation of this operator was incorrect. I've tested it in Bundler and it works identically to the operator in RubyGems, the docs for which say:

Notice that we only include 2 digits of the version. The operator will drop the final digit of a version, then increment the remaining final digit to get the upper limit version number. Therefore ‘> 2.2’ is equivalent to: [‘>= 2.2’, ‘< 3.0’]. Had we said ‘> 2.2.0’, it would have been equivalent to: [‘>= 2.2.0’, ‘< 2.3.0’].

See the RubyGems docs for more info.

It might also be worth adding a link to these docs in the Bundler docs as a kind of explicit acknowledgement that Bundler's semantics for this operator are identical to RubyGems'.

Finally, mentioning any sort of Googleable phrase for this operator would help newbies. Some call it they spermy operator, though it is understandable that one might wish to avoid this. RubyGems calls it the pessimistic operator, read as approximately greater than.

http://gembundler.com/v1.3/man/bundle.1.html is linked from home page but is a 404.

I could not find a require.html page or equivalent in the bundler-site page sources.

It appears that almost all links to the docs are broken. I.e. the Homepage links to http://bundler.io/v1.10/man/bundle.1.html which 404s. Many other links, such as almost all from What's new also lead nowhere.

Related #199

The code snippet at the bottom of bundle_install.haml uses the correct '--disable-shared-gems' option, but the accompanying text says '--without-shared-gems'.

Fix here:

http://github.com/chrismear/bundler-site/commits/disable-without

S'all.

Add an FAQ to the bundler.io site with easily-linkable sections for quicker responses to common issues/questions.

See also the Trello card with the list of FAQs.

Should there be a separate page for using Bundler with Rails 4? The latest one on the site is Rails 3 and the way that the Rails 2.3 and Rails 4 guides leaves it uncertain if the behavior for using bundler with Rails 4 would be the same as or different from Rails 3.

In http://bundler.io/v1.5/gemfile_ruby.html , the page has

ruby 'RUBY_VERSION', :engine => 'ENGINE', :engine_version => 'ENGINE_VERSION', :patchlevel => 'RUBY_PATCHLEVEL'

but later on:

The ruby directive explicitly leaves out the ability to specify a patch level. Ruby patches often include important bug and security fixes and are extremely compatible.

Is the latter text information that used to be true, but is no longer true, but hasn't been deleted?

Many people are surprised to learn that it is possible to run bundle install --local and have bundler try to install their gemfile using the gems that are already on their machine. I'd like to highlight this feature and hopefully make more people aware of it, since it can be super helpful.

Steal this guide: https://github.com/radar/guides/blob/master/gem-development.md

Create a Frequently asked Question Page based on the FAQs from http://bundler.io/v1.3/rationale.html page
and any others that can be thought of.

related #199

It would be handy to have a section (maybe in the FAQ? maybe in getting started) that explains how to handle merge conflicts on the Gemfile.lock file. If you're using git, the easy way to fix a merge conflict is git checkout HEAD -- Gemfile.lock && bundle install. There are a couple of scripts that will set git up to do this for you automatically. One is a pretty simple gist that sets a git merge resolution driver and one is a git hook that also runs database migrations in rails apps.

Instead of the Report a Bug Page linking directly to the ISSUES.md page. Create a page to link to it and to lay out some of the options to try first before reporting the bug.

From the main site clicking on "Learn more: Executables" takes you to a Github Pages "Page does not exist!" page.

In rationale.haml:577, it says:
bundle config build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config

but I think it should say:
bundle config build.mysql2 --with-mysql-config=/usr/local/mysql/bin/mysql_config

to set option for building the mysql2 gem.

Thank you.

right now the man pages (bundle help and http://bundler.io/man/bundle.1.html) are completely disconnected from the command help (http://bundler.io/v1.10/commands.html). We should connect them, and make one create the other! That way we don’t have to update them twice.

Create a page documenting how to use bundler/inline in scripts:

# Allows for declaring a Gemfile inline in a ruby script, optionally installing
# any gems that aren't already installed on the user's system.
#
# @note Every gem that is specified in this 'Gemfile' will be `require`d, as if
#       the user had manually called `Bundler.require`. To avoid a requested gem
#       being automatically required, add the `:require => false` option to the
#       `gem` dependency declaration.
#
# @param install [Boolean] whether gems that aren't already installed on the
#                          user's system should be installed.
#                          Defaults to `false`.
#
# @param gemfile [Proc]    a block that is evaluated as a `Gemfile`.
#
# @example Using an inline Gemfile
#
#          #!/usr/bin/env 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 Pod::VERSION => "0.34.4"

We've been very good about keeping Bundler stable since 1.0, and it seems like most people now use the latest stable version consistently. Let's continue to archive a copy of the docs as they were for each minor version, but move the list to a sidebar or another page rather than filling up the site header.

Right now the what's new page only explains what is new in the very latest point release. We should link to (or have a long page that includes) what is new in every point release since 1.0. We should also link to the full changelog from there.

Happy to help get Google Apps email set up if it's not done yet