Thank you, Bazaar designers, for first-class rename operation

[Ben Finney]

(This turned into an essay. TL;DR version: new user unfamiliar with any
DVCS concepts asks me explicitly and unprompted for VCS features that it
just so happens Bazaar is good at, we learn them, and he goes away
happy.)


Howdy all,

Today (Mon 2010-03-08) while a friend was visiting me, he raised the
topic of having trouble with VCS, specifically a CVS repository with
many branches. He'd got himself into a mess trying to merge, and was
expecting me merely to commiserate, not fix anything.

Having some time to fill, I proposed that we should not only fix the
problem, but get him solidly established with a better tool, Bazaar.
This is our story.


The user in question I'll call Brian, though his real name is Malcolm.
(I can't resist a good Monty Python joke.)

Brian mostly does system administration, but uses some of his spare time
hacking on Perl code for various free-software projects. He is writing a
specialised server application for a community organisation, and it is
this project that is the focus of his desire to learn good VCS tools and
workflows.

This most recent project is probably one of the larger systems he has
programmed, and he initially developed it for some months without any
VCS at all; he assumed that, as sole developer, the benefits weren't
worth it. After learning *that* lesson the hard way, he set up a VCS
repository to track his single-developer workflow — using CVS.

Before today, Brian has never used any VCS more modern than CVS (even
Subversion is uncharted territory). I know that the Bazaar documentation
has been greatly re-worked during the last year or so, but I can never
again look on it with a newcomer's eyes. So I asked that we use the
opportunity to simultaneously show off, and test the efficacy of, the
Bazaar documentation for newcomers.

His most easily available Bazaar was version 1.18, from the NetBSD ports
repository. Yikes! Looking at the package repository page for ‘bzr’ at
<URL:ftp://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/devel/bzr/README.html>
I see that version differ hugely by architecture, so I wonder whether
someone with contacts there needs to prod the NetBSD maintainers to get
the package built at a later version?

I warned him that with that rather old version, there would be a little
hiccup in operation: explicitly telling the tool to use a non-default
format, until he could get around to installing the latest stable
version. No problem, he's apparently accustomed to packages in the
NetBSD repository being at wildly varying levels of out-of-datedness,
and was midly surprised that Bazaar was even available, so didn't regard
an extra command option as undue hardship.


I pointed him to the website, and asked him to look for beginner
documentation and use it to get started. He quickly followed links and
eventually found the documentation for version 1.18, and once there dove
unhesitatingly for the “Bazaar in five minutes” document. It's *great*
to have that document so visible, and it is consistently popular with
people I've seen who are fresh to Bazaar. It needs to be excellent;
let's see how it stands up in this case.

Brian started with the “five minutes” guide, and then quickly realised
he would need something to track in the VCS. He had a specific problem
in mind, but didn't want to toy with the actual code base; so I watched
as he made from scratch a minimal example that contained modules and
subdirectories and numerous files. Only then did he continue with the
guide to see how to track all this in the VCS.

At this point I informed him of the manual hiccup to make version 1.18
perform better, and we created a branch in his existing example working
tree with ‘bzr init --format 2a’. He then did what I keep forgetting
that most beginners do (including me): examine just what happened on the
filesystem, with ‘find’ and ‘file’ etc.


The “five minutes” guide showed him that in order to commit, he needed
to specify a message on the command line. This concerned him: “What if I
don't want the whole message on the command line? Can't it invoke my
editor for a message?” I asked him how he would expect that to happen if
it were possible, and he discovered that omitting the message option did
what he asked. I think perhaps the guide would better be explicit that
it is showing a shortcut for supplying a message, rather than implying
that supplying it on the command-line is necessary.

There was a little confusion for Brian over the difference between the
various commands that change the state of the working tree and what
is/isn't tracked, versus actually committing a revision to the branch.
The guide is explicit about what needs to be done, so I don't know what
more can be done to help a newbie understand this in a brief guide.

While exploring what Bazaar would do in response to new filesystem
entries or changes to existing files in the working tree (both what
happens in ‘bzr commit’ and what changes go on in the filesystem in the
‘.bzr’ directory), we learned the ways to query Bazaar for basic
information (‘bzr info’, ‘bzr status’, ‘bzr diff’, ‘bzr log’). Brian was
happy enough, but not particularly impressed at this point.


Brian continued the “five minutes” guide, and learned about branching.
He had already set up, probably as a response for having dealt with the
previous lack of a VCS by manual concurrent copies, anticipated that
each branch would be stored in subdirectories of a top-level “project”
directory. Bazaar was already looking to be a good fit.

At this point he noticed (by observing the effects on the filesystem
entries in each branch) that there was lots of repository data in each
branch. I failed in my role of silent observer, and jumped in to tell
Brian about detaching the repository from the branch, and that the
project directory was a good place to set up a shared repository. Again
we had to manually specify the ‘2a’ format, but this was accepted
without complaint.

The script playing out in Brian's mind continued, and he made lots of
different kinds of modifications in each branch, then learned about
merging. He was delighted at “All changes applied successfully”; with
CVS as competition, Bazaar could hardly lose here. I pointed out that,
in fairness, any modern DVCS would do as good a job with simple changes;
but made sure to impress that Bazaar's merging support was the most
mature and IMO the best even in complex situations.

The default behaviour of ‘bzr add’ brought another smile, and in
explaining that I also went through the ‘bzr ignore’ feature. Using file
globs for the interface made sense and was appreciated.


At this point came the *big* win, from my perspective:

Brian tried some more changes in each branch, including a rename and
content modification. I made no comment, but his commentary included the
fact that this specific problem was one he never wanted to deal with
again. So when I said that *only* Bazaar treats a rename as an explicit
first-class operation – that all others support renames only by a copy
and delete, or a heuristic guess, etc. — he was sold solidly on Bazaar
at that point.

So, in Brian's case at least, it seems rename *is* the killer feature
of Bazaar <URL:http://www.markshuttleworth.com/archives/123>; and I
didn't even need to prompt for this request. Huzzah!


The rest was gravy. After completing the “five minutes” guide, we then
tackled the import of his existing CVS project. He didn't hold much hope
that the revision data would be consistent, owing to the mess he'd got
into that prompted him to raise the topic at the start of the day.

But, after some more wrangling of NetBSD packages and switching instead
to download directly from the ‘bzr-cvsps-import’, we got all his
branches successfully migrated. I didn't make any promises, but we were
pleasantly surprised that the history was intact, the ancestry of each
branch coverged where expected. Not having to replay each and every
revision was another win, though probably one that CVS deserves for not
screwing up the repository in this case.

The session ended with an exploration of ‘bzr missing’, which was quite
a welcome surprise to Brian. He was very pleased that Bazaar could so
simply compare branches and report, not only based on the ‘diff’ output,
but rather based on the revisions. He went away happy that his path
ahead was clearer than he had hoped, and his head buzzing with ideas.


All of which is a long way of saying: Thank you, Bazaar team, for making
a tool that is such a good fit, and easy sell, to someone with an open
mind.

There are, I suspect, a huge number of people out there who have never
used a decent modern VCS tool, and most of them will simply end up using
whatever one their friend introduces them to and see no good reason to
switch away. It's important, then, that this tool be so easy to teach
that I can decide to do it spur-of-the-moment when neither of us was
expecting to use the computer at all, and have it be such a success.

-- 
 \      “Some forms of reality are so horrible we refuse to face them, |
  `\     unless we are trapped into it by comedy. To label any subject |
_o__)        unsuitable for comedy is to admit defeat.” —Peter Sellers |
Ben Finney