How to Read Open Source Code is just the start. Once you know how to read open source code, I encourage you to start contributing to open source projects as well. There are multiple challenges and difficulties that come along with this, but it can also lead to an amazing community of knowledge sharing and insight, which will make you a much better programmer in the process.
Since the rise of open source software, developers have been able to create and share their code with the community at large. This has lead to a massive increase in code reuse and some incredibly successful projects have sprung from this collaboration. Whether you’re contributing to a popular project, starting your own open source project or using an open source tool, you can improve how well your projects do by following these simple steps.
The best way to make someone’s life easier is to write open source software. Open source software is software that can be freely shared and modified by anybody. The main idea of open source software is sharing what you made with the community. Because of this, you release your work under an open source license, so anybody can make the code better and distribute the changes back to you.
No one cares about your project
First of all, as an author, shift your thoughts about open source. You might think that if putting a lot of effort into the project (library, tool, framework, etc) that’s interesting to you, a lot of developers are going to get excited as well.
Unfortunately, that’s far from the truth…
It might sound harsh, but developers out there are only interested in solving their problems. So when someone visits your repository, one is searching for a solution.
Setting up your project for success
Not too long ago I wrote a post about an open source project I released through The New York Times. Although I have had some experience contributing to open source software (OSS) in the past, this was my first time launching an open source project where I was the sole contributor and wanted others to use what I had written in their own projects. As someone who has benefitted from plenty of incredible OSS projects, I had some idea of what a “good” open source repo on GitHub looks like: it should have a README.md file, installation instructions and enough documentation to get started. But beyond that, I was totally lost: what would take my repo from good to great?
What follows is a short guide, pulled from my own experience, on best practices when making a project open source. Most of what I learned was found through research online, conversations with coworkers and friends and checking out dozens of projects available on GitHub.
Choosing a license
An open source license guarantees that others can use, copy, modify, and contribute back to your project without repercussions. It also protects you from sticky legal situations. You must include a license when you launch an open source project.
Legal work is no fun. The good news is that you can copy and paste an existing license into your repository. It will only take a minute to protect your hard work.
When you create a new project on GitHub, you are given the option to select a license. Including an open source license will make your GitHub project open source.
If you have other questions or concerns around the legal aspects of managing an open source project, we’ve got you covered.
Documentation is Key
Probably one of the biggest pitfalls for open source projects is a lack of documentation. Having easily accessible, human readable and reference-able documentation can be the difference between a project that is readily consumed by others and one that falls by the wayside without much fanfare.
There are a few places where you can place important information, but the most central and accessible is in the project’s root README.md file.
Solve a real problem
Before even starting the open source project, before even writing the first line of code, invest a lot of time in finding a real problem to solve.
To summarize, a good open source project solves a problem that developers are actively searching for a solution.
I wasn’t particularly enthusiastic about strings. Creating such a library might even be boring… But what’s more important I found a decent problem to solve.
Some strategies to find good problems to solve:
- Think about a problem you are experiencing. Can you create a solution for it?
- Explore open source projects that are widely used, but are mediocre. It’s ok to implement your own better solution.
- Search for ideas in GitHub issues of popular repositories, Stackoverflow questions, or even Twitter.
A successful open source project solves a known problem
Start with a README
The README.md is the most visible file in your repository and likely the first one a person will see. The project’s main README file is usually located in the root of your repository and acts as the landing page for your repo; it should communicate the most important information about your project clearly and concisely. There aren’t hard and fast rules about what should and shouldn’t be in a README, but the following are some good starting points.
Why your project exists. What purpose does it serve and who does it serve? This is a mission statement of sorts and should be prominently visible for anyone who’s visiting the repo for the first time.
Quick start instructions. Usually includes instructions on how to download and use your code as quickly and easily as possible.
In-depth API documentation. Depending on how robust your API is, you could opt to include the documentation for it directly in your README file. If there is too much to fit in one place or you need more documentation features (such as search capability, FAQ, forum, etc.), this is where you can link to an external site.
How to contribute. The next part of this post will do a deeper dive on how to instruct others to contribute to your project via a contributing guide, but the README.md file is a great place to encourage contributions and link them to that guide.
Shout out to your contributors. It’s important to give thanks and recognize those who help support your project. The All Contributors project is a great resource on how to best reward different kinds of contributions along with some handy tools that make it easier to streamline the process.
Where to turn for help. If a user or contributor needs help using your code, who should they reach out to? Would you prefer they ask you directly, open an issue in GitHub or reach out to others working on the same things? Some larger communities set up IRC or Slack spaces where anyone can ask questions and get help from others.
Code of conduct. No one wants to deal with a jerk on the internet. Including a code of conduct can clearly point out the kinds of behavior that aren’t tolerated and can help structure an inclusive community around your project. The Contributor Covenant is a widely adopted code that celebrates and encourages diversity of thought and people, and clearly defines enforced punishments for those who act in discriminatory or ill-intentioned ways. There are a plethora of examples of different types of code of conduct out there, so do your research and pick the one that best aligns with how you and your community members want the developers around your open source project to behave — or create your own.
The README file is meant to direct users to where they need to go, either with code samples, set-up instructions or links to more in-depth forms of documentation. These are just some of the topics you can include in your README, but there are so many others that might be right for your particular project. Don’t be afraid to take a look at other repos, whether or not they’re similar to yours or completely different, and borrow ideas whenever you think it makes sense!
Reading and understanding open source code is one major way in which open source software development differs from proprietary software development. If you’re interested in contributing to an open source project, or simply hoping to modify a piece of open source code for your own purposes, knowing how to read the code will be incredibly helpful. Use this guide to help you get started!