GitHub 101: A Beginners Guide To Open Source Software Projects

Since launching in 2009, GitHub has become the biggest Git repository hosting service in the world and is used by millions of individuals and businesses to manage software projects. It has also become a playground for open-source software projects that often involve a large number of contributors. When there are a lot of cooks in the kitchen, it can become chaotic and scare off beginners. If you are a software developer that’s ready to enter the GitHub fray, we have some advice on what to do — and what not to do — when you’re contributing to a project in a Git repository.

As of April 2016, GitHub has over 14 million users and 35 million repositories. Many of the projects hosted on GitHub are open source. The nature of the service allows for large groups of people from all corners of the world to collaborate and improve the code in these projects. But the nature of group work, especially when individuals come from diverse backgrounds, means maintaining and participating in a project can become problematic. Which is one reason why GitHub brought in a feature that allows project owners of public repositories to block troublesome users.

It can be intimidating to start contributing to an open source project and it can be a bit of a learning curve for newbies. First off, let’s talk about taking the plunge. To do this, you’ll need to create a GitHub account. We have a guide on how to do this here.

Once you’ve done that, it’s best to start off on a project that is beginner-friendly.

Ask Questions

Shubheksha Jala is a developer from India who recently documented her foray into contributing to open source projects on GitHub and the sometimes hostile responses she received from existing contributors who did not take kindly to newbies. It was a daunting experience but she worked hard to get accepted as an open source contributor.

One of Jala’s biggest tips for beginners is to ask questions.

“I can’t stress on this enough. I’ve lost a lot of time because I kept holding myself back and this was my biggest inhibition,” she said on a post in Medium. “Everyone is scared of looking stupid. But don’t let that crippling fear result in stunted growth. It’s okay to ask if you don’t understand something related to the project. The maintainers of the project have been well-versed in the project for years. They can help you fairly quickly. The alternative is you spending hours lost in their codebase trying to figure something out that you’re not even supposed to know in the first place.”

Jala does advise that you do your research first before asking a question; the answer may already be available through documentation or by doing a quick Google search. Stack Overflow is a good resource to look at as well. If there is a contributors guideline for the project you’re working on, read it.

Start off by working on resolving easy issues on a project first and be comforted by the fact that you’re not expected to know everything when you’re a contributor.

“The idea is to learn and grow as you start solving harder issues becoming more familiar with the project and the tooling they use. The time it takes for this to happen varies from project to project and person to person,” Jala said.

So You Want To Improve The Code

According to developer Brian Ford, the best way to start improving the code in a public project is to fork the repository on GitHub; this makes a copy of the repository on your own GitHub account. He advises that before you start trying to improve the code and release it as pull request, which essentially lets you tell others about changes you’ve pushed to a GitHub repository so they can come and examine it, you need a clear vision on what you want to do. Then you need to create a branch so you can comfortably make changes to the code without compromising the existing project. According to Atlassian: “Git branches are designed to be a fail-safe mechanism for integrating code and sharing changes between repositories.”

Testing is something that should be done before you submit a pull request. Ford said: “As you’re changing the code, you might want to try it within some app or larger project.”

Once you’ve changed the code, tested it and committed it (which is basically saving the changes), you’re ready to submit a pull request.

Mind Your Manners

It’s such a simple thing to keep in mind, but it can be easy to forget your manners when you’re working on a project full of contributors with strong personalities. But always remember to be polite, lest you want to risk being blocked by the project owner.

Submitting a pull request can be a great learning experience for beginners. According to GitHub director of field services Matthew McCollough:

“It’s a huge opportunity to learn from some of the best people in the industry. You’re essentially getting mentoring that you can otherwise not get for free, but in benefit of trade for your time and thought and investment in fixing, improving and tuning up the pieces of software used worldwide.”

When you’re submitting a pull request, be sure to keep your commentary brief and specific when you’re trying to point out problems with the code. Supplying screenshots can also help.

Take note of how other pull requests are submitted as well and try to keep the format of your ones consistent with existing conventions.

Jason Chen, who created the Git repository for Quill Rich Text Editor has the following advice to share for submitting pull requests:

• Do submit one pull request to address one issue.
• Do submit two pull request to address two issues.
• Do not tack on a minor whitespace or semicolon changes in unrelated commits or Pull Requests, even if the minor change is correct. Make a dedicated commit or Pull Request instead.
• Do read the contributing.md guideline if one is linked.
• Do submit pull requests for typo fixes in documentation or comments. This is the easiest and most welcome way to get your name added to the contributor list.
• Do not submit a large surprise Pull Request. Discuss the need for it and the merits of your approach first, probably in a GitHub Issue or the project discussion forum or mailing list.
• Do not be surprised or get upset when you ignore the above and your Pull Request gets closed.
• Do not expect all Pull Requests to lead to being merged.
• Do not expect others to coach you through your Pull Request. It happens when time permits but expecting it is misguided entitlement. Pick an easier way to contribute if you get stuck.
• Do include tests with your Pull Request.

More importantly, he wants to warn beginners to avoid jumping to conclusions that other contributors are being rude:

“Do be charitable with your interpretation of others’ words. For example, reasonable interpretations of ‘What do you not understand?’ include a condescending insult or hurried clarification attempt. But the most charitable interpretation is that it is an open ended invitation to be a data point used to improve the documentation. With global diversity of personalities and cultures participating in open source and the low emotional density of written text, always default to the most charitable interpretation of others’ words.”

Don’t be discouraged if things don’t go according to plan when you’ve just started contributing to open source projects on GitHub. Not everybody will be nice when they dish out feedback and it can be daunting when you submit to a big project. But everybody has to start somewhere and you can gain invaluable experience by simply taking your first steps.

Do you have some advice you’d like to share with GitHub beginners? Tell us all about it in the comments.