The big patch theory

It is well known that the free/open source software major asset is the sense of community surrounding each project. That idea is the constant in almost all the promotional videos which participate in the Linux Foundation contest We’re Linux.

A community driven project, exposed to the masses by Eric Raymond in his paper The Cathedral and the Bazaar, has been gaining moment, turning the software development, rather than a isolated, almost monastic, craft work, into a collaborative, openly discussed, engineering task.

All those ideas sound exciting and appealing, but from the trenches, how is it done? How does a bunch of hackers collaborate all together to construct a coherent and useful piece of software?

We could be tempted to think about complex, full solution, software such as forges, distributed revision control software, etc. But I won’t go there. That’s buzzword. From my point of view, the essence of any collaborative software project is the patch.

According the software engineering, an important activity, in the software development process, is the peer reviewing. Even ESR gave a name to it: the Linus’s Law. But the software peer review is not an task done once or periodically, it would be an almost impossible duty, or at least impractical, because it’d imply read and analyse thousands of lines of code. Instead of this, the peer review it’s a continuum, it’s a process that must be carried on during all the code writing.

So far we stated two purposes for a patch file: collaborative software construction and peer review. For the first purpose the activities implied are, from the developer point of view, modifying the code, extract the diff file and hand it out; from the integrator point of view, the application of the patch and keep a register of it. It’s relatively simple process, and it can be automatised in some degree with the help of a SCM software. But there’s hidden trick: the patch must be small and specific enough to survive several changes in the base code, and could be applied cleanly even if the surrounding code had changed since it was created.

Nevertheless, for the second purpose, the process from the developer point of view, is more complex; the crafting of a patch for peer review is not a trivial task, quite the opposite, good patches are fruit of experience.

A good patch has set of subjective and objectives values that the reviewers and the integrator will take in count at the moment to commit it in the official repository. A patch must be small enough to be easily understandable, attack a single issue, self-contained (in must have all it needs to solve an issue), well documented, complete, honour the project code-style, and so on.

A perfect patch must transmit the needed confidence to the maintainer, with a simple glance, to apply it immediately. And only the experience can give this skills. There’s not a Patch 101 lecture, but maybe is a interesting idea.