Grok Programming

Over the last ten years or so I and my family have benefited greatly from open source software.  For the most part Spring and Hibernate have made the biggest direct impact on my career but there have been countless other projects too numerous to name that have helped me along the way.  I have nothing but respect for those folks that work away all those hours to give away something that is useful to other people.  So while I may be a bit blunt and rude here just keep in mind this paragraph.

I have been looking for a place to give back to the Java open source ecosystem for a while now.  In that quest I’ve downloaded and looked over a ton of open source projects.  Most of them suck when it comes to initial buy-in costs on developers who might just want to give some of their time to the project.  There are a lot of us out here that would love nothing better than to help you out on your project if only trying to do so wasn’t so painful.  Let’s take a look at what I’ve seen on where open source projects go wrong and start driving potential contributors away instead of attracting them.  I’m also not going to name the guilty parties (after all these people are honestly working hard on their pet project too) but I will call out one that does a good job.

Your open source project sucks if…

…building the project is so retarded it makes Stephen Hawking cuss
In the last few weeks I’ve pulled source from a ton of projects whose build instructions amounted to:

1. Pull from SVN/CVS/Mercurial/Bazaar/Git
2. Dude, ur a hax0rz now!!!!oneelevenone!

Take some time to explain how in the hell a newbie is supposed to get this project up and going so they can starting looking around to contribute.  If I look up after checking out the source and the clock’s little hand has moved while trying to figure out that I was supposed to run “ant build pleasegod -Dtest=john3:16″ to have the initial project actually work then it sucks.  You are bleeding away potential developers because we don’t want to jack around with this stuff.  Clean up your build instructions, automate as much as you can, and put a quick rundown of what needs to be done on the project’s website.  Simple.

Run over and take a look at Seam.  They have a few steps beyond just grabbing the source but it is short, sweet, and it works!  I know some will say that JBoss is paying people to write these instructions but seriously…they’re one freakin’ page long.  One page!  All open source projects should be able to crank out something like that without breaking a sweat.

…source control, issue management, forums / mailing list, and/or automated builds are things you read about once in a magazine
You won’t get people to even download the source to your project if we can’t see that just the basics of having a distributed development effort are in place.  To be honest I’ve only seen this once and I’m not totally sure it wasn’t a joke.  But still, developers looking to join a project really do want these base level tools in place.

…the number of completed builds can be counted on one hand but you need an abacus to keep up with the broken ones
If I, as a developer just walking up on your project, has to tell you that your project’s “nightly” builds are broken and have been for three weeks and it comes as a shock you should quit. I’ve had this happen a few times now and I’m sorta stunned it happened at all. Basically after getting the project up, having a problem, and then wandering out to the automated build reports and finding no working builds I hit the road. This tells us that either everyone on the project is too busy to pay attention to something pretty important or the project itself is dying a slow, painful death.

…if you’ve created the project favoring a particular development environment but don’t tell us
Look, it is your project so you can do what you want when it comes to the tools you want to use.  Build the thing from the menu in Eclipse if that warms your pants (the rest of us will laugh at you though).   But at least tell us about it!  Most of the developers you might actually want do not really give a crap about the development environment that the project is slanted towards.  Some of us might even submit some changes that help out moving it to other environments.  But having spent time trying to force some project into what I could only guess was what tools the dev team decided to use makes me just move on.

…if finding the Ark is easier than figuring out what your project needs
When a potential developer goes to help out on a new project they have no clue what needs to be done, what has been rejected as bad ideas already, or what half of the issues in the issue tracker even mean. Keep an updated - easily found - list of high level “This would be really cool if….” out there. It doesn’t have to be glamorous work since most people getting involved in an open source project understand there is a bit of trust that needs to be earned. Be honest, open, and try saving some the things that look like good learning experiences for those noobs when you can.

…if trying to get familiar with your project’s community is less fun than watching three hours of Carrot Top
Good god, Carrot Top has a fan club.

You’re not going to get people to flock to your project if simply by them simply saying “Hey, I’d love to help out” gets flames in return that would make Gavin King proud.  There are very few open source projects with the inertia that can keep people around when the community stinks that bad.  You need to ensure that while healthy debate can flourish that blatant rudeness is actively discouraged.  If noobs are asking the same questions on the forums/mailing list over and over that’s a pretty good sign to spend some time setting up a FAQ or a sticky post covering that stuff (hell, set it up as a “This would be really cool if….” item).  Most people wanting to join a project really don’t mean to ask the same freakin’ question the last twenty people did.  They just don’t know any better.  Cut them some slack.

Of course, if there happens to be an “inner circle” of people running the project and the rest of us are just passengers on the ship then you probably don’t give a damn about getting new blood into the development process anyway.

So all this adds up to taking a look at your project and actively spending effort to keep the barrier of entry to it low.  Spending a little time fixing these broken windows tells us you really do care about the project and we’ll be understanding when things aren’t going so smoothly in return too.

I’m still looking around to see where I can fit in, help out, and make a difference.  If you happen to have a pet open source project that you think I might be able to lend a hand out on send me an email or leave a comment.  Even if it doesn’t work out maybe I’ll know someone who is a better fit.

Chris java, rant, software development development, java, open source, projects