Re: Please don't use revision numbers on commit messages (and elsewhere).

[Uday S Reddy <u.s.reddy@cs.bham.ac.uk>]

On 4/2/2011 1:03 AM, Óscar Fuentes wrote:

>>
>> Can you comment on whether this convention suits you?
>
> I don't get the part about the local branch. If you branch from trunk
> when the tip revno is 10, then commit locally (revno 11) then commit
> again locally (revno 12) mentioning your revno 11 on the commit message,
> finally merge the changes into trunk which meanwhile advanced to revno
> 15, this is how trunk looks like afterwards:
>

No, the trunk really looks like this:

  16 merge uday's awesome feature into trunk
  10.1.2 Fix bug introduced on revision 11
  10.1.1 Implement awesome feature
  15 someone else's changes
  14 someone else's changes
  13 someone else's changes
  12 someone else's changes
  11 someone else's changes
  10 someone else's changes
  ....

Notice that the merged branch revisions are numbered 10.x.y, not 16.x.y 
or 15.x.y. If the branch originated at revno 10 of the trunk, then its 
revisions are numbered 10.1.1, 10.1.2,.... That is how the DAG structure 
is represented.  (I didn't realize this until Stephen Turnbull explained 
it to me last summer, here on emacs-dev!)

The three components of the revision number are:

     base-revision . branch-id . branch-local-revision

The base-revision is revision number where the branch diverged from the 
trunk.

The branch-id is a unique number for the merged branch, just in case 
multiple branches based at revision 10 happen to get merged in due course.

The branch-local-revision is the localized version of the revision 
number, i.e., 1 = 11-10, 2 = 12-10, ...

So, doing that bit of arithmetic is all it takes to decode "revision 11".

>   1. People do as they see. If you put revnos on trunk's commit messages
>      they get the message that it is okay to do that on their branches
>      too.

Agreed.  But as I have argued, it is okay for people to do it in their 
branches too.

>   2. Related to the previous, it is undesirable to add exceptions to
>      policies.

The same response as above.

>   3. If you are inspecting the VC history on a branch and wish to see
>      where certain commit with revno X mentioned on a commit message, bug
>      report, etc fits on the context of your branch, you must go out of
>      your way to look up on trunk the revid of X.

All you would need is your branch's history.  I don't understand what 
you would find on the trunk that you don't have in your branch's log 
already.

>   4. Generalizing the previous point: revids remain valid after a merge,
>      revnos don't.

revid's remain textually valid.  revno's remain mathematically valid. 
If it turns out to be a big problem, then we should probably write an 
emacs browser for bzr logs that does the conversions.

Ideally, bzr people should have given us some way to write something 
like $r12 in the log entry, which could have been automatically 
translated to 10.1.1.  But you know bzr people.  They don't like to make 
life harder for the novices to help the experts.

-------

Another possible way to write the revision references is to use relative 
numbers, i.e., to refer to revision 11 in revision 12, just say 
"revision -1".  It is easy to write, and easy to understand as well.

Cheers,
Uday