This book is a step by step guide on creating a fully functional Open Source Project. The Book starts with documentation and a quick project setup, then moves into work scheduling, management, completion, stress testing, and ending with tying everything into an issue tracker. Within the pages of this eBook you’ll find everything you need to know in order to bring your idea from concept to reality. This book is designed for the everyday developer to understand, yet contains concepts similar enough to those used by enterprise level software companies to make it useful for almost everyone.
This tutorial is for people who have never created a project and want to learn the basics of creating an open source project. This course will teach you how to create a Github account, write a CONTRIBUTING.md, commit code to a repository, use pull requests, and push your work to GitHub. We are not recommending that anyone should contribute to this project but we will give you an example of what things look like when you are ready to start your own open source project.
Define what success looks like
urllib3 is used by millions of people everyday, has 785 stars on GitHub, and has been growing since its creation in 2008. Andrey has another project, ssh-chat, that has 1,560 stars on GitHub, but is only used by about 15 people today. So which project is more successful? In order to answer that question, Andrey described how defining success at the beginning of project will help you understand if it’s successful or not.
The beginning of every open source project looks like this:
- Build something. Anything.
- Get frustrated with the hardest parts, build libraries and tools to help.
- Discard the original project to focus on the libraries, which become your new project.
- Go back to step 2 and repeat.
The story of urllib3 begins with the problem of trying to upload billions of images to S3 in 2008. Using existing Python libraries, this would have taken more than three weeks because there was no good concurrency support. You could use s3funnel, a multithreaded S3 client, but managing threads is painful. You could use a worker pool in s3funnel instead, but existing HTTP libraries didn’t reuse connections, and most solutions weren’t threadsafe or lacked multipart (filepost) encoding. Enter urllib3.
A snippet of requests, a popular function in urllib3
In Andrey’s words, “The solution space [in engineering] is about building something and solving a problem. For urllib3, the space was really small and the solution to other things were really useful, and that’s what made it successful.”
When defining a project’s goals, think about how solving a small problem can make a large impact.
Another form of success in open source is exemplified by ssh-chat, an encrypted chat-over-SSH program written in Go. Andrey started ssh-chat as a weekend project. One of the main contributions to the project’s success started with creating a thorough README. As Andrey puts it, “Having a great README is basically 80% of the work to success. You need to be able to answer three questions for your contributors: “Who else uses it?” “What do they use it for?” and “Where can I get more help?”
A snippet of ssh-chat, a popular ssh-chat program written in Go
But just creating an awesome README didn’t kickstart the impressive growth of ssh-chat. To make it thrive, it needed more traction.
Set a LICENSE file
The first thing you should do is choose a license for your project and ensure the license text lives in the LICENSE file. There are sadly too many projects on GitHub with a missing license and this makes it more difficult for people to use and contribute code.
If you are unsure which license to choose for your project, there are great resources online for choosing what is best for you.
Recruit core contributors
To spread the word about ssh-chat, Andrey started asking for help, asking for improvements, and finding ways to bring more people into the project. In order to help build interest, Andrey reached out to people on Twitter and offered free Go programming lessons in exchange for opening pull requests. This overcame the initial inertia of getting a few people involved and interested in the project. These early contributors eventually became champions of ssh-chat and started answering questions on Stack Overflow.
Another component of building and maintaining open source projects is learning to be inclusive. Andrey says “accepting pull requests very generously, and very graciously” was a key step in building more community interest and is something that many open source authors miss in the beginning. And asking specific people to make a pull request was much more effective than making more generalized asks of his Twitter followers.
Create a README.md
When you visit a GitHub repo for first time, the README.md file is rendered underneath the code. This is a fantastic opportunity to introduce your project, explain how you build the code, and explain how people can get involved and participate. Remember, .md files are Markdown files and you can use Markdown syntax to make them look all puuuuurty. OK, I admit, that was creepy.
Market and promote your project
In general, programmers tend not to be self-promoting types, so actively marketing and promoting an open source project doesn’t come naturally. With this in mind, Andrey identified ways that programmers can promote their projects without being self-aggrandizing.
One approach is to write interesting blog posts about your projects to provide clearer context of the project’s story and mission. Medium is a great platform for sharing in the technology community and has more potential readers than a self-hosted blog.
Other opportunities for connecting with contributors that worked for urllib3 and ssh-chat included:
- Answer questions on Stack Overflow (set up alerts on Stack Overflow for specific topics)
- Participate in discussions on Hacker News, reddit/r/programming, etc.
- Sell to other open source projects and establish partnerships with them. “The only reason urllib3 is the most popular third-party Python library today is because it’s part of requests.”
- Feed the non-trolls: Getting upvotes on your announcement post is only half the equation. More activity and discussion yields more people clicking on it and more updates, so if you respond to almost every comment, then that’s 2x as many comments.
Label bugs as ‘Bitesize’
One of the most difficult areas for a new potential contributor to get started in is learning what they can work on to help with a project. Of course, the list of issues is often a good place to start, but many issues are riddled with context and nuance which can make this difficult.
A simple solution to this is to create a Bitesize label that you can apply to bugs that would be simple for beginners—this could include minor UI issues, string issues, translations fixes, and more. Simply label these bugs when you triage them and then provide a URL in your README.md and CONTRIBUTING.md files to point prospective contributors at the list to get started.
Everything you need to start your first open source project. It’s a lot easier than you think. Here are links to tools that can help you with your open source project. This guide will help you get your first open source project started in no time!