There is something thrilling, rewarding, and even scary about getting your first open source project out there for the world to see. But where do you start? How do you end up with a project that is useful to the community?

As South Africa celebrates the Day of Reconciliation, a day to promote unity throughout the South African community, across all languages, traditions, races, cultures and genders. A day that we focus on being one as a country, despite all our differences, I can’t help but see it as a perfect day to share some of my personal experiences about open source with you.

Getting involved in open source has been one of the most rewarding things I’ve done. Seeing other developers blog, tweet and recommend one of your projects is priceless. Lets dive in to a few tips I believe is required to make any open source project a success!

A Selfish Act

The first open source project that I consider a success was my Laravel Migrations Generator. We started rewriting one of our legacy applications in Laravel at my company. The database had more than 100 tables, and some tables had more than 50 fields. It would’ve taken forever to rewrite everything by hand, and would’ve been very error prone.

I decided to look around to see if there was something already. I found a few options, but none of them could replicate our legacy database with 100% accuracy. After trying them all, I decided to write my own.

I didn’t try to create an open source project, and at the time I didn’t even know I was going to open source it. I was just looking after my own best interest, trying to solve my own problems.

While I was searching for a tool that could generate these migrations, I came across a lot of people asking for one. So once I was happy with the results, I decided to create a Composer package and open source it. This is a scary step, and I must’ve gone through the code 100 times to make sure I didn’t do something stupid. But the important thing is I did it. I pushed the code to Github for all to see.

Choosing a licence

Unlicenced code is unusable code. Without a license you are the only person allowed to do anything with the project, which is probably not what you want.

If you want to allow others to use your code, you’ll have to decide on how you want to allow them to use it. Have a look at choosealicense.com if you’re not sure or head over to opensource.org/licenses for a list of open source licenses. I generally use the MIT or GNU GPL licence for all my projects, but make sure you understand the full implications of the licence before adding it to the project. — Thanks to Andreas for pointing out the importance of this section

Easy easy easy!

To get people to contribute to your project, they need to first use your project. The easier it is to use, the more likely it is that someone will use it, and the more likely they are to contribute later.

If you manage to build something that is a thousand times better than any existing solution, and has the most beautifully written code, but takes a day to understand and set up, chances are people will end up using the less effective solution, mainly because they got it working in under 10 minutes. So the first and most important thing is, make sure it’s easy to find, use, set up and understand.

Easy to find and install

I’d highly recommend that you put your code on GitHub. Bitbucket and GitLab are great tools, but not everyone is familiar with them.

Secondly, make sure you use a package/dependency manager for the tool you’re using. Examples might be Composer, NPM and the WordPress Plugin Directory. Just make sure it’s as natural for the user as possible to install your project.

Easy to set up

Think about when you want to use someone else’s project. You want a short description on what it does, and then some copy/paste installation instructions, and perhaps a more detailed explanation as to what it does below.

Add a README.md that gives a short description of the project, and then lists everything a user needs to do to get it installed and working.

Easy to use

How many times have you installed something, and 10 seconds in it gives an error. Depending on the project, you might just decide to uninstall it and try another one. Similarly, if you read the documentation, and you need to jump through hoops to get it working, you might decide to rather jump to another solution.

If they can easily get past this step, and it seems to be doing more or less what they expect it to, chances are, they’re hooked. They are now going to use it in their current project, and hopefully tell their friends about it!

Marketing

I’m sure many of you have found a hidden treasure before – a great project that simply no one knew about. It doesn’t matter how good your project is, or how great the code is; if no one knows about it, it doesn’t help anyone.

I’ve spoken to other developers about this, and some have said: “I’m not that kinda person, if people want to use it they can, and if they don’t, they don’t”. At first these people seem very humble. They’re not trying to sound cool by telling everyone they just wrote this awesome tool. But sometimes it really is an awesome tool, and people need to hear about it. Simply putting it on Github is not enough.

How you may ask? If it is solving a common problem, it may have already been raised on Stack Overflow, forums, IRC, Twitter, etc. Find those questions and start answering them by promoting your project.

“You want me to shamelessly boast about my project, by spamming it all over the internet?”

Spam is something people don’t want. If your solution works, and helps them solve a problem, then it’s definitely not spam! But yes, I want you to let the world know that you have built a successful project, and that you think it’s worth looking into.

I started Googling for “Generate migrations from existing database”, finding questions, and answering them with a link to my project, adding a disclaimer that I am the author. I did this once or twice, unsure if my project really was any good, in fear of criticism. After I received a positive response from the community I went back and probably answered a dozen similar questions, getting my project out there.

Two months later, I saw someone else recommend my migrations generator as a solution on IRC in #laravel. I later found a blog post written on installing and using it, with step by step instructions and screenshots. After a while people started raising issues, and submitting PR’s. This was a great time for me!

The code must be perfect

I think people generally put way too much emphasis on “good code”. I think a working solution is much better than no solution, and bad code is much better than one that’s difficult to use.

Sure, the easier it is to read and understand your code, the higher the likelihood that someone will contribute, however, as you can see, this is by far the least important step. There’s a much bigger chance that someone will contribute if it’s easy to use, than if the code is good, because no one contributes to projects they don’t use.

Working with issues and PR’s

Think back to when you created issues on other projects, or have been brave enough to submit a Pull Request. For you, it’s a big moment. Will the maintainer respond? Will they accept your PR. You end up refreshing the page every 5 minutes just to see if something changed. And it’s very important to keep this in mind when going through issues and PR’s.

If someone has created a PR, it means they have put effort into it. It could very well be their first PR ever. Think how you would want someone to respond to make you want to contribute again. You want someone to recognise your work, your effort, and you probably want to see it 10 minutes after you opened the PR.

Be kind. Always thank people for creating issues and submitting pull requests. They took time out of their day to help improve your project!

Always try to accept a pull request. If the code is not up to the minimum standard you’ll accept, help them to improve it. Mentor them, and lift them up. Do everything you can to get those commits merged in. It’s a great feeling for a developer to get their code merged into a public open source repo and, chances are, they will do it again.

If it’s implementing a feature you really can’t accept, explain it to them. Tell them you’re sorry for not accepting it, but you don’t see it as part of the project. Also, recommend opening a ticket suggesting the idea, before spending hours of work on it, and urge them to submit again. Perhaps propose an easy task they can help you with.

Conclusion

Open source, in some way, is a lot like running a business. For it to be successful, you need a product that the community would be interested in. You need to market the product, work with people, and make tough decisions about accepting or declining pull requests, all while trying to keep everyone happy. The main difference being that you’re doing it for the community, with the community, and everyone is hoping you succeed!

I hope this post inspires you to release one of your projects as open source, and please, do tell us about it 🙂