A new way to commit
When writing exploratory code,
I often found myself forgetting to
commit to version-control at the right places. Remembering to commit was
turning into a burden that was making the Zone
find, and so turning me off version-control. And yet, it was illuminating to
go over the big picture of the things I had tried. What I needed was a way to
automate committing at just the right times.
But what are the right times? It's no use to commit on every time I save a
code file — that's too frequent and leaves the history littered with
versions that don't compile. It also gives no hint to the major milestones in
a program's evolution. The answer I ended up with was to automatically commit
whenever I had something coherent to say.
Automating the commit process
My current solution
consists of the
- A file with a special name in the code repository (say Log). Log is
intended to be used as a journal as we work on the codebase.
- An editing environment that does the following everytime Log is saved:
- Commits the codebase (saves a snapshot)
- Appends a tag and timestamp to Log identifying the snapshot
- A command to extract the snapshot corresponding to a given tag.
After using it for a couple of years I find this process has several
- I find myself committing much more frequently, and the changelog (for
that is what Log is) is a lot more coherent, easy to read by itself.
- The extra context makes it much easier to find and drill down into the
state of the repo at a specific point in the timeline.
- Anytime I find myself writing a large comment in the code I now think
about whether to move it to the changelog. Just as accessible, and it reflects
the fact that the comment is valid for a specific point in time.
- Once the larger comments move into the changelog I have a lot more
confidence that my comments are not out-dated. As a result I find myself
more inclined to write comments, which makes the changelog even more coherent
and useful. It's a nice positive feedback cycle and a nice way to encourage
oneself to document code.
- I focus more on leaving a trail of breadcrumbs and less on silly things
like formal design documents and so on. It is the lesson of wikipedia: if you
make the reader's job a little harder (validating what he reads with a little
deduction, putting facts together from different commits), the writer is a lot
more willing to give him meat to chew on.
Rather than more well-defined
maintenance for a specific bug in an issue tracker.