There you are, you just opened your laptop and got the inspiration to write a bunch of code and release it open-source: sounds quite simple and easy, but you should always keep in mind a few rules that are going to boost your “creature” before releasing it to the public.
Documentation
If it’s not documented, it doesn’t exist
That’s probably the biggest truth of OSS: if you don’t provide a good README or some more complete docs it’s gonna be hard for people to be able to understand the value of your software, or to even give it a try and get straight to the point.
ReadTheDocs is an awesome project that lets you create beautiful documentation for your projects for free but, if you want to keep things simple, github’s pages or wiki might be what you were looking for.
Packaging
Do never forget about shipping it in a way that makes it easy,
for others, to install your software in a matter of seconds:
a great example, in this sense, is NPM
for NodeJS, which lets you install modules with a simple npm install moduleName.
This is possible with basically any platform out there: PHP has Composer, Ruby has Gems and Python uses, if I’m not wrong, pip (there are many other examples, like CocoaPods and so on, but the ones i mentioned seem to be most mature and stable nowadays1).
Visibility
I don’t know about you, but I always have a strange feeling when I open a link to a project and it’s hosted somewhere like, let’s say, GoogleCode: I wouldn’t say that your choices are limited, but whenever you’re gonna pick a hosting solution for your library it’s though to look anywhere but Github, as they have:
- great user experience
- good platform for engagement (pull requests, comments)
- love for the OSS world
- awesome vision and communication
- tricks to make your experience fabolous
If you want to look for widespread alternatives, though, you might find Atlassian’s BitBucket the most serious competitor of GitHub.
Coding standards
Follow the coding standards that are en vogue in your community: for example, in PHP you got the PSRs, which are guidelines for writing your code, created by the PHP community itself (or – at least – its most prominent members).
Writing code with your own standard will just make it harder for the ones interested in your project: you want them to be able to focus on what you’re offering and to discuss it, not to spend too much time reading commas and brackets in weird positions.
Tests
Automated tests are probably a must if you plan to have people relying on your software, especially if what it does is not contained in very few lines of code (and in any case, even there tests are so much helpful).
Tests will also help you evaluating contributions from the community: other devs will get interested in your software, find a glitch, fix it, add a test and send you a pull request. At that point you only have to check the code, because the tests are gonna take care of the build on their own.
Nowadays you don’t even have to boot your own machine to run the tests: hook your library with travis-ci and you’re done!
Recap
Before announcing your latest project to the world, I would:
- put it on github or bitbucket
- write a decent
README.md - create the package on the most suitable package manager
- review the code to check everything makes sense
- add tests and let them run on Travis
I’m sure I might have missed something… …so you tell me, what are your golden rules?
- Besides, probably, apt :) ↩