Salvatore Iovene

Inspired by a cer­tain patch that hit a darcs repos­i­tory to which I con­cur, I would like to talk about one thing that devel­op­ers don’t seem to get very often, when using revi­sion con­trol sys­tems: the struc­ture of your files in the repos­i­tory should have noth­ing to do with the log­i­cal units that make your patches, or with the com­ment of your patches them­selves.

Yes­ter­day, I saw this patch hit the repos­i­tory: “Adding Cloth.h to the repo”. The patch was adding an empty file, named Cloth.h. What’s wrong with this? A cou­ple of things:

1. The patch adds no log­i­cal value unit to the repos­i­tory, but merely a tech­ni­cal value, i.e. an infor­ma­tion about the con­tent of the repos­i­tory itself, which is, then, absolutely redun­dant, as you could retrieve that infor­ma­tion in a sep­a­rate (and more proper way), which of course depends on the revi­sion con­trol sys­tem you are using. Indeed it was just a tech­ni­cal infor­ma­tion. Fur­ther­more, the fact that the file was added, would have been there and obvi­ous also with­out hav­ing to ded­i­cate a sin­gle patch to it.
2. The com­ment (“Adding Cloth.h to the repo”), once again, doesn’t make any log­i­cal sense of its own, as adds an infor­ma­tion that was already avail­able using the revi­sion con­trol sys­tem tools.

What is a bet­ter way to do that? A patch named “Pre­lim­i­nary sup­port to clothes”, which would add the file Cloth.h with its con­tent, even if not yet func­tional, makes per­fect sense. It means that you’re adding some log­i­cal value to the repos­i­tory, and the value that you’re adding has noth­ing to do with the way that value is rep­re­sented (the file Cloth.h), or that it’s being actu­ally added to a repository.

In other words, the form and con­tent of patches should not only rep­re­sent sin­gle units of implicit log­i­cal value, as dis­cussed ear­lier, but should have no aware­ness what­so­ever of being part of a revi­sion con­trol sys­tem, or being uploaded to repos­i­to­ries, con­tains file, or even being patches at all!

Read more ver­sion­ing tips here.