"revision" considered confusing (was: Outdated Wiki Page?)

John Yates jyates at netezza.com
Tue Apr 24 19:03:03 BST 2007

On Mon 2007-04-23 Martin Pool wrote:

> On 4/24/07, John Yates <jyates at netezza.com> wrote:
> > Always happy to beat a dead horse, in this case the confusion
> > caused by perpetuating the traditional term "revision".  Here
> > are Eugene's definitions that mention revision:
> So basically that is to say that in this context (at least) we should
> just stop saying 'revision' and use the noun 'commit'.
> I'd rather explain it as: the 'commit' command makes a new 'revision'
> object.  This is consistent with our current ui and code, and i think
> reasonably clear, unless i'm missing your point.

'When I use a word,' Humpty Dumpty said, in a rather scornful
tone,' it means just what I choose it to mean, neither more
nor less.' 

'The question is,' said Alice, 'whether you can make words
mean so many different things.' 

'The question is,' said Humpty Dumpty, 'which is to be master -
that's all.'


Bzr and the vc world in general already uses the term branch
as a verb denoting creation of an object of the same name.
Thus you cannot argue that suggesting that the commit action
creates a commit object is beyond the pale.  The fact that
the proposed help messages need so many parentheticals is at
least a clue that maximum clarity has not been achieved.

I do not honestly expect bzr to change.  The term revision
is too deeply embedded in the ui and the vc culture.  But by
conflicting with the popular connotation of the term this
usage presents an obstacle to understanding when attempting
to explaining vc concepts to neophytes / non-programmers.

In common usage to edit or revise are nearly synonymous.
Neither term suggests much temporal precision.  Rather they
suggest extended processes: "I am editing / revising document
X to reflect / incorporate / achieve / Y".  Further the common
notion of a revision of a published work really does not
suggest the idea of an intermediate snapshot or checkpoint.

If I had my druthers I would prefer to replace commit -- both
as verb and as noun -- by snapshot.  To me this captures the
"whole tree state", the "instant in time", and the "perhaps
not yet finished" notions all at once.  It is the term that
I use when teaching vc to non-programmers.


More information about the bazaar mailing list