Make Sure Your Open Source Project Actually Builds!

I suppose this post could apply to any project, but since I like to dig into open source projects quite a bit that’s what I’m focusing on.

How hard is it to bring a new developer into your open source project?  Outside of the core IDE of choice for the language, what else needs to be installed on the developer’s machine in order to get it to build?  If you have to tell them to install a few versions of .NET, Ruby, Python, and then a slew of other tools, why not just put it in a README file at the root of the project instead of relaying that information to every developer who has to ask you directly?  If I can pull the source down from the repository of choice, I should be able to get up and running with the code base without having to spend even an hour trying to figure out how to build the project.  If it’s a .NET application, I would expect to open it up in Visual Studio and press Cntl+Shift+B and have a successful build.  Even better is if there’s a build script and some batch/shell script that will run the build.  That way the developer can find out if the way they’re compiling the code is the same as what’s available as an official release.  There’s been a number of projects that work 99.999% of the way I need it to, but there’s one small feature I need to add or comment out and recompile the rest to fit my need.  If your official releases are strictly Visual Studio builds, then mention it.  Yes that means *gasp* documenting your project.  Heaven forbid.  A little 1-2 line README file that’s not likely to get out of sync of the code isn’t going to kill you.

Even worse is if a 3rd party library needs to be installed for the code to compile correctly.  Include it in the repository if possible (when licensing doesn’t prevent it), or at least have a README or REQUIREMENTS type document that lets me (as a new developer project) know what else I need to install.  Say you’re developing a WPF project, and you’re using a Codeplex project full of controls, then let me know to install it.  Don’t let there be a missing reference in Visual Studio for me to spend extra time figuring out what it’s supposed to be.

All in all, I suppose this really boils down to asking “Can you build your project on another machine in one simple step?” or “Does your project pass #2 on The Joel Test?”  It really shouldn’t be that hard?

If you’re going to start a new OSS project, do your research first

I’m a fan of open source software the same as many developers.  So much so that I like to subscribe to the RSS feeds from sites like Codeplex to keep an eye out for new and interesting projects.  I have to admit that there’s some cool projects that look like they could have some real potential, but the I’m noticing that the projects fall into one of the following categories (ordered by perceived number of projects)

1. So-and-so’s utility class(es)
2. So-and-so’s school project.  This includes user group projects.
3. Control(s) for a popular product (typically Sharepoint)
4. Contrib projects to existing projects (both open & closed source)
5. Port of another project (typically projects that are in another language)
6. Proof-of-concept project
7. Other minutia that generally has only one-off type usage.

The reason for this post is the prevalence of projects that fall into number 5 above.  I’ve come across a number of projects that are ports of Rail’s Migrations into the .NET space.  The problem as I see it is that a couple of them were started up because the originator of the project wasn’t even aware that other projects existed.  I’m all in favor of the competition is best for the consumer approach, but having multiple projects that do nearly the exact same thing because neither was aware of the other just creates lots of rework for no good reason.

So if you’re thinking of starting up an open source project, please spend at least 10 minutes flexing your Google-fu muscles to see if a project already exists that can fit your needs.  If there are similar projects, but lacking some key features, at least contact the developers behind the project to see if it’s on their list of features to implement.  If they’re not going to implement them, then either code the feature up and contribute it back to the project yourself, or fork the project and go down your own path with it.  If you can’t find a project that’s going to fit your need, then by all means do your own project, but at least acknowledge similar projects and explain how yours is different.  Not only does this help show that you’re intentionally going down a path that’s probably been trodden before, but it also establishes who your arch-enemy projects are going to be.  Don’t be afraid to have an arch-enemy project as it gives a great frame of reference in what you’re looking to achieve with the project.