One of the most beautiful aspects to software development is having the opportunity to contribute to Open Source Software. For a long time I wanted to contribute to a library or framework that I used every day.

The only problem was that every time I had the motivation to try, I easily got intimidated by what seemed like a high-pressure situation (spoiler alert: it doesn't have to be). By starting small and staying focused, making your first PR for a widely used project can be both fun and beneficial for the community.

So after chatting with Jon Galloway of the .NET Foundation, I sat down and fixed an issue that I had discovered in the ASP.NET Core documentation. I created my pull request and the next morning I woke up to it already merged in! It's not always that easy, but follow these simple steps and you'll be a well-respected contributor in no time.

Step 1: Find an Issue

Although it may seem obvious, the most important step is finding a issue. And not just any issue, a good issue. What makes an issue good? Just find something that seems wrong and ask yourself these questions:

  1. Is there a clear and obvious reason for the change? If a change fixes a breaking bug, then it is a fix worth pursuing. If there is indisputable evidence that a section of documentation is wrong, then a fix is worth pursuing. The key is making sure that the motivation for the change is shared among users and maintainers alike. If you want to make a change to the API because you think it will be better, then maybe you should start by creating an issue to first get some input from the maintainers before spending more time on it.
  2. **Can you fix it in a clean and concise way? **To some people refactoring/rewriting can be a cathartic exercise. But just because you feel better after a rewrite doesn't mean it was a good idea. Keeping the changes minimal and specific will help in two ways. The first is that it will keep your changes easy to read, which will help speed up the review process. The second is by minimizing the chance for new bugs or issues. No amount of cleanup is worth it if new bugs are introduced.
  3. **Is there already a fix out there? **Before diving too deep into a solution, make sure that someone else didn't already take a shot at it. If they did, double check the status. It might be pending, abandoned, or simply obsolete at this point. Open source moves fast, so investigate first to avoid wasting time.

Step 2: Fork & Fix

Believe it or not, the easiest part of your first open source contribution should be forking and fixing. GitHub makes forking super easy, just navigate to the repository and click the "Fork" button!

GitHub's Repository Interaction Options showing Watch, Star, and Fork options.
GitHub's Repository Interaction Options

Once you have your own fork of the repo you can clone it to your development environment for editing. You technically have the option to edit it online from GitHub, but as I cover in the next step it's best to clone the repo so you can ensure the changes pass tests and coding standards.

Finally, when applying fixes try to limit changes to those required for the fix. Small changes means fast reviews, which probably increases the chances of getting it merged. If you feel like the changes are beginning to snowball, reach out to the project maintainers for some guidance.

Step 3: Test & Pull Request

The world would be a better place if everyone tested their code. And to me, it's absolutely CRAZY that people make changes and commit it without verifying that it works! Continuous Integration has been a blessing by allowing teams to move fast while maintaining stable branches. But that doesn't mean we should rely on CI alone. It's crucial to test your changes as rigorously as possible before making your PR. It helps to ensure that the changes you made were correct, and helps to avoid wasting the valuable time of a maintainer.

Once you've successfully tested your changes your good to create your PR! Be sure to provide a clear and concise title so maintainers can easily triage the PR. In the description be sure to include details about the motivation for the change, how the issue was solved, and any other supporting details that would help a maintainer review the changes.

When creating a PR, sometimes repositories will have a Contributor License Agreement (CLA). This is just an agreement that means the community can use your changes. It typically takes less than 5 minutes and only has to be done once, so don't be intimidated by it.

Step 4: Be Patient, Listen, and Stick with it

With some luck and hard work, your PR will get merged in once the maintainers take a look. They could also provide some requests for more changes or simply ask some questions.

An important part of Open Source Software is being able to work together and receive criticism. Respect is paramount in a community.

Take the time to understand their feedback and work with them to arrive at the best outcome. If it results in a merged PR, then that's great! But if they are still not happy with the changes, don't let that get you down. Stick with it and use it as an opportunity to learn and grow.

Finally, if they close it (or worse, never respond to it) then do not worry! Anyone who contributes to Open Source Software will get a closed PR at some point in their career. My recommendation is to start back at Step 1 and find a good issue to fix. GitHub projects usually have issues with a tag like good first issue or help wanted that are great for new contributors.

Conclusion

Contributing to Open Source Software is an exercise that all developers should try at some point. There are so many fantastic tools and frameworks out there that we use for free every day. But they are not free for the maintainers and their families. Give back to those who work so hard and help make your community a better place.

If you have any questions please hit me up on twitter! I'm happy to help anyone with their first (or 100th) PR!