If you’re anything like me, you want to contribute to open source software but are too intimidated to send your first pull request to another team’s repository.
In this article I’ll share my first foray into working with a major open source project. My hope is that this will help take away the intimidation factor of working with another team’s code and show you how cool working in a larger community can be.
In this article, I’ll specifically be talking about a pull request to Microsoft’s .NET documentation project. The workflow, tooling, and examples I provide will be specific to that project and the team that maintains it, but the broad concepts should be applicable to many projects you encounter.
Find a Project to Contribute to
It goes without saying that in order to contribute, you need to pick a project you want to contribute to.
Last weekend I learned that I had been accepted into the .NET Foundation. That’s a big deal for a life-long Microsoft fan (and .NET fan since 2001) and it left me wanting to find ways to contribute more to anything related to .NET.
As it happened, I found a thread on Twitter that piqued my interest:
I decided to take their advice and look up the .NET documentation projects. After all, writing on technical matters is just a little bit in my wheelhouse.
Pick a Good First Issue
Once you select a repository, you’ll need to find a way to get started.
Sometimes you’ll have strong opinions on something that needs to be changed. Other times you might just be looking to help a team with an up for grabs issue.
If you’re trying to contribute something specific, you can skip most of this section and move on to actually working with the code. That said, if you are contributing anything other than fixing a typo or getting example code to compile properly, you really should create an issue in their repository for the work you’re about to do. This makes sure your work is wanted and that the repository owners can comment on the implementation of it before you spend your time on the topic.
If you don’t know what you’d like to work on, go to the repository’s Issue’s tab and look at the available tags. You want to look at issues that are currently open and have “Good First Issue”, “Up For Grabs”, or similar tags applied to them.
Microsoft’s documentation team has thoroughly vetted and commented on everything in their backlog, and it was a breeze for me to find issues that were available.
Now, you need to find an issue that looks like a mixture of something you’re interested in working on and something that’s potentially easy to do for someone new to the repository.
In my case, I selected an improvement to the INotifyPropertyChanged examples in C# and VB .NET. The as-is code was fine, but .NET evolves over time and, as it evolves, better ways of doing things emerge. This was my opportunity to share best practices in an area I’m an expert in, so I jumped at the chance.
Understand the Issue
Whenever you pick up an existing issue, you need to carefully and thoroughly read the description as well as every comment in its history. The repository owners and issue creator have likely chimed in to some extent and out of respect for their code, you should understand the issue and their intent and concerns in the way it is resolved.
In my case, which appears very typical for the .NET Documentation team, the team had thoroughly vetted and discussed the issue and I had some extremely helpful comments to rely on.
I also made a comment declaring my intent to work on the issue as well as my intended change. This was partially to see if the team would reassign the issue to me or request I work on a different issue instead, but no reply came back.
Fork and Clone the Repository
Although you can clone repositories locally without forking them, you won’t be able to make a pull request unless you’ve first forked the repository.
Forking, thankfully, is very simple. Just click the “Fork” button on GitHub and it will walk you through creating a copy of that repository.
Once the repository is forked, follow GitHub’s prompts to clone the forked repository to your machine.
I’m a big fan of GitKraken as a Git Client, so I copied the URL and cloned from GitKraken using that URL, but the command line or another app of your choosing will work just as well for you.
Understand the Team’s Workflow
The next step will vary based on the project and team you’re working with. First, you’ll want to figure out what branch you should base your changes on. Next you’ll want to find out if the team chooses and specialized git workflow or naming conventions around their branches.
Thankfully, you don’t need to guess these things in most repositories as the community has standardized on creating a contributing.md or readme.md file which will walk you through how to get started working with the repository, including the branch structures and git workflow.
If no relevant documentation is present, be wary since the team may not welcome new contributors.
In my case, the .NET team provided a very helpful contributing guide, but you may not get this. You may need to infer things by looking at past commits to identify patterns or even contacting the repository owner yourself.
Before you get started in an editor, I recommend creating a branch in git based on the appropriate starting branch (see earlier discussion). Be sure to check prior branches and the contributing.md and/or readme.md files for branch naming conventions.
Branch names aren’t the end of the world since you’re submitting a pull request later to another repository, but it helps you feel like you belong to use a consistent name.
Orient Yourself
Okay, now that you have the code locally, you need to open up the project in whatever editor the language you’re working with demands.
In my case, that editor should have been Visual Studio, however I couldn’t find a .sln file at the root of the repository, so I assumed the project was instead intended to be a Visual Studio Code workspace.
I was delighted to open up the folder in Visual Studio Code to get a prompt that the workspace is associated with a set of recommended extensions and ask me if I wanted to install them. Of course I accepted that, and Visual Studio Code configured itself in a way that would help me see the code similarly to how the maintainers see it.
You’re unlikely to work with a team as awesome as the Microsoft Documentation team (and if you do I’m sure they’d love to hear what they can improve on).
Even with this helpful guidance, you still need to find your way around the project structure. While contributing.md may help make sense of some folders, often my first step in a project is just to open folders and subfolders until I start to see repeated organizational patterns.
Once I’ve started to identify patterns, I start looking for the files related to the code I’ll be changing.
In my case, Microsoft made it incredibly easy yet again by noting them in the issue on GitHub.
So, per the issue, I looked up how-to-implement-property-change-notifications.md and looked around the markdown file for the section containing the code examples to update.
What I found was surprising:
Instead of the page containing the example, it referenced the example from another git repository the team maintained: the Samples repository.
This was a bit of an obstacle since I had to fork and clone that repository, then find the files I was looking for in that project’s structure.
For me, the second repository was the biggest negative of the whole experience. The nested repository design made it harder for me to orient myself and harder for me to have confidence in what I was doing because I couldn’t easily see the markdown with my revised changes in it.
I believe that Microsoft designed things this way to make it easier for developers who wanted to download the samples and play with them locally, so the team sacrificed their own productivity for the good of the larger community.
Make and Test Your Changes
Once you know you’re in the right place, you’ll need to make the necessary fix or enhancement, test it, and then commit the files in question.
Building, running tests, running linters (if applicable), and otherwise validating your code is important and a big part of being a responsible software engineer in a larger community.
Thankfully, most large projects have automated checks built into the pull request process that will make sure your code complies with team standards, but it saves a bit of humiliation to make sure your code works fine locally before you create your pull request.
Once your code is committed, make sure you push it up to your forked version of the repository. This step is necessary in order to create the pull request.
Create your Pull Request
Now that you’ve pushed your changes, you can go back to your forked repository and create the pull request by clicking on the appropriate prompts.
The branch and repository on the left indicate the repository and branch you want to merge into. This repository should be the project’s main repository and the branch will usually be the same one that you branched off of. The branch and repository on the right will be the forked repository and its branch you were working with a moment ago.
Now that you have the destination set, follow the team’s convention of naming your request. In my case, I put a descriptive title of the commit as well as an issue number in parentheses.
The team also had a template auto-populate the contents of the pull request’s body and I wrote a detailed list of the changes I made, using markdown syntax.
Note that the very last like says Fixed dotnet/docs#10675.
This is a magic string that GitHub parses to associate my commit with the correct issue (#10675) in the docs repository (recall I was making a change to the samples repository).
If you have any concerns regarding what to put in your pull request for the repository you’re working with, take some time and look at past pull requests, their contents, and any comments on those requests.
Once you’re ready, click Create pull request.
What Happens Next?
Congratulations, you just contributed a little bit to the open source software community. The journey, however, isn’t over.
Your code may need to pass automated checks (typically a build and possibly some code analysis) before it is reviewed. Additionally, a project maintainer will need to look over your changes and choose whether or not to accept them by merging them into the source repository.
In my case, the changes were reviewed the next morning and I got a kind message and a notification that my pull request was accepted and the issue closed.
The changes I made went live within that day, meaning that not even 24 hours passed between me forking their repository, making changes, and those changes being reviewed, approved, and deployed to production.
Closing Thoughts
As I said, I’ve been a life-long fan of Microsoft. However, I didn’t expect the feeling of pride that hit me when I got that message. Mine was a minor change and a change the team made very easy for me to accomplish, but the pride from having contributed in a small way to something I care about was huge.
I strongly recommend you give contributing to open source software a try. Find a project you care about. Find something that interests you. If you can’t find something, try working with Microsoft’s documentation like I did, or put something out there on Twitter saying you’re looking for a small way of helping a project.
Start small, see how things work out, and then work your way up to what something you like.
The community is great and if you respect people’s processes, code, and workflows, they’re usually going to be extremely helpful and thankful for your help – even if your code or comments aren’t perfect.
Open source software development is amazing. All it needs is a little help from you.
The post How to Contribute to Open Source Software appeared first on Kill All Defects.
Top comments (24)
Great post Matt!
On this website: up-for-grabs.net/ You can find GitHub repositories tagged:
and more...
So a good place to start if you are looking for a project to contribute to.
I think one of the things that doesn't get mentioned enough is, if you want to start contributing to open source but don't know how or are intimidated by it, you can start contributing to your friends' side projects. Be it cleaning up readme, fixing existing issues and so on. If your friend or a co-worker has a open source project, reach out to them, collaborate and it will give you a good starting point.
I started my open source work last year during the hacktoberfest and it was the best thing I could have done the last year. This event is very good because you have a motivation to read through the contribution guidelines. In my opinion it is difficult to start if before no contribution was made in any repository. But after one or two contributions you know how the process works and you can apply your knowledge do other repositories, too.
Love this. This is a true end-to-end coverage of how to contribute to Open Source. Thank you for sharing Matt.
Last year, I also wrote an article on Open Source Contribution and those interested in pursuing OS contribution might find it useful when combined with the contents of this article.
Thanks for writing this article. it is indeed daunting to start, especially for me, always thinking that I am not good enough to contribute, and others can do a better job. Never knew there are tags like
good first issueWhat a great article, Matt. In case anyone wants a step-by-step course with a deep dive into the workflows and how to find / work on issues for a project, I just released a course on this topic!
pluralsight.com/courses/contributi...
If you work at a bigger company (or some small companies too), you may have a Pluralsight subscription.
In the course I cover the same topics and it's geared towards those who feel intimidated or unsure where to begin when looking at open source projects.
Good luck!
I love Pluralsight. Congrats on the course!
Hey man! This article is awesome, I am currently learning how to Contribute to Open Source Software, Can I translate your article, learn, and then put it on the China Programming Forum website? And I'll keep original address in article.
Yes, provided you link to killalldefects.com/2020/01/26/how-... which was the original post on my web site.
Okay, no problem.
Nice post, and some good recommendations for contributing to 'big' projects.
My fist contributions were to small projects. Most times I found and fixed a bug, or added a feature in my fork. It's a good idea in such cases to first create an issue, to get feedback how the maintainer think about it.
I really want to contribute in open source project. But, Lack of knowledge make me down.
The more I learn software development, The more I feels lack of knowledge :(
You'll always lack knowledge. Tech changes quickly and things are broad and deep. Look at it as an opportunity to grow and not as a sign something is wrong with you.
Hi Matt,
Sounds I'm in the right path and just need keep walking and build something amazing!🌁
Thank you for your advice 🙋
I think contributing is the easy part, it's finding something that you want to contribute to that's difficult. I think I figured out a solution to that which usually comes down to "what packages am I using in all my projects?" and right there in your dependencies there's always a library or the overarching framework you're using that could use some help with fixing bugs. So that's a tip for someone that's looking for things to contribute to that are within your domain and not just a random package/framework that you have no idea about or ever used.