Read this first!

Before you do anything else, read this blog post about Why Hackathons Suck (and don't have to). It's important to approach the hackathon concept with a dose of humility and realism about the costs you're imposing on the OpenMRS community, and compare these to the benefits you'll be bringing.

To summarize: the effort that the OpenMRS community spends getting tickets ready to work, and helping to onboard new volunteers, is greater than the value those volunteers will provide within any one hackathon. The OpenMRS community (and as a result, the hospitals and clinics that use the system to treat patient) get a net benefit when (a) a hackathon volunteer sticks around the community and spends more time over the coming months doing tickets, or (b) if you organize a regular series of hacking events, where regular contributors help onboard newcomers, and become familiar with the codebase.

So as an organizer, don't just think about how organize one hackathon, but think about how you can do so in a way that maximized the benefits it brings to our open source community and on the ground implementations.

Specific Advice

Most of this is attributable to notes from Wolf Schlegel and Tobias Vogel, who have run many hackathons. (Thanks!) And "you" doesn't necessarily)

It helps to have a team organizing a hackathon, rather than just one person, e.g. a project manager and a tech lead

Make sure you know how to set up the technical environment. There are some recipes on the OpenMRS Wiki, but these are not always up to date with the latest releases of maven, git, eclipse, etc, so try them yourself.

Setup is sometimes an elusive beast. It might work perfectly on 10 machines, but then inexplicably fail on the 11th.

Have people set up their machines ahead of time, or else you'll end up spending half the hackathon doing setup.

Someone in the room needs to understand the architecture and design of OpenMRS, or everyone will waste time flailing around.

Wolf did this by just starting a ticket (before the hackathon!) and learning by doing.

Aside: you may need to establish a relationship with a product owner. The ticket itself may not be perfectly written, and if you're putting in effort, but what you're implementing doesn't seem quite right, talking to the reporter (e.g. by Skype) can clarify things and improve the output.

During a hackathon, you need a way to answer any domain question. (Otherwise you'll get blocked on communicating over time zones, because whoever reported the tickets you're working will not be sitting at a keyboard exactly when you're doing a hackathon.) One approach is to learn as much as you can about the domain yourself. Another is to ensure that some experienced OpenMRS community member can be online to answer questions during the first half of your hackathon.

Don't be discouraged or distracted if in some spaces the test coverage and code quality looks bleak; the system is in production and building the systems happens by optimizing the use of limited resources. You should approach things with the viewpoint "I'm working on a ticket, and I can see 10 other things I'd like to improve/refactor. But my priority is to commit the requested feature or bugfix. Secondarily I can share suggestions for other improvements and refactorings, and let the OpenMRS community do the triage and decide what should be done next."

People are interested, they are passionate and excited, and they are making time from their schedule to attend your hackathon. But once they leave it's natural that their interest will wane. Try to organize things to maintain people's interest over time.

At the very least, if people got halfway done working on a ticket, ask them to commit to finding spare time over the next week to finish it off.