Open Source Checklist
Make users dig your open source project.
This is basically a summary from one of Chris Hunt’s podcasts where he shares some tips and good practices when starting and maintaining an open source project. The podcast also includes some suggestions on how to find ideas for open source projects and a lot more useful information. I found the checklist really helpful so I wrote down most of the items here, in order to have them available for future reference.
The things mentioned in this article are actually pretty simple, but I think they go a long way in terms of organising a project and providing useful information to its users.
README
The first thing you should absolutely do when starting a project is add a README document in its root folder. This file will be the go-to place where users can get all the essential information about your project.
The following are some of the most important items you should include in it.
Name
Pretty simple, right?
Description / Rationale
Explain what makes your project special, useful or fun. Try to share why you created this project, what drives you to spend your time on it and how you think it will help or entertain others.
Usage
Describe how people can use what you have created. A video or an animated GIF is always nice to be able to see it in action. You can use Asciiname or tty2gif to generate an animation from your terminal interaction. If your project is a library it’s good to provide some example code that shows the users how to get started and what behavior to expect.
Badges
Badges are just dynamically generated images and they are a quick, visual way to show the status of various aspects of your project. They are somewhat optional though. Some of the most common badges are the ones for TravisCI (a continuous integration service) build status and the project’s version number. For a list of available and existing badges check out shields.io.
Contributing
This section is for those who might want to contribute to your open source project. It should include how to download it, get the required dependencies, what is the build process or any other tasks necessary for setting up a development environment. If the process is really complex consider using something like Vagrant. Some projects have issues or features marked as beginner, newbie or something similar, which are low hanging fruit for new contributors.
If the content in this section starts adding up, consider moving it to its own file. Check brackets.io for good a Contributing section and examples of some newbie issues.
Changelog
Add a link to another file that describes everything users need to know about the changes you've made for each version. Specifically this file should include the following sections:
- Added
- Deprecated
- Removed
- Fixed Bugs
The items under each of these titles are an important part of your release notes. For more information about what a changelog should look like listen to (no less than) The changelog podcast #127.
License
Even open source projects need to specify under what license they are released. Anybody who wants to use, modify or share your project needs to know what she is allowed to do with it. Some popular licenses are MIT (do whatever you want), GPL (make sure you share stuff) and Apache 2 (grant of patent rights). To know more about what license fits your needs check out Choose a license or TLDR Legal, they are really helpful and simple.
Releasing to the World
Version
When you feel confident using your project, launch it at 1.0.0 and ignore your hesitation because of future changes you might want to make. If it’s good enough for you, then it will be good enough for other people. Make sure you assign new version numbers using semantic versioning:
Given a version number MAJOR.MINOR.PATCH, increment the:
1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
2. PATCH version when you make backwards-compatible bug fixes.
Share
Tweet it, post it on Hacker News (with a Show HN prefix) and/or send a message to mailing lists you read or know about (i.e. Cooper Press).
Further Reading
There are a couple of really good articles by Michael Klishin where he shares some thoughts on How to Make Your Open Source Project Really Awesome Part 1 and Part 2. Some of the things he mentions are included in this article while others are not, both posts are absolutely worth reading.
