Beginner’s Guide to Web Development
Open Source Contributions
8 minute read
Open source software generally means code that is open to the public, and anyone is welcome to propose changes or enhancements to it. (Keep in mind, though, that just because open source software is open to the public does not mean it is not subject to proper licensing and copyright laws.)
Most of the world’s open source code today lives under a service called GitHub, which not only hosts code but also allows people to manage and moderate the code repositories. Having an active GitHub account with relevant open source contributions in your field of work has become increasingly more attractive to prospective employers and is slowly becoming a standard measurement for the quality of an engineer.
Why Make Code Open Source?
This question is occasionally brought up by those who are new to coding or not used to the direction the industry is moving toward. It’s a fair question — why in the world would companies or even individual developers share their code with the rest of the world? The answer can be reduced to one word: collaboration.
The quality of a project can only increase when more people who care about it start putting their heads together to improve it. When more people are involved in a library’s development, more use cases are brought to light, and the code becomes more robust over time as it starts getting used by lots of people around the world.
Ultimately, the pros of open sourcing code far outweigh the cons, but even with that in mind, open source is still not for everyone. The policies of certain corporations, and even the laws governing some public institutions, still forbid code from being open sourced, and that’s okay.
5 Easy Steps for Contributing
If you’re ready to start getting noticed by certain communities you care about, and even prospective employers, then it’s time to start contributing to open source! If you’re just getting started writing software and still aren’t sure of your skill level, contributing to open source projects is a great way to learn how to collaborate with other developers and will improve your code as it gets critiqued by potentially tens if not hundreds of other developers. This might sound a little intimidating, but don’t let that stop you — most communities are very understanding and welcoming to beginners, as long as you abide by the rules.
Now let’s go over the unwritten law of the land in the open source world. Pretend you were using an open source library and found a bug in it. Usually the flow of contributing to open source code works like so:
1. Read the CONTRIBUTING file
Some open source projects have a file at the root directory called
CONTRIBUTING.md. This file usually contains instructions for preliminary steps you need to take before becoming a contributor.
In this file, they might ask you for a certain convention on how to file bugs, etc. Be sure to read this file and follow the instructions. Here are a couple of examples of the
CONTRIBUTING file in the jQuery and Angular repositories.
2. File a bug in the project’s repository
At this point, this process varies depending on what was requested by the project’s authors in the
CONTRIBUTING file. But in general, the next step to contributing to an open source project is to file a bug in the project’s repository.
This is where GitHub really shines, as it makes it really easy for anyone to communicate with the authors of the library in question. There, you would “open an issue,” and notify the authors of the bug you found and what steps they must take to reproduce the bug.
The more information you write about the issue, the better. So if you found what part of the code is causing the bug in the project’s codebase, be sure to let them know where the problem is and that you would be happy to fix it for them by opening a pull request. Most authors will welcome a pull request, but it is generally considered good courtesy to wait for the author’s feedback in the issue before opening the pull request.
3. Forking the code
While you are waiting for the author’s feedback on the issue you opened, there is nothing wrong with forking the project and starting to work on a fix for the problem on your version of the code.
Forking means you are making a copy of the project to your GitHub account so you can freely make changes before submitting it back to the original codebase. The process of submitting it back to the original codebase is called a pull request, which basically means you are asking the author’s permission to merge the changes you made into their original codebase.
Once you are done making the changes on your version of the repo, be sure to look for any special instructions the author might have added in the
CONTRIBUTING.md for commit messages. If there are special instructions, then follow their conventions. If not, then a couple general guidelines for good commit messages are to be descriptive about the changes you made, and make the least amount of commits possible. Some libraries will even require you to squash all your changes into one single commit before opening a pull request.
Also, if the library has unit tests, be sure to run them and ensure everything is running properly before submitting your pull request. If you added any new features that might require new tests, be sure to write those tests and commit them into the project as well.
4. Making a pull request
Once you’re done and proud of your code, and the author has given you permission to open the pull request, push your code to your remote GitHub repository and open the pull request. Much like opening an issue, be sure to follow any guidelines in
CONTRIBUTING.md before opening the pull request. A good guideline when opening pull requests is to mention the ID of the issue that is getting resolved with this pull request. This is as easy as adding the #ID-OF-THE-ISSUE to your description. To find out what the ID of the issue is, simply find the issue in the list of issues, click on it, and look at the end of the URL. The ID will be the number at the end of the URL.
Once your pull request is open, it will be up to the library author to review your code and decide whether or not they are going to accept the changes you made. Usually if they see a problem with your code, they will let you know so you can address it. Don’t worry if that happens — it’s normal. Once you have addressed any problems they might have found and pushed all the latest changes, the author will be able to accept your pull request, causing your code to merge to the original codebase.
5. TA-DA! 🎉
Congrats! Once your code is accepted, you have officially become an open source contributor. But don’t stop there — keep looking for more ways to help improve that library (and others) by proactively looking at their list of GitHub issues and offering to help fix some of the problems you see you. (Hint: Not everyone who opens an issue is looking to fix it themselves.)
What Projects to Start Contributing To
It’s generally a good idea to start contributing to smaller projects. So, for example, instead of contributing to the jQuery source code, which gets a lot of attention and has been pretty stable for a few years, it might be a better idea to start with one of the community-backed plugins that were built on top of jQuery.
Those authors tend to get less attention and usually need a lot of help fixing bugs or writing new features for their codebases. Those smaller libraries also tend to not have as much of a process when contributing, so it’s good to know some of the general unwritten rules laid out above when seeking to help them out.
You may be surprised to find some authors simply don’t want any help, which is fine. In those cases, it’s better to move on and look for other libraries that are genuinely looking for more help. Again, a great way to get to know an author is by simply opening an issue on their repo and getting a conversation started.
Sometimes you will also find great projects that have been abandoned. In those cases, feel free to message the authors and let them know you would like to either take over the project or simply help them manage issues and pull requests by other developers. Both of these solutions will help the open source project tremendously, as well as increase your experience as a developer by collaborating with other developers.
Contributing With Documentation
If contributing to a project’s codebase still feels a little too intimidating, you might want to look into other ways of getting started — documentation, for instance. After all, how good is an open source library if nobody knows how to use it? Many libraries evolve quickly and their documentation often gets overlooked and quickly becomes outdated.
If you’re looking to start contributing to open source projects and don’t know how to start, consider helping a project with their documentation. Documentation is an essential part of libraries and is usually a low-hanging fruit for prospective contributors that want a foot in the door — not to mention, it helps the project immensely.