gem-contribute

Find contributable issues in the gems your project already depends on.

$ gem install gem-contribute
$ gem-contribute scan
44 gems · 42 on github.com · 2 unknown source

Top contributable projects (by open contributable issue count):
  rubocop          4  github.com/rubocop/rubocop
  rspec            1  github.com/rspec/rspec
  reline           1  github.com/ruby/reline
  ...

The premise: the gems in your Gemfile.lock are the projects you have the most context on. If you depend on sidekiq, you have opinions about Sidekiq. That’s a better starting point for open-source contribution than scanning all of GitHub for good-first-issue tags and hoping one looks interesting.

Quick start

gem install gem-contribute            # one-time install
gem-contribute init                   # one-time setup: set clone_root, then GitHub OAuth
gem-contribute scan                   # see what's worth contributing to
gem-contribute issues rubocop         # drill into one project's issues
gem-contribute fix rubocop/12345      # fork, clone, branch (<clone_root>/rubocop/rubocop)
# ... make your change, commit ...
gem-contribute submit                 # push, then open the PR compare page in your browser

Full command reference → ・ Configuration →

Status

v0.x, heading toward 1.0. The CLI is the v1.0 surface — all verbs below are live on rubygems.org. What follows 1.0:

See ROADMAP.md for detail.

Commands

Command What it does
gem-contribute init One-time interactive setup: set clone_root, then authenticate with GitHub.
gem-contribute scan [path] Parse Gemfile.lock, resolve each gem to its source repo, rank GitHub-hosted projects by open contributable issue count.
gem-contribute issues <gem> List open contributable issues for one gem with number, title, and URL.
gem-contribute issues all Iterate every github.com gem in the lockfile; print only those with open issues.
gem-contribute auth login Authenticate with GitHub via OAuth device flow (no token paste, no client secret).
gem-contribute auth status Show whether the cached token is still valid.
gem-contribute auth logout Drop the cached token.
gem-contribute fork <gem> Fork and clone a gem’s repo, land on the default branch. Use this to explore before picking an issue.
gem-contribute fix <gem>/<n> Fork the gem’s repo, clone to <clone_root>/<owner>/<repo>, create a gem-contribute/issue-<n> branch. Re-running the same command is safe — switches to the existing branch.
gem-contribute submit From inside a clone, push the current branch and open a pre-filled PR compare page in your browser.
gem-contribute config set <k> <v> Persist user preferences.
gem-contribute config list Show current configuration.

Global flags: --refresh (clear cache), --version, -h/--help.

Configuration

User config lives at ~/.config/gem-contribute/config.yml.

Key Default Notes
clone_root (none) Where fix and fork clone repos (<root>/<owner>/<repo>). Set via init. fix errors if unset.
editor $EDITOR Editor launched by fix -e / fork -e.
ai_tool (none) AI coding tool launched by fix -a / fork -a with the clone directory as cwd.
comment_on_fix true Post a “working on this” comment on the issue when fix runs. --no-comment to opt out per invocation.
preferred_labels ["good first issue", "good-first-issue", "help wanted"] Labels scan and issues query when counting contributable work. Comma-separated string or YAML list.

Manage with gem-contribute config set <key> <value> rather than editing the YAML by hand.

Authentication

gem-contribute auth login uses GitHub’s OAuth device flow. The flow:

  1. The CLI requests a one-time code from GitHub.
  2. Your terminal prints the code and (on macOS / Linux) copies it to your clipboard and opens github.com/login/device in your browser.
  3. You paste the code, click Authorize.
  4. The CLI’s pending poll succeeds; the token is cached at ~/.config/gem-contribute/auth.json (mode 0600).

This is the same UX gh auth login uses. The OAuth App is gem-contribute, registered to the gem’s maintainer; users do not need to register their own.

Tokens are scoped to public_repo only — enough to fork, clone, and read public issues, not enough to touch private repositories. If you ever want to revoke, visit your authorized apps and remove gem-contribute.

Design

For the architecture overview, see design.md. For specific decisions and the reasoning behind them, see the ADRs.

The short version:

Contributing

The tool is for finding contributable projects, so it had better be one. See CONTRIBUTING.md and open issues tagged good first issue.

If you’re looking for the Blue Ridge Ruby 2026 workshop materials, see archive/workshop.md. The workshop concluded 2026-05-02; the materials are kept for reference.

License

MIT. See LICENSE.