Contributing to open source projects used to seem like a mysterious process, with questions such as – should I contribute in a pull request? or simply add my changes on the top of their codebase? How do I credit the developers? Is it even worth contributing? In this article, You will learn how to make contributions to an open source project hosted on Github through a series of practical examples based on scenarios drawn from real life experience.
Each open source project maintainer has different opinions on what they expect from each contributor. For example, some maintainers would accept even a simple typo fix while some demand code to be of high programming quality. This article is born out of my experience working in various open source projects over the past 5 years and will aim to help you make your first contribution to an open source project on Github.
Learn the basics
When working with GitHub, you should know how to use Git – one of the most popular version control tools (also known as revision control tools). Because developers constantly make changes to their code, they need a system that can manage those changes in a central repository. In this way, everyone involved in the development process can download a given piece of software, make changes, and submit updates.
The GitHub Flow
GitHub is designed around a particular collaboration workflow, centered on Pull Requests. This flow works whether you’re collaborating with a tightly-knit team in a single shared repository, or a globally-distributed company or network of strangers contributing to a project through dozens of forks. It is centered on the Topic Branches workflow covered in Git Branching.
Here’s how it generally works:
- Fork the project.
- Create a topic branch from
- Make some commits to improve the project.
- Push this branch to your GitHub project.
- Open a Pull Request on GitHub.
- Discuss, and optionally continue committing.
- The project owner merges or closes the Pull Request.
- Sync the updated master back to your fork.
This is basically the Integration Manager workflow covered in Integration-Manager Workflow, but instead of using email to communicate and review changes, teams use GitHub’s web based tools.
Get to know GitHub
GitHub is the most popular platform for open source collaboration, so you’ll probably use it when exploring the world of OSS. First, you need to create a GitHub account and read the guide that helps you get started. On GitHub, you can contribute to projects by submitting issues and contributing code. Submitting issues means sending messages about errors in applications and suggesting ways to fix them. Contributing code involves sending pull requests with your corrections and improvements.
Pull Request button
If we click that green button, we’ll see a screen that asks us to give our Pull Request a title and description. It is almost always worthwhile to put some effort into this, since a good description helps the owner of the original project determine what you were trying to do, whether your proposed changes are correct, and whether accepting the changes would improve the original project.
We also see a list of the commits in our topic branch that are “ahead” of the
master branch (in this case, just the one) and a unified diff of all the changes that will be made should this branch get merged by the project owner.
Join the community
You can easily join an open source project by subscribing to the mailing list for that project. You can find mailing lists on official websites or on GitHub pages. After being accepted to the list, you can communicate with team members and get support if necessary. Thanks to the vibrant communities present in nearly every OSS project, you are likely to get quick replies to your questions.
Comment on a specific line of code in a Pull Request
Once the maintainer makes this comment, the person who opened the Pull Request (and indeed, anyone else watching the repository) will get a notification. We’ll go over customizing this later, but if he had email notifications turned on, Tony would get an email like this:
All skills are welcomed
Even non-programmers can contribute to open source projects! Documentation is needed for all projects, and sometimes this is poorly written and maintained. Thus, you can help by writing, updating or even translating documentation. Also, your design skills might come in handy: every application needs an interface, after all. Finally, you can contribute by managing a community by replying to questions and guiding newcomers.
Pull Request discussion page
Now the contributor can see what they need to do in order to get their change accepted. Luckily this is very straightforward. Where over email you may have to re-roll your series and resubmit it to the mailing list, with GitHub you simply commit to the topic branch again and push, which will automatically update the Pull Request. In Pull Request final you can also see that the old code comment has been collapsed in the updated Pull Request, since it was made on a line that has since been changed.
Adding commits to an existing Pull Request doesn’t trigger a notification, so once Tony has pushed his corrections he decides to leave a comment to inform the project owner that he made the requested change.
Create your own open source project
Every project should start with an identified need. If you feel that existing projects on GitHub or Bitbucket don’t offer the functionality you would like to build, then create your own open source solution. Besides an initial project draft, you should consider the following set of questions:
- What skills do you need for your project?
- How much time are you willing to spend on your project?
- What problem(s) does your software solve?
- How many potential users are there for your product?
Pull Request final
An interesting thing to notice is that if you click on the “Files Changed” tab on this Pull Request, you’ll get the “unified” diff — that is, the total aggregate difference that would be introduced to your main branch if this topic branch was merged in. In
git diff terms, it basically automatically shows you
git diff master…<branch> for the branch this Pull Request is based on. See Determining What Is Introduced for more about this type of diff.
The other thing you’ll notice is that GitHub checks to see if the Pull Request merges cleanly and provides a button to do the merge for you on the server. This button only shows up if you have write access to the repository and a trivial merge is possible. If you click it GitHub will perform a “non-fast-forward” merge, meaning that even if the merge could be a fast-forward, it will still create a merge commit.
If you would prefer, you can simply pull the branch down and merge it locally. If you merge this branch into the
master branch and push it to GitHub, the Pull Request will automatically be closed.
This is the basic workflow that most GitHub projects use. Topic branches are created, Pull Requests are opened on them, a discussion ensues, possibly more work is done on the branch and eventually the request is either closed or merged.
Here are some general practices to follow when contributing to an open source project on Github.