Contributing to open source can be a fun and rewarding experience, but it can also be difficult to know where to start. This article will guide you through making your first contribution to the world of open source; from deciding which project you want to get involved in, right through to raising your first issue and making your very first code contribution.
If you're not a programmer, or you just fancy a break from coding, this article also includes a list of ways that you can get involved in open source, without writing a single line of code.
What is Open Source & GitHub?
Open source is a method of software development that promotes transparency and collaboration. When a project is open source, not only can you download and use it, but you can view its source code too. This means that you can fix bugs, add new features, and generally make changes to the project. Being able to view the source code, also gives you a greater understanding of how the software works.
If you've used open source software before, chances are you're already familiar with GitHub. GitHub is a website that provides repositories where developers can store and share their open source projects, but it's also a way for people from all over the world to collaborate on a single project. Once you've registered with GitHub, you can raise issues, suggest new features, and even contribute your own code to projects hosted on the website. Although GitHub is far from the only code hosting service out there, its popularity in the open source community means that it's a good place for newcomers to start.
Choosing a Project
After you've created your GitHub account, you need to decide which project you want to get involved in. This is where the sheer number of projects on GitHub can be overwhelming. In December 2013, GitHub announced that it had reached 10 million repositories, so you'll need a way of narrowing down your options, if you've ever going to choose a project:
- Stick to what you know. Many well-known open source projects use GitHub - JQuery, Ruby on Rails, and Bootstrap, to name a few. So it's worth visiting the websites of open source projects you're already familiar with, navigating to their 'Contribute' or 'Get involved' page, and then checking whether they host their code on GitHub. Making your first contribution, will be much easier if you're already familiar with the project.
- Search by programming language. Chances are, you already have some idea which programming language(s) you'd prefer to work with, so why waste time looking at projects written in languages you either don't know, or aren't really interested in? To see only the projects that are written in your preferred language, perform a language: search (for example, language:csharp, or language:java).
- Trending. You may also find some inspiration by checking out which projects are currently trending on GitHub. GitHub also maintains Showcases of the trending projects that it deems to be the most unusual, which can throw up some really interesting results, such as projects that are based on emoji.
How GitHub Projects are Structured
Every GitHub project is stored in its own repository, which usually consists of multiple folders and files. Although projects owners have the freedom to structure their GitHub projects however they like, there's some files that are common across most projects.
When deciding whether you want to contribute to a project or not, there's a couple of files you should pay particular attention to:
- README.md. This file contains essential information, such as how to build and use the project, and the owner's contact details.
- LICENSE.md. When you hear 'open source,' don't automatically assume you're free to do whatever you want with the software, as there's actually a wide range of open source licenses. You should always read a project's licensing information carefully, as any contributions you make will also be licensed under these terms. If you can't find a License.md, the Readme.md may mention the project's license, and you can then perform a Google search to see exactly what this license entails. If you can't find any licensing information, the project will at least adhere to GitHub's Terms of Service, or you can contact the project owner for clarification (the Readme.md usually contains the owner's contact details).
- CONTRIBUTING.md. Some larger projects have a file containing everything a potential contributor needs to know, which may include project-specific guidelines on how to raise issues and contribute code. If you see a Contributing.md file, be sure to read it carefully.
Making Your First Contribution
Once you've chosen a project, you need to decide what form your first contribution will take. Although there's many different ways you can help out, there's two methods that are particularly popular:
- Raising an issue. An issue is an area where you can feel the project could be improved, for example, you could report a problem or bug you've encountered while using the software, a feature you feel is missing, or a gap in the project's documentation. Conventions for raising issues may vary between projects, so it's always a good idea to check the project for any guidelines (the Readme.md or Contributing.md files are usually good places to look).
- Contributing code. This is what most people automatically think of, when they decide to contribute to open source. In GitHub, code is contributed via a pull request.
The next few sections show you exactly how to raise an issue, and how to contribute code to your chosen project.
How to Raise an Issue
As a first step, it's well worth browsing the issues that other people have already raised, as not only does this give you a feel for the kind of information you should include, but it's also a way of checking that your issue hasn't already been reported. To browse existing issues, navigate to the project's repository and click the 'Issues' link.
When you're ready to raise an issue, click the 'New Issue' button.
Make sure you include as much information as possible, particularly regarding your hardware and software setup. You may also want to provide screenshots or recordings that illustrate the issue, and any error outputs or logs. The more detail you can provide, the easier it will be for the developers to identify and fix the issue.
How to Make a Pull Request
Contributing code via a pull request, involves cloning the original project, making changes to your copy, and then asking the project's owner if they want to pull your changes into their original repository.
The following steps give you an overview of this process:
- Navigate to the project's repository.
- Clone this repository, by clicking the 'Fork' button. When you "fork" a project, it exists on GitHub only, so before you can make any changes, you need to get this copy onto your local computer.
- Create a local clone of your fork, by running the git clone command from your terminal/shell, e.g:
- Connect to the original repository - remember that you cloned your copy, and not the original repository. So, you need to tell your local copy where it can find the original, using the git remote add upstream command, e.g:
Remote Add Upstream
- Make your changes to the local version - this is where you get to be creative!
- Tell Git which files you've changed, and want to commit, by running git add command, followed by the updated file:
- Commit your changes to the project's history, and provide a log message explaining the changes you've included in this commit, e.g:
- Push the commit from your local repository, to GitHub.
git push <remote> <branch>
Note, this commit gets sent to your copy of the repository, and not to the original repository.
- In GitHub, navigate to your copy of the repository.
- Click the "Pull Request" button.
- Enter a description of the changes you've made, and then click the "Send pull request" button. The project's owner will then check your changes, and decide whether they want to include them in their repository.
This is an overview of how to make a basic pull request; you can find additional information about making code contributions, at GitHub Help.
Contributing isn't just about Code
Making a contribution to your favorite open source project doesn't have to involve programming - maybe you need a break from writing code, aren't proficient in your chosen project's programming language, or have never written a single line of code in your life!
Whatever your reason for avoiding code, there's still plenty of ways you can get involved:
- Become a tester. If you can download, build, and use an open source project, you can test it. Testing can be as simple as using the project as you normally would, and reporting any issues you encounter; or you could take a more vigorous approach, for example by checking how the project functions across a range of hardware and software environments.
- Write documentation. Documentation is essential for attracting new users, but it's one area that tends to get easily overlooked. Even when documentation does exist, it's often written by the person who created the project, who may be too "close" to the project to imagine encountering it as a newcomer. As someone who has first-hand experience of being an outsider looking for information about the project, you should already have a good idea of what's missing from its documentation.
- Build a community. If an open source project is to survive and flourish, it needs to become the center of a large, engaged community. Community means more people to discover and report issues, suggest new features, and generally help to spread the word. There's lots of ways you can help to grow a project's community, but a few popular methods are writing blogs and tutorials, promoting the project on social networks, and becoming active on its mailing list and/or forums, particularly when it involves answering questions newcomers have about the project.
- Become a translator. Offering open source software in multiple languages can really help it reach a wider audience. So if you speak different languages, why not offer to help translate the project's website, documentation, or even its user interface?
- Help with bug triaging. This is the process of evaluating and prioritizing incoming issues, and performing general maintenance on the project's issue tracker, such as removing duplicate issues. Bug triaging is an essential bit of admin that ensures there's a steady, ordered list of issues for the developers to work on.
- Suggest a feature. If you have an idea you feel could improve the project, you can suggest it to the project's owner. Bear in mind that well thought-out ideas, with lots of detail and added extras such as mockups, tend to be more positively received than a random, one sentence suggestion.
- Help with design. Most open source projects are the hard work of a small group of people, which doesn't leave much time for the added extras that usually accompany proprietary software. If you have a talent for design, why not offer to help design the project's website or logo? If you fancy a bigger challenge, you could volunteer to give the project's user interface a makeover.
- Donate. This may not be the most exciting way to get involved, but the simple fact is that open source projects don't generate revenue through sales, so donations can help the project's owner cover the cost of things like hardware and software, and other related expenses. Donations are also a way of showing them that you appreciate all their hard work.
This article has covered a number of ways that you can start contributing to open source, but there's countless other ways of getting involved. If you're still unsure how your particular skills could be put to good use, try reading everything you can about your chosen project, scouring its mailing list and forums, and compare the project to other, similar projects - what is it missing? And is this something you could help with? If you're really struck, it may be worth reaching out to the project's owner, to see if there are any areas they particularly need help with.