How to contribute to open source

A guide for Rails beginners

• Find a project
• Set up the project on your local machine
• Become familiar with the codebase
• Find and fix an issue
• Conclusion

Here’s how I recently got started contributing to open-source Ruby on Rails projects. I’m pretty new to Rails, so if I can do it then you can too! (For more tips for beginning Rubyists, see my study plan.)

Find a project

Here are some beginner-friendly projects that I know of:

• Lobsters
• Ruby for Good makes software for nonprofit organizations. Some of their projects has a Slack community, which could come in handy as you learn your way around a project.

If you want to widen your search, see this list of open-source Rails codebases that I’ve compiled, or explore the resources at First Timers Only.

As you consider projects to contribute to, keep these questions in mind:

• Is the project active? Does it have recent activity and frequent commits?
• Does the README.md have beginner-friendly instructions?
• Are there a variety of issues tagged “Good First Issue” or something similar?
• Are you interested in helping the project succeed?

Set up the project on your local machine

Once you’ve chosen a project, follow the setup instructions in README.md or CONTRIBUTING.md. You will probably run into problems; use your Google-fu to solve them. For example, here were my setup problems in Ubuntu in WSL2, for two of the projects listed above:

• Circulate: The bin/webpack-dev-server command didn’t work until I downgraded to a previous version. Also, chromedriver (for system tests) is not very straightforward to set up in WSL. The guide that worked for me is this one supplemented with this other one.
• Lobsters: The mysql2 gem wasn’t installing properly. It turns out I needed to first install MySQL (duh). So I followed this guide, adding the extra step of sudo service mysql start after installing the MySQL packages. I also had to create some missing files for MySQL and create a new MySQL user for the databases used by Rails. Oh, and I had to disable passwords before creating the new user, otherwise it couldn’t be accessed.

Become familiar with the codebase

Poke around and get a feel for what the app does and how it works. Here are some good starting points in a Rails app:

• the readme (of course)
• config/routes.rb
• the Gemfile
• db/schema.rb
• the tests

Find and fix an issue

You can follow roughly these steps:

1. Make sure you’ve read the project’s README.md and (if it has one) CONTRIBUTING.md.
2. Find an issue that is well-described and seems simple to fix. Often (but not always) these are tagged as “Good First Issue”.
3. At this point, some projects prefer that you claim the issue or leave a comment. Be sure to follow the project’s contributing guidelines. Once you have the OK from the project maintainers, or if there are no pre-contributing steps, then it’s time to work on the issue.
4. Reproduce the issue on your local machine.
5. Write a test that fails because of the issue. (Not all projects require this, but it’s a good rule of thumb.)
6. Fix the issue, and make sure your new test passes.
7. Send back your fix by creating a PR (pull request). To learn how to make a PR, follow the steps in First Contributions. Here is another guide with a few extra steps that are good to keep in mind. Also, if you find that you’ve cloned a project’s repo before forking it, this guide explains how to get back on track by making your local copy point to your fork.
8. Patiently wait for feedback from the project maintainers, and respond if they ask for more input from you.

Conclusion

If all goes well, your pull request will be accepted and you will have made your first contribution to open source! 🎉 From there you can keep an eye out for new issues in your favorite projects so that you can make even more contributions.