The New Developer’s Guide to Open Source

Photo licensed under CC0 — sourced from Pixabay

Contributing to Open Source Software can be a great career booster. Many tech companies list Open Source contributions either as a job requirement or as a plus for potential applicants to engineering roles. Also, lady developers, according to a recent GitHub survey, only about 3% of Open Source contributors identify as female. With these facts in my mind, I made the decision to jump into my first Open Source adventure.

After months of working up the courage to contribute to an Open Source Software (OSS) project, I took the plunge and submitted my first pull request. To help other new contributors struggling to work their way into Open Source, I assembled a step by step guide to choosing a project, fixing an issue, and submitting a pull request.

Step 0: Don’t Panic

Easier said than done. Take a deep breath, put on some Kenny G, everything will be OK.

Step 1: Find a project

For me, this was arguably the most difficult step. I must have Googled “best open source projects for new contributors” dozens of times. Based on my experience, I do not recommend using Google as your primary resource for finding projects. Instead, check out one of these resources:

• Code Triage: This site lists thousands of Open Source projects that need developers sorted by number of open issues. You can filter the list by programming language, and even sign up to have issues from projects emailed to your inbox daily. This was my favorite place to research projects by far; the easy-to-use UI takes stress out of the search process.
• GitHub — Great for new contributors: This list is smaller than the list of Open Source projects on CodeTriage, but it is a showcase of projects curated by GitHub that are known for being welcoming to new contributors. If you find huge lists overwhelming, start here.
• up-for-grabs.net: A site with a list of projects that have tasks tagged for new contributors. You can filter the list by tags like programming language or type of software, and up-for-grabs displays the number of newcomer issues each project currently has open. The downside — this list does not appear to be the most up to date and some of the projects shown are not very active.

With so many OSS projects out there in GitHub land, it can be incredibly challenging to figure out which project will best suit your skill set. I suggest choosing a project that is written in your most comfortable programming language, and also choosing a product that you have either already used, or you can figure out how to use. Contributing to a project requires you to understand what that piece of software is supposed to do, so before you commit your time, try out the product and make sure you get the concept.

Now that you have a project in hand, continue to step 2.

Step 2: Make sure the project is active

This step is pretty simple and will eliminate a good number of projects right away. Head to the project’s GitHub page and answer this list of questions:

• How many open issues does this project have? (Check the page’s “Issues” tab close to the top of the project’s home page.)
• When was the last commit sent? (Check the “Code” page to find the latest commit)
• How many contributors are there? (Number of contributors will also be on the project’s “Code” page)
• Does the project have an active Slack, IRC, Gitter, or other contributor chat? (Usually you can find this in a project’s contributor guide)

If you find yourself on a project page with only one open issue where the last commit was six months ago, there are only a couple of contributors and no contributors’ chat forum to be found, back away from the OSS project. Go back to Step 1. Or, if you’re starting to panic, go back to Step 0. Breathe.

Once you’ve found a project with a healthy number of open issues (I think 100+ is a good number to shoot for to ensure you have a variety of issues to pick from), and a solid base of regular contributors, it’s time to move on to Step 3.

Step 3: Make sure the project is newcomer-friendly

To ensure you have a good first experience with open source, keep an eye out for projects that are open to newcomers, and projects that really, really, are not. Taking on new contributors is a big task for project maintainers, and not all of them are willing to hold your hand as you embark on your journey.

Any open source project that is looking to attract new contributors should have the following:

• A clearly posted open source license — Calling a project open source without an open source software license is a big no-no. You don’t want to contribute your code to software that is improperly using the term open source. Check the project’s GitHub page for a LICENSE.md file, and a license name listed on the project’s heading. Some of the more popular licenses include Apache, GNU GPL, MIT, and Mozilla Public License.
• Painstakingly detailed documentation — Look at the README section of the project page. Read through the docs and try following along with the instructions provided for using the software. Make sure you can get through setup and understand the software’s purpose. If the README links to other pages with more documentation, check those pages out, too. Don’t rush through this part, reading docs can be a bit dry and boring but will make you a better contributor.
• New contributor guide/style guide — You should be able to find this in the project’s documentation under “Get Involved” or “For Contributors” or “Contributing”, etc. This guide will give you information on what steps to take to make your first contribution. You should also see style guidelines for contributing code to the project.
• Git workflow details — Git is a powerful tool that also has the power to seriously jack up your code if you use the wrong commands. For that reason, each project should have specifics in the contributor guide about how maintainers would like contributors to utilize git.
• A code of conduct — A code of conduct that prohibits discrimination, harassment, and overall douchebaggery is a must. This won’t keep people from being rude to you from time to time, but a code of conduct does mean the maintainers will be more likely to boot people from the project if they’re violating the rules.
• Discussion forum or group chat — Check the new contributor docs for a forum where people can ask questions, talk about how to resolve issues, propose changes, etc. Usually projects will have a channel on Slack, IRC, or Gitter. Also, join the channel and read through some of the conversations in the forum. Are people respectful? Do the maintainers answer questions in an encouraging way? If not, move on to another project.
• Issues reserved/flagged for new contributors — From the project’s “Issues” tab, click the “Labels” button. You should see a list of labels this project uses to flag issues. The new contributor docs should tell you which of these labels are best for newcomers, but some common ones you may see are “help-wanted”, “newcomer”, “difficulty/low”, “first-timers-only”, “beginner”… you get the idea.

If the project you’re exploring is missing one of these components, jump on back to Step 1 — there are plenty of open source fish in the sea. Oh yeah, and, don’t panic.

Step 4: Get intimately familiar with git

Git has become the industry standard version control tool. If you’ve never used git or GitHub before, I would highly recommend playing with these tools on a small, non-crucial personal project before contributing to a group project. Check out this tutorial for some of the most important basic commands you will use while tracking a project using git.

If you already have some experience using git, take some time to read your chosen project’s guidelines for commit messages, when to squash commits, naming conventions for branches and forks, etc. One convention that seems to be true across projects— do not develop on the master branch. This will make it much more difficult to synchronize your fork with the project’s master branch when changes happen in the main repository.

Step 5: Choose an issue to work

For your first pull request (PR), pick a bite-sized issue that you understand fully. It’s stressful enough trying to become a part of the project’s community and learn the git workflow — don’t add the extra stressor of trying to solve a difficult problem while trying to read through an unfamiliar codebase.

A few examples of great first issues:

• Correct a spelling or grammatical error
• Fix a broken link
• Help write project docs
• Refactor or add comments to code to follow guidelines
• Rename variables for better readability or consistency

Check the issue in GitHub to see if it has already been assigned or worked on by someone else. This will keep you from duplicating or stepping on someone else’s toes. Choosing a good newcomer issue can be a tricky step because there are a lot of new open source contributors out there testing the waters. Keep at it; you’ll find something to work on it just takes time and effort.

Once you’ve picked an issue most contributor guides will give instructions on how to ask to be assigned to work said issue. The project may have a bot or CI/CD tool that helps assign issues. If the project docs are unclear about how to request to work an issue, ask one of the moderators what to do.

If you can’t find an issue that you know how to solve listed on the project’s issue tracker, see if you find a typo in the documentation and ask if you can create a new issue to fix it. As long as you’ve picked a newcomer friendly project, you can also head to the discussion forum to ask if anyone would be willing to help you work an issue if you’re feeling stuck.

Don’t panic.

Step 6: Cloning and Forking and Branching, Oh My!

OK — back to git. As mentioned in Step 4, each project will have its own conventions for git best practices. However, there are a few things you will need to do no matter what project you choose.

• Make sure you have git installed on your local machine. If you have a Mac OS, homebrew package manager makes installing a breeze. Just type “brew install git” onto your terminal’s command line. (After installing homebrew, of course.)
• Clone your project’s repository into a directory of your choosing on your local machine
• Fork the repository and add a remote of your fork to your local machine. This allows you to push and pull commits to and from your fork on GitHub.
• Create a new development branch to work on the issue you selected. Do not make changes to files while on your fork’s master branch.

If any of these steps is unclear, head back to step 4 and try out a few interactive git tutorials. You should also check your chosen project’s docs to see what kind of git guidance you can find.

Step 7: Fix your issue

If you’ve picked a newcomer friendly issue that you fully understand, this will likely be the easiest step. It may take some time in a large project to find the directory that holds your issue. GitHub’s search feature can be helpful here. From the project’s repository, look at the top nav bar next to the GitHub logo for a search box labeled “This repository”. Type in some key words from your issue, like the typo you’re trying to fix, or the file that contains the bug you’re seeking. Once you find the right file, Command F is your best friend.

Now, fix that bug/typo/broken link! This should feel incredibly gratifying now that you’ve spent so much time on steps 1 through 6.

Step 8: Commit your changes

Do yourself a favor before committing any changes by doing a quick git branch check. As a rule you should be making all changes on the branch you created for your assigned issue, not on the master branch. Check your project’s docs on commit messages and follow them to a ‘t’. Some projects use bots to assign, create, and close issues and the formatting of your commit message may be crucial to the functionality of the bot.

Before committing it’s also a good idea to check the status of your branch to see if you need to pull down any new changes from the master branch. Once your working branch is up to date with master, commit your changes, push the code to GitHub, and create a pull request on the project’s page.

Then, you wait…

Step 9: Make requested fixes

Chances are, if this is your first time contributing to an open source project, (or even if it’s your 100th time contributing) your contribution will have some mistakes in it. Maybe you missed a project guideline, wrote a funky commit message, or misunderstood the explanation of the issue.

Whatever the mistake, remain humble and receptive to feedback. Don’t beat yourself up or become defensive. Most of the time (if your project is beginner friendly) the maintainers are asking you to change something for a good reason. If you need clarification on what you need to fix or why, just ask. It’s that simple. Commit the requested fixes, squash your commits if you have multiple that pertain to the same small issue, and push your code again.

Keep lines of communication open and also keep an eye on your issue to make sure it gets merged. If maintainers haven’t merged your changes within a week or two, follow up and see if you need to do anything else.

Step 10: Celebrate

This is an exciting moment. If you’ve reached this step, your first pull request has been accepted into an open source project! Your GitHub profile will show a celebratory picture on your timeline so jump in the air and yell “Huzzah!”

Once you’re done celebrating, remember to continue contributing to the project you chose. Project maintainers put a lot of work into helping new contributors so it’s important to show your gratitude by gradually solving incrementally more difficult problems.

Contributing to Open Source software is a great resume booster, but it’s also much more than that. It’s a chance to be a part of a movement that has fostered technological progress and innovation for decades. If you feel like you have nothing to offer to the Open Source community, I challenge you to prove yourself wrong by getting involved. And, as always, don’t panic.