Happy new year, everyone! This is Karen Rustad, OpenHatch’s former scribblemonkey and present grad student and aspiring coder.

OpenHatch’s new mission statement essentially states that the point of OpenHatch is to lower barriers to entry for new contributors to open source software (whether it’s their first or their tenth FLOSS project). Prospective contributors have to overcome confusing jargon, a fear that their effort might not be welcome, and/or a lack of personal connection to the free software community. Each of the tools OpenHatch has developed — the volunteer opportunity finder, the people and project pages, the automated skillbuilding ‘missions’, and so forth — has been meant to address one or more of those obstacles.

To continue in this vein, this semester, Asheesh and I are planning on building a new tool for OpenHatch users specifically to assist new technical contributers. We’ve dubbed it the ‘buildhelper’.

A mockup drawing:

(I already have some better ideas for the icons, but they’ll have to wait until I return home to my drawing tablet and Photoshop-running computer.)

The buildhelper is a templating system for projects to list out on an OpenHatch page all of the steps necessary for a new contributor to get a working development environment for that project running on their machine. The steps should cover checking out the project’s code, installing dependencies, running the development server (or analogous, depending on the type of project)–everything necessary for a completely new developer to be ready to test code and start writing patches for bugs. It’s a form of documentation, only targeted at editors of your project rather than users.

Each step has the basic name/description of a step, a more detailed explanation (if necessary), a link (if necessary, e.g. to the relevant git repository), an estimate of how long the step should take, a help button that links to either a relevant OpenHatch mission or other background-info tutorial that a project favors (optional), and a “crap, it didn’t work and I don’t understand why” button that takes the user to the project’s IRC channel (the dev channel specifically, if the project has more than one), where they can solicit help from more experienced project volunteers and point to the specific step where things went wrong. As a user completes each step, they can check them off one by one; if necessary, they can leave and come back to the buildhelper steps later and it will still remember their progress. Once the user gets to the end, we then congratulate them (yay!) and link them to the project’s list of bitesize/good-for-newcomers bugs so they can get started hacking right away.

It should be extremely obvious, but I’ll say it anyway: the buildhelper can’t do all the work involved with getting new developers up and running. In order to be useful, projects will need to put in a great deal of effort: filling out the templates with accurate, precisely-worded instructions; accounting for different operating systems or other environmental quirks; and making sure that when unsuccessful wannabe-contributors stumble into their project’s IRC channel, there are helpful humans to answer their questions. Additionally, this tool doesn’t cover things like code style guides, patch submission guidelines, or other information new devs are likely to need (though providing a space to link such resources at the end of the buildhelper might be a good idea!). Free software development is fundamentally a human-based, community-oriented activity, as much as we sometimes might like to pretend it isn’t. 🙂 There’s just no getting around that. But by building a clear, explicit place for prospective developers to seek out this kind of assistance and providing suggestions and specifications for current project maintainers on how to fill out the buildhelper template in a helpful, useful way, we hope that this tool will make communication between fresh recruits and old hands much easier.

The current plan (after some preliminary HTML mockups and background Django coding) is first to make a buildhelper document for getting started on contributing to OpenHatch (eating your own dog food–fun and expedient!) before working with other projects and (eventually) making an interface for filling out and submitting the buildhelper template open to all FLOSS. This will take months, at least, though mainly because I’m in school full-time. But hopefully it’ll be worth the effort in the end.

Anyway, we would love some feedback on the buildhelper as an idea. Could you see such a tool as being something useful for your project, that you could point new contributors to? What features would you like to see? What are some of the common stumbling blocks you’ve encountered when you (or people you know) have tried to get involved with a new project for the first time? Were there assumptions made by projects (or individual volunteers) that made getting started harder, or particular communication problems? Or are Asheesh and I completely nuts for wanting to build this? Let us know!