I did something cool a couple months ago in my work on Adium, and wanted to share the story and how to do it in your own open-source project.

---

A couple months ago, I started a branch in the Adium repo for “project parallelization”. The idea was to see what I could do to the Xcode project to make it more easily parallelizable: Xcode will parallelize the build process on a multi-processor machine, but some things (mostly shell scripts) are a bottleneck, being inherently non-parallelizable, so I wanted to remove as many as I could and optimize the ones I couldn’t.

A quick look over the Xcode project revealed that (at least in Adium’s case), this would be a rather big job consisting of many different operations. So I decided to keep a to-do list, and I decided to maintain it on the Adium wiki rather than in a local file.

The result is the ProjectParallelization page. It worked very well: most of the work was done in a few days. It also was very popular with the other developers, because everybody knew what I had done and was going to do as of the present time. Everything is lain out on the page; this promotes openness, since everybody knows what you’re doing.

I’m very happy with how it turned out, will do it again for any future branches, and recommend that others do it.

---

How-to

A good way to perform any large task on an open-source project is to maintain a journal on the project’s wiki (in addition to creating a branch in the version-control repository). This has two benefits:

• It promotes your own productivity. You needn’t keep everything in your own head: Page everything out to a to-do list in the journal and maintain the list by crossing off items and adding new ones.
• It helps other developers on the project understand what you’re up to.

Your journal should include:

• A short one-line summary of the purpose of the branch.
• A link to the branch.
• A longer “Rationale” section describing the purpose is fuller detail. Where the summary above summarizes what you’re doing, the Rationale section should provide a backstory.
• A to-do list.
  • Cross off items that have been done; include revision numbers (e.g. “DONE in [42]; REVERTED in [44]”). Ideally, you’re using something like Trac where these are linkified.
  • Nested items are encouraged.
• Once the branch’s purpose has been fulfilled, analysis of results.

This entry was posted on Sunday, November 19th, 2006 at 12:06 AM by Peter Hosey and is filed under Uncategorized. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.