Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
130 lines (73 loc) · 4.43 KB

GETTING_STARTED.md

File metadata and controls

130 lines (73 loc) · 4.43 KB

Getting Started

Prerequisites and Setup

Fork the ruby/rubygems repo and clone the fork onto your machine. (Follow this tutorial for instructions on forking a repo.)

This repository does not have a root Gemfile. Development dependencies are managed through purpose-specific gem files in tool/bundler/ (e.g., test_gems.rb, rubocop_gems.rb). Use the following rake task instead of bundle install:

bin/rake setup

NOTE: If the above fails with permission related errors, you're most likely using a global Ruby installation (like the one packaged by your OS), which sets GEM_HOME to a location regular users can't write to. Consider using a Ruby version manager like RVM, rbenv, chruby or asdf. These will install Ruby to a location regular users can write to, so you won't run into permission issues. Alternatively, consider setting GEM_HOME environment variable to a writable location with something like export GEM_HOME=/tmp/rubygems.gems and try again.

Testing Your Local Changes

RubyGems Commands

To run RubyGems commands like gem install from your local copy:

ruby -Ilib exe/gem install

Bundler Commands

To run Bundler commands like bundle install from your local copy:

bin/bundle install

Running Tests

RubyGems uses test-unit and Bundler uses RSpec. Each has its own test commands.

RubyGems Tests (test-unit)

To run the entire RubyGems test suite:

bin/rake test

To run an individual test file, for example test/rubygems/test_deprecate.rb:

ruby -Ilib:test:bundler/lib test/rubygems/test_deprecate.rb

To run a specific test method named test_default:

ruby -Ilib:test:bundler/lib test/rubygems/test_deprecate.rb -n /test_default/

Bundler Tests (RSpec)

To run all Bundler specs (both regular and realworld):

bin/rake spec:all

This runs spec:regular and spec:realworld. The full suite takes 20-30 minutes.

To run an individual spec file:

bin/rspec spec/install/gems/standalone_spec.rb

To run multiple spec files or long-running specs in parallel:

bin/parallel_rspec spec/install

For realworld higher level specs (also run in CI):

bin/rake spec:realworld

Developing Bundler and RubyGems Together

When developing Bundler features or bug fixes that require changes in RubyGems, you can set the RGV environment variable to point to the repository root so Bundler's test suite picks up those changes:

RGV=.. bin/parallel_rspec

You can also test against specific RubyGems versions:

RGV=v3.2.33 bin/parallel_rspec

It's recommended to set this variable permanently using direnv for consistent development.

Code Style and Quality

Check code style compliance:

bin/rake rubocop

Optionally configure git hooks to check this before every commit:

bin/rake git_hooks

Shell Aliases (Optional)

Set up a shell alias to run Bundler from your clone for convenience.

Bash

Add this to your ~/.bashrc or ~/.bash_profile:

alias dbundle='ruby /[repo root]/bin/bundle'

See this tutorial for adding aliases to your ~/.bashrc profile.

Windows (PowerShell)

Add this to your PowerShell profile (use vim $profile on the command line if you have vim installed):

$Env:RUBYOPT="-rdebug"
function dbundle
{
	& "ruby.exe" E:\[repo root]\bin\bundle $args
}

For a better command line experience on Windows, consider using Windows Terminal.

Git Commits

Please sign your commits. Although not required to contribute, it ensures that code you submit wasn't altered during transfer and proves it came from you.

See Git commit signing documentation or GitHub's guide for details on generating signatures and automatically signing your commits.

Debugging

See DEBUGGING.md for debugging tips and techniques.