RubyGems Documentation

RubyGems and Bundler follow the support lifecycle of the Ruby language:

• Ruby Version Support: Supported as long as the Ruby team supports the version. When a Ruby version reaches end-of-life, the following minor release of RubyGems/Bundler will drop backwards compatibility with that version.
• Security Releases: Security fixes are provided for RubyGems and Bundler versions that were included in a currently-supported Ruby release. These versions receive security fixes until that Ruby version reaches end-of-life.
• Bugfixes: Generally released from the main branch. The team does not guarantee bugfix releases for previous minor or major versions.

To update a specific gem without unintentionally updating its indirect dependencies, use the --conservative flag with the bundle update command.

Note: In versions prior to 2.2.22, bundle update --source <gem> had undocumented conservative behavior; users should explicitly use bundle update --conservative <gem>.

To upgrade RubyGems to the latest stable version and update Bundler to match, run the following commands in sequence:

1. Update the RubyGems system.
2. Install the latest version of Bundler.
3. Update the Bundler version used by your current project.

$ gem update --system

$ gem install bundler
$ bundle update --bundler

To follow best practices for deployment and ensure isolation, use the --deployment flag (which replaces the deprecated --production flag in version 1.0.0.rc.3).

In versions prior to 1.0.0.rc.3, the --production flag was available and provided the following behavior:

• Installs gems to vendor/bundle by default (can be overridden with --path).
• Uses --local if vendor/cache is present to avoid connecting to RubyGems.
• Raises an exception if Gemfile.lock is missing or if the Gemfile has been modified without updating the lockfile.

Note on Git sources: If you encounter errors stating "the git source has not been checked out", avoid installing gems to a user-scoped directory (like ~ or $HOME) during deployment. Instead, use deployment-specific paths.

Bundler CLI man pages (the output of bundle help) are managed within this repository using .ronn files located in lib/bundler/man/.

Creating a new page

Create a new .ronn file in lib/bundler/man/ following the naming convention bundle-<command>.1.ronn. For example, to document a bundle cookies command, create lib/bundler/man/bundle-cookies.1.ronn.

Formatting

Man pages use ronn formatting, which combines Markdown with standard man page conventions.

• Use sections like ##OPTIONS to organize content.
• Use code blocks and definition lists where appropriate.
• Consult the ronn guide formatting guide for detailed syntax.

The simplest way to inspect variables or objects is to insert puts statements directly into the code. This is particularly useful when running tests to see values in the console output.

puts "stacktrace: #{caller_locations(0).join("\n")}"
puts "@definition: #{@definition}"
puts "specification.class.name: #{specification.class.name}"
puts "spec.method(:to_checksum).source_location: #{spec.method(:to_checksum).source_location}"
# etc