Open source projects can seem scary at first. It is not immediately obvious how to structure an open source project and get people to contribute. But the beauty of open source is that the more you share, the more others will share with you. These projects provide some great examples of basic start points for open source projects on Github which can be used as templates or blueprints for future projects.
1. 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.
2. 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.
3. Create a CONTRIBUTING.md
In a similar fashion, the CONTRIBUTING.md file is designed to show how people can participate in a GitHub repo. When this file is present, GitHub will display a little note inviting people to learn more about contributing to your project. Users who click on that link will see the contents of CONTRIBUTING.md.
Again, this is a great opportunity to explain how people can participate. In this file you should provide simple step-by-step instructions for how prospective community members can clone and build the code, explore issues/features to work on, fork the code, contribute back their changes, and which communication channels they can use for help and support.
4. 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.
5. Checkboxes for items
A neat little feature in GitHub is the ability to use Markdown to add checkboxes to issues. This can be helpful when you file an issue for a larger feature with a number of tasks that need to be completed. It means you then don’t need to file lots of issues for each task. To add a checkbox simple use this syntax:
What is neat is that when you add a number of these checkboxes within a single issue, the issue list will show how many checked items have been completed next to the issue title. This provides a handy way of determining which larger issues are making progress and which are not.
6. Issue templates
Speaking of issues, one of the most frustrating aspects of managing bugs is when your users submit bugs that are not particularly helpful for a developer to resolve. In general, you want your users to provide the following information:
- A crisp and descriptive summary of the issue
- A more detailed description of what happens and why it doesn’t work
- The expect result and how the current is not correct
- A step-by-step set of instructions explaining how the developer can reproduce the problem.
- A list of details about the user’s system (e.g., operating system, version of the software, and any other details
This is a lot of information for a typical user to provide. To make this easier, GitHub has an Issue Templates feature where you can pre-fill a new issue with content and questions the user should fill in. Simply create an ISSUE_TEMPLATE.md file in a .github directory in your code and add the Markdown in that file and it will be displayed in the main text box in a new issue. You can do the same for pull requests with a PULL_REQUEST_TEMPLATE.md.
7. Use the wiki
One of the most important aspects of creating a strong community is ensuring new participants can learn how to get involved. Ideally you want to provide documentation about your project such as:
- A step-by-step tutorial on how to fork the code, work on a new feature, and how the code review process works.
- Coding standards, conventions, and requirements.
- A breakdown of the code, how it is structured, and what the different source files do.
- Details about how the project communicates, makes decisions, and more.
Every GitHub project comes with a built-in wiki that is a perfect place for this kind of content. What’s more, each wiki is actually a repository that you can commit to. This makes it easy to split the load up among contributors to maintain documentation about the project and how to participate.
8. Build a GitHub pages site
Although the wiki is a great place for documentation, it is not the best place for a website about your project. For this GitHub provides GitHub Pages—a free service for building a project website.
GitHub Pages is powered by Jekyll, a static content management system. This makes it simple to build a site, maintain it in a repo, and iterate and improve on it.
9. Waffle.io/ZenHub for planning
GitHub currently doesn’t include particularly comprehensive project management tools. If you are building a project and want to manage target deadlines and assign tasks and feature goals to those deadlines, you might need a project management system. Fortunately there are a few great options, both of which integrate tightly with GitHub:
- ZenHub is a particularly comprehensive project management system where you can track work boards, tasks, and TODO items, all of which integrate with existing GitHub projects via issues and other features. ZenHub integrates really nicely and adds a layer of functionality that is noticeably missing in GitHub.
- Waffle is a Trello-like platform that allows you to manage kanban cards for tasks that integrate fully with GitHub issues
The idea behind open source projects is that a group of individuals or organizations get together with the goal of creating quality software. The main benefit to an open source project is that you are able to contribute your code to a larger community of coders, who can help you write better and more efficient software.