How to contribute

Community involvement is essential to RubyGems. We want to keep it as easy as possible to contribute changes. There are a few guidelines that we need contributors to follow to reduce the time it takes to get changes merged in.

Guidelines

  1. New features should be coupled with tests.

  2. Ensure that your code blends well with ours:

    • No trailing whitespace

    • Match indentation (two spaces)

    • Match coding style (run rake rubocop)

  3. If any new files are added or existing files removed in a commit or PR, please update the Manifest.txt accordingly. This can be done by running rake update_manifest

  4. Don't modify the history file or version number.

  5. If you have any questions, Feel free to join us on Slack, you can register by signing up at slack.bundler.io or file an issue here: github.com/rubygems/rubygems/issues

For more information and ideas on how to contribute to RubyGems ecosystem, see here: guides.rubygems.org/contributing/

Getting Started

Installing dependencies

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.

Manually trying your local changes

To run commands like gem install from the repo:

ruby -Ilib exe/gem install

To run commands like bundle install from the repo:

ruby bundler/spec/support/bundle.rb install

Running Tests

To run the entire test suite you can use:

bin/rake test

To run an individual test file located for example in test/rubygems/test_deprecate.rb you can use:

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

And to run an individual test method named test_default within a test file, you can use:

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

Running bundler tests

Everything needs to be run from the bundler/ subfolder.

To setup bundler tests:

rake spec:parallel_deps

To run the entire bundler test suite in parallel (it takes a while):

bin/parallel_rspec

There are some realworld higher level specs run in CI, but not run by bin/parallel_rspec. You can run those with:

bin/rake spec:realworld

To run an individual test file location for example in spec/install/gems/standalone_spec.rb you can use:

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

Checking code style

You can check compliance with our code style with

rake rubocop

Optionally you can configure git hooks with to check this before every commit with

rake git_hooks

Issues

RubyGems uses labels to track all issues and pull requests. In order to provide guidance to the community this is documentation of how labels are used in the rubygems repository.

Contribution

These labels are made to guide contributors to issue/pull requests that they can help with.

Type

Issues might have a light green type: * label, which describes the type of the issue.

Pull request might have a light orange rubygems: * or a light blue bundler: * label which describes the pull request according to the following criteria:

In the case of bundler, these labels are set by maintainers on PRs and have special importance because they are used to automatically build the changelog.

Workflow / Status

The light yellow status: * labels that indicate the state of an issue, where it is in the process from being submitted to being closed. These are listed in rough progression order from submitted to closed.

Closed Reason

Reasons are why an issue / pull request was closed without being worked on or accepted. There should also be more detailed information in the comments. The closed reason labels are maroon closed: *.

Categories

These are aspects of the codebase, or what general area the issue or pull request pertains too. Not all issues will have a category. All categorized issues have a blue category: * label.

Platforms

If an issue or pull request pertains to only one platform, then it should have an appropriate purple platform: * label. Current platform labels: windows, java, osx, linux

Git

Please sign your commits. Although not required in order for you to contribute, it ensures that any code submitted by you wasn’t altered while you were transferring it, and proves that it was you who submitted it and not someone else.

Please see git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work or help.github.com/en/articles/signing-commits for details on how to to generate a signature and automatically sign your commits.