By Kate Travers
When I first started out learning to code, the idea of contributing to an open source project was really intimidating. I got that advice from everyone — “Contribute to open source! It’s so easy! Employers love it!” — but I was still hesitant. I’d only been writing Ruby for a couple months, how was I going to contribute anything useful to someone else’s project?
Well, I’m happy to report from the other side, it’s actually pretty painless and fun for beginners at any level to make meaningful contributions to open source projects.
So shake off that imposter syndrome, the open source community needs you. They need everyone, in fact. Open source projects depend on a large and diverse community of contributors to make their codebases robust. That includes people from all skill levels and all areas of expertise. Plus, the benefits are reciprocal. You’ll get to know the community better, build your support system, and get your name (and your code) out there in a really positive way.
Getting started
So where do you start? The two best pieces of advice I got in this department were to 1) start small and 2) (in the immortal words of Jerri Blank) go with what you know.
Start small
Don’t get caught up thinking that the only contributions open source project owners are interested in are major bug fixes or complicated refactors, that’s simply not the case. Instead, it’s better to zero in on a small, focused improvement.
Take Flatiron School founder Avi Flombaum’s first open source commit, for example. Here, he substituted one method in a single module (and added tests, another solid contributing move, but we’ll come back to that). Clear, concise, and an irrefutable improvement to the codebase — all in just a couple lines of code.
Work on a project you’re already using
Start with something familiar. If you’re learning Rails, check out the repo for a gem you’ve been working with, like factory_girl or formtastic, or another Rails-based project you’re using, like rubygems. You’ll be more invested in improving the project and be able to start from a baseline working knowledge of its intended functionality.
That said, you can always explore new available projects on GitHub. I always like checking their trending page for current hotness, and I actually found the source for my first open source commit through their community explore feature. I was leisurely searching for Ruby-based ‘cat’ projects (like you do), which led me to catsay, a brilliant riff on the cowsay gem. One commit later, and I was an open source contributor. It can really be as simple as that.
Best ways to contribute
There are tons of easy entry points to open source contributing. Let’s run through some of the best options, as well as best practices for submissions.
1. Report a bug
You don’t have to contribute new code to open source projects — bug reporting is just as valuable, something I didn’t realize right away as a beginner. Project maintainers rely on users for reporting, so as you’re working with open source tools, be sure to report any bugs that you surface.
If you uncover a bug, before filing a new issue, check and see if it’s already been reported. You don’t want to clog up the issue tracker with duplicate issues.
Once you’ve verified you’ve found a valid, unreported bug, you’ll want to open a new issue and include as much information as possible for the maintainers. A quality issue report should include:
- Clear title and description of the bugKeep the title concise, but provide clear info in the description below.Example:
- Steps to reproduce the problemStart from the beginning, and provide any necessary context.Example:
- System/version information (your OS version, browser information, etc.)Example: “OX 10.11.1 (15B42), Ruby v2.2.0”
- Full text of any error messagesExample:
If there’s a UI/UX component to the bug, it’s helpful to include a screenshot, or better yet, an animated gif screen capture using a program like licecap, a great project with a terrible name.
Want more advice on writing great bug reports? Check out Textmate’s contributing wiki.
2. Improve existing bug report tickets
While you’re out there setting the bar for quality error reporting, you’ll probably notice some open tickets that aren’t up to snuff. Here’s another opportunity to contribute by filling in whatever information is missing.
First, verify that the issue is still happening. Some times bug fixes go in, but the corresponding ticket is accidentally left open. If you can’t reproduce the error, @ mention the maintainers so they can close the ticket.
If you’re able to reproduce the issue, go ahead and add any of the information mentioned above that’s missing:
- Steps to reproduce
- Error text
- Version info
- Screenshots
Any info you can add will will help take the issue one step closer to being closed.
3. Improve docs
All developers rely on good documentation — it’s the first place you’re going to go when learning new tech. As you’ve probably noticed, though, project docs aren’t always maintained in pace with the rest of the project. You’ll run into info that’s unclear, outdated, or non-existent. Here’s a chance for you to do yourself and other developers a huge favor — fill in those gaps in documentation.
- Add a descriptionIf you run across an undocumented method, chances are it’s not an easter egg. Write up a clear description, ideally with usage examples, and submit for review.
- Write an exampleGood docs provide example usage for all methods / features / etc. (example: Rails ActiveRecord callbacks). If you run across a method that could be clarified with an example (or maybe needs a better example), add one in there. This could be your express ticket to becoming a bonafide Rails contributor.
- Fix a typoHere’s your time to shine, English majors. Remember — (almost) no fix is too small!
4. Add specs
Test coverage is another area that often needs improvement, especially on smaller projects. For any public open source project, you can run the codebase through a static code analysis engine like Code Climate. For Ruby projects, use a tool like simplecov to hook into Ruby’s coverage library and quickly spot the areas that need test coverage. Then put your test writing skills to good use!
Remember, you’ll need to weight coverage vs. the total speed of the test suite. Any tests you add should be super fast or too valuable to leave out if they drag down the suite speed.
5. Patch a bug
Here’s where you can combine everything you’ve learned from the four options above into the ultimate open source contribution: the bug patch. Of course, don’t feel pressured to solve every bug you find, but if you have the bandwidth, take a shot at sleuthing out the solution. Even if you don’t find the fix, report your findings on the existing issue, or open a new one with full details on everything you tried.
When you do find the fix, keep in mind that the best patches are as non-disruptive as possible. Specifically, your fix should introduce as little new code as possible, and any new code should be written in the same style as the rest of the codebase. Keep your scope small; your pull request should address a single, limited issue with minimal changes overall.
When you’re ready to open your pull request, be sure to cover the following:
- Reference the open issue your pull request is solving. If there’s no existing ticket, open one yourself (following the guidelines above).
- Provide a clear description of your changes — what issue you’re solving and how.
- Update any corresponding documentation (as described above).
- Write a test case for the test suite that covers your fix (as described above).
Summary
Most importantly, be patient. It might take a while for your contribution to be reviewed, but don’t let that stress you out. Stay positive, keep contributing, and be proud of your new open source contributor chops.
More resources:
1. GitHub contributing guidelines
2. GitHub guide to finding open source projects
3. Learn.co contributing guidelines
4. Rails documentation guidelines
Kate Travers is a labs developer for Learn. You can see some of her past posts here.
Written byFLATIRON SCHOOL
Make yourself useful.
