Friday, May 15, 2009

Great software writing can be Mercurial

Cross-pollination works. For example, I think infrastructure groups can usefully adopt several developer tools and mindsets. (I've talked about this before.) One of these is automated build & test systems. Another one - and the necessary foundation for automated builds - is revision/version control.

And I'm usually interested in comparing different approaches to solving a problem I'm familiar with. I find seeing the differences in the approaches gives me a better understanding of the underlying problem; it helps to abstract what is perhaps an implementation artifact and what is inherent to the domain.

So when I spotted on TouchCode's Google Code wiki that Google Code is now supporting yet another version control system, Mercurial, I was intrigued enough to go learn more about Mercurial, how it differs from and tries to improve upon Subversion and Git.

Did I mention that I'm easily distracted by bright, shiny knowledge? There's a rule I follow strictly: when I am playing, I'm allowed to shoot off into completely random digressions if I want to!

Conveniently, Mercurial: The Definitive Guide is available online, Free. Thanks, Bryan O'Sullivan!

What a delightful surprise to see it looks like the makings of a good software book, too! From the Preface:

Technical storytelling

A few years ago, when I wanted to explain why I believed that distributed revision control is important, the field was then so new that there was almost no published literature to refer people to.

Although at that time I spent some time working on the internals of Mercurial itself, I switched to writing this book because that seemed like the most effective way to help the software to reach a wide audience, along with the idea that revision control ought to be distributed in nature. I publish the book online under a liberal license for the same reason: to get the word out.

There's a familiar rhythm to a good software book that closely resembles telling a story: What is this thing? Why does it matter? How will it help me? How do I use it? In this book, I try to answer those questions for distributed revision control in general, and for Mercurial in particular.
And right off the bat, a great explanation that I'm going to point lots of people to in the future:

Why use revision control?

There are a number of reasons why you or your team might want to use an automated revision control tool for a project.
  • It will track the history and evolution of your project, so you don't have to. For every change, you'll have a log of who made it; why they made it; when they made it; and what the change was.

  • When you're working with other people, revision control software makes it easier for you to collaborate. For example, when people more or less simultaneously make potentially incompatible changes, the software will help you to identify and resolve those conflicts.

  • It can help you to recover from mistakes. If you make a change that later turns out to be in error, you can revert to an earlier version of one or more files. In fact, a really good revision control tool will even help you to efficiently figure out exactly when a problem was introduced (see the section called “Finding the source of a bug” for details).
  • It will help you to work simultaneously on, and manage the drift between, multiple versions of your project.
Most of these reasons are equally valid—at least in theory—whether you're working on a project by yourself, or with a hundred other people. 
All cool so far, right? But check out what Bryan did  - this is so self-referential, I just love it to pieces:

About the Example Code

This book takes an unusual approach to code samples. Every example is “live”—each one is actually the result of a shell script that executes the Mercurial commands you see. Every time an image of the book is built from its sources, all the example scripts are automatically run, and their current results compared against their expected results.

The advantage of this approach is that the examples are always accurate; they describe exactly the behavior of the version of Mercurial that's mentioned at the front of the book. If I update the version of Mercurial that I'm documenting, and the output of some command changes, the build fails.
Anyway, I'm still reading, and I think I may well give Hg a shot for my next project.

1 comment:

  1. Aha, Google wrote up an Analysis of Git and Mercurial when they were deciding what distributed CVS to add to Google Code as next alternative to Subversion.