How to Run A Successful Open Source Project
Github has thousands of open source projects and tons of abandoned code and while it can be hard to tell the difference between the two from just a glance at their commits, there are quite a few thing that differentiate the two.
Between being a avid user of open source from running a Linux desktop to Linux servers and cloud instances, I have looked for certain things in the software I install and use and below is just a few of the things I do in my software project and well as look for in the software I use on a daily basis
Good Documentation
Your documentation should be easily accessible and simple. Don’t overly explain things with technical diagrams, ERD’s, etc. I love these… but most users want to get to the meat right away and start configuring and installing.
Also break everything down and make it searchable or easy to find by top level areas.
Finally, be as precise as you can. Walk through every step of installation of your project yourself. I suggest doing a full devops install for your project so you can get an idea of all the necessary steps that you will need to document.
Easy Installation
The simpler the installation and running process, the better. Todays users are lazy as hell and don’t like to do ‘makes’ (lazy bastards), they want everything handed to them ready to go. And who can blame them… I hate doing ‘makes’ to!
Build install scripts, executables, and have versions of your project downloadable from an artifact repository.
Create A Community
Your open source project should have multiple ways for people to talk to you (as well as to others):
- project issues and pull requests
- project forum
- website contact form
These are all redundant in ways as people will use what they want and what they are comfortable with but the more ways you can provide to be contacted and for people to talk to each other, the more people will ask questions… and those questions in turn provide ideas and ways to improve the project and documentation, etc etc.
Create places for conversations to happen and they will just start to spawn from their. Do not limit communication or it will begin to die (ie Slack)
NOTE: I know I will get shit for ragging on Slack but if you can’t search it, if you can block people from entry, it is not ‘open’ and it does not BUILD community… it is a WALLED COMMUNITY; Only ‘certain people’ are allowed in to the community. So it is not a ‘community building’ tool. Good for internal teams but not for open source.
Well Tested
I am not a fan of unit testing and I make that known but I absolutely INSIST on integration testing! In modern architectures, everything is distributed and so integration tests are absolutely crucial especially when doing devops.
A well tested project will be able to adjust a couple configuration settings and be able to adapt to any environment.
The more well tested your project is, the more widely used it will become.
Readability of Code
This one is a personal fave of mine. If I can read the code, I can modify.
Some projects deliberately try to make the code unreadable (I think) at times and this makes it hard to contribute back. Of course, the more complex the project, the more complex the code.
It’s not hard to maintain a level of readability in your code since compilers will compile everything the same (unless it’s Python in which case it’s white-space sensitive).
Make your code something that is easy to contribute back to.
Conclusion
Maintaining an open source project becomes ALOT of work over time… but its worth it. I would say it’s worth more than my time at Amazon considering the people I have helped, the patterns I have created and the theories I have helped to prove and test.
You might feel that it is going nowhere at first but it will feel like that in the beginning until you find something to latch onto. Just keep plugging away and coding. Commit something ever day and try to find something to commit everyday whether it be documentation or code or tests.
Eventually you will hit an AHA! moment and it will drive you onward!
