On Open Sourcing Libraries
Jump to: TL;DR
Open sourcing a library is easy, it is just a matter of seconds. All you need is a public repository hosted somewhere (GitHub, Bitbucket, etc.) right? Nope! Actually, it would be better for everyone if you would add some love to your new shiny library you just made publicly available. Let's see how to do that.
README file is a first-class citizen in your project. You MUST have
it! This file MUST contain the name, and a (short) description of your
library. See this description section as an elevator pitch.
Then comes the Usage section. Describe how to use your library, with both words and code snippets. Add screenshots or GIFs. Be as exhaustive as you can. This is your project's documentation, and most of the time for libraries, this will be the only documentation you will provide.
Writing the Usage part first is not a random choice. Your
should blow your reader's mind, so that they will use your library and
contribute back (or not).
The third section you MUST include is the Installation one. This section explains how to quickly install your library, from a user point of view. If you have more than one way to install your project, describe the one you consider the best first, and then explain the alternatives.
You can add an optional Requirements section like Depends on X version Y.
The fourth required section is Contributing. This can be replaced by the use
CONTRIBUTING file though. Explain how to hack your library, how to
report bugs or how to submit feature requests. It is important to be exhaustive
Explain the rules to avoid commenting every single line in Pull Requests you
receive. Point contributors to the right tools such as linters or compilers.
You MUST add a Testing section too. Explain how to set up the test suite, how to run the functional tests, and the tools that people may have to install.
Optionally, add a Credits section if you use third-party things or if you want to list your contributors (that could be an Authors section though).
Last but not the least, add a License section!
Here is a template:
project-x ========= project-x is a better way to achieve this and that, by leveraging the new API, blablabla. ## Usage ... ## Installation ... ## Requirements ... ## Contributing See CONTRIBUTING file. ## Running the Tests ... ## Credits ... ## License project-x is released under the MIT License. See the bundled LICENSE file for details.
As you can see, I introduced two files in this template:
CONTRIBUTING. I already covered the
CONTRIBUTING file while describing
the Contributing section. The
LICENSE file contains the license you will
choose for your project, but which license?
I won't compare all licenses, browse tl;drLegal instead. It provides useful information related to Open Source licenses, with simple words.
I tend to use the MIT license as it is very liberal. My advice here is to look at your community, and choose the most appropriate one. For example, in the Symfony2 (a PHP Framework) community, most of the related projects (bundles) are released under the MIT license. However, Java projects are often released under the Apache License 2.0.
According to recent reports, most GitHub projects don't have an Open Source license. That is bad! You MUST have a license, even if it is the Beerware license.
As mentioned on Hacker News, choose your license carefully. Also, don't make up your own or just state that it's public domain. Public domain is actually not a well-defined concept internationally, and means different things in different countries.
Even if you now have a well-documented library and a license, you can't dominate the world yet. In the following, I give an overview of what I consider important in Open Source projects.
Write Tests & Automate
Open Source projects are a way to write beautiful code as there are no deadlines, and no "customers". Keep in mind that your projects show what you are able to do. As a developer, your library is your business card.
Write tests, a lot! How do you expect people to contribute to your library if
you don't provide a test suite? So, write tests, and use Travis
CI. It is all about adding a
describing how to run your tests. It is another way to document how to run the
Add a status image to your
README file too.
It is important to use the right tools for your library. Look at your community again, and choose the tools people tend to use. In PHP, we use Composer as dependency manager. Don't waste your time with PEAR or anything else, use Composer. If you write a Node.js library, register it on npm. For Ruby developers, distribute your library as a gem. For C# developers, use NuGet.
Another example, in Symfony2 it is considered good practice to add documentation
Resources/doc. It is a convention. Don't duplicate your documentation.
Add a link to quickly jump to this folder on your
README file instead.
Managing Issues & Releases
If you use GitHub, don't waste your time with the Wiki. I never found a decent
workflow. Either use the
README file for your documentation, or use Read The
Docs to host it in case you have extensive
documentation. Use GitHub Issues to manage milestones, and rely on labels to
sort your issues.
Also, try to reply to all issues, as soon as possible... But be careful, and manage your time. Be nice with everyone, and take time to help newcomers. It is worth learning how to maintain a successful open source project.
Another advice would be to release often by tagging versions periodically. Talking about versions, please follow the Semantic Versioning Specification.
Then, maintain a
CHANGELOG file to help your users identify changes. If you
break backward compatibility, write an
UPGRADE file in order to explain how
You Need Feedback!
The main reason why I open source a lot of projects is that I can learn a lot thanks to user feedback. So you need feedback, I need feedback, everyone needs feedback! Share your project on Twitter, Hacker News, and so on. Spread the word! People must know about your project, not because it is awesome, but because people can comment on it.
Use GitHub pages to create a website for your library, buy a domain if you want.
Remember the world domination plan? That is pretty much all you need to achieve this goal. We never know!
Once you dominate the world, it is important to enroll new people to help you. That is a terrific experience! And it will give you more time for your other Open Source projects (also known as your new world domination plans) :-)
Open sourcing a library is not just about publishing the source code. You need to add a few things to make it usable, and enjoyable. Documenting your projects shows that you are able to teach, and that you are able to find the right words to explain something. Also, it shows that you care about what you do.
Don't forget to add tests in your library, if you don't do that at work, do it at home. And don't forget the license too, no excuse!
It is really cool to open source projects, but avoid the NIH syndrome. Contribute as much as you can, open source things that don't exist.
- MUST have a
READMEfile including a name, a description, and the following sections: Usage, Installation, Contributing, Testing and License;
- MUST have a license that is visible;
- MUST be tested;
- MUST be standard or MUST fit your community habits;
- NEED feedback;
- MUST be nice;
- SHOULD enroll people.
This post is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.