I spoke in the unconference at PHPUK last week, on running an open source project. I thought I would collect together my thoughts into one place before I lose the scratty piece of paper I wrote them down on. I’m not sure I’m the right person to be giving advice exactly, but these are the things that, having been project lead on joind.in for a while, I think are important.

Community

I love it when people share their code, just make something and publish it, but to my mind it isn’t an open source project until it has people around it. There’s nothing wrong with building something as a hobby, but it’s quite different to have people around it.

To allow others to contribute, you need some infrastructure to allow them to see what’s happening and to communicate. As a project lead, you need to monitor/moderate these channels. Joind.in uses mailing lists on google groups, a bug tracker (atlassian offer free licenses for open source projects, which is awesome), and an IRC channel. We also have a blog and a twitter account to make public announcements rather than just talking to “insiders”. We actually also keep different mailing lists – for announcements, for features, and for developers. This saves interested parties such as conference organisers getting bogged down in technical details.

If your project isn’t well known yet, let people know about it. Blog it, tweet it, or post on stack overflow questions where your code solves their problem. It isn’t true that if you build it, people will come – they don’t even know it’s out there to find until you tell them.

README

The only way you’ll ever get code contributors to your project is if they can actually get started with setting up the application. Now, this is “do as I say, not as I do” because if you’ve ever set up joind.in, you probably had to ask a few questions and patch the README file! That said, it is something we’re working on and it definitely helps new contributors to get started as we put these elements in place.

The other problem is that nobody reads the README … I have no solutions for that!

Roadmap

Having a clear vision and wanted features for a project has been really beneficial for joind.in – people suggest things and I can say “it’s on the roadmap”, or point them at the mailing list thread discussing the features, etc. At the moment, we’re working on better APIs, new javascript widgets, showing a more informative schedule and getting CfP functionality into the system.

By coincidence, I know of two separate CfP applications that have been built (with a third planned) NOT as part of the project, which we may integrate against. It would have been good to have them as part of the existing project but apparently that wasn’t appealing to any of those developers – I blame the project leadership entirely but I’m not sure what I’d do differently next time to make that easier!

Code Contributions

These are tricky things – like most open source contributors, I’m interested in what I’m interested in, and it can be hard to get excited about other features or other parts of the system. However, those other contributions are the lifeblood of the project and the project lead needs to review, test, merge and deploy those contributions in a timely manner or risk losing contributors. Even if you won’t be merging the change, it’s really important to say why not and give constructive feedback on what the requirements are for things to be accepted.

In my experience it is a tricky balance between getting contributions that are useful and improve the project, and one-off things that might not be used, and where that contributor will disappear and leave you to support/defend it! Only instinct can tell on this one, but with all pull requests, don’t be afraid to be honest about what you think is in the best interests of the *project*. Just like any other leadership role, you’re not there to be popular.

Transparency

For me this is absolutely the best thing about running an open source project! People can see in to the code, the issues list, the mailing list, and even the continuous integration server. I can ask people to help, pointing at the code that doesn’t work. Sometimes people pop in and tell me I’m doing it wrong before I even realise that there is a problem.

For those people that work on the project alongside me, they can see which pull requests are open, who commented on them saying what, and which were merged and when. I push all the branches I’m working on to my own github repo so when people ask about progress on a feature, I can normally point at what there is (if anything).

Showing all the guts of the project to the outside world might feel like airing dirty laundry (especially on a code base that looks like this) but it has enabled fly-by input from all kinds of people that might not have taken the time to climb the fence into the walled garden. More than once I’ve tweeted for help with a bugtracker link in and had people make useful and informed suggestions in the comments there, that someone else can go on and try out in code. In fact, I sort of wonder how I thought I could ever run a project – especially something like joind.in which is really owned by the community itself, containing their data – without having the inside so visible from the outside. Certainly it has informed how I like to run “normal” software projects!