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

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

[Óscar Fuentes]

A revision number only makes sense on the branch where it was created
(and this only after setting some options, as Emacs did.) If I'm reading
the VC log on a random branch and see "Fix breakage introduced by rXXXX"
and want to look at the referenced revision, I need to switch to trunk
and hope that XXXX corresponds to one of its revisions. If a series of
commits on a feature branch mentions one another by revison number,
after merging them into trunk (or into any other branch) those numbers
are wrong.

So, if you wish to refer to another revision on the commit message (or
anywhere else) please use the revision id, which is unique for every
commit.

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

[Lennart Borgman]

On Thu, Mar 31, 2011 at 10:47 PM, Óscar Fuentes <ofv@wanadoo.es> wrote:
> A revision number only makes sense on the branch where it was created
> (and this only after setting some options, as Emacs did.) If I'm reading
> the VC log on a random branch and see "Fix breakage introduced by rXXXX"
> and want to look at the referenced revision, I need to switch to trunk
> and hope that XXXX corresponds to one of its revisions. If a series of
> commits on a feature branch mentions one another by revison number,
> after merging them into trunk (or into any other branch) those numbers
> are wrong.
>
> So, if you wish to refer to another revision on the commit message (or
> anywhere else) please use the revision id, which is unique for every
> commit.

Why not both rev number and rev id?

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

[Óscar Fuentes]

Lennart Borgman <lennart.borgman@gmail.com> writes:

>> So, if you wish to refer to another revision on the commit message (or
>> anywhere else) please use the revision id, which is unique for every
>> commit.
>
> Why not both rev number and rev id?

If you have the revision id you know the revision number for every
branch that contains the revision.

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

[Lennart Borgman]

On Thu, Mar 31, 2011 at 11:53 PM, Óscar Fuentes <ofv@wanadoo.es> wrote:
>>
>> Why not both rev number and rev id?
>
> If you have the revision id you know the revision number for every
> branch that contains the revision.

How do you convert from rev id => rev number?

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

[Óscar Fuentes]

Lennart Borgman <lennart.borgman@gmail.com> writes:

> On Thu, Mar 31, 2011 at 11:53 PM, Óscar Fuentes <ofv@wanadoo.es> wrote:
>>>
>>> Why not both rev number and rev id?
>>
>> If you have the revision id you know the revision number for every
>> branch that contains the revision.
>
> How do you convert from rev id => rev number?

Any command that accepts a revision number also accepts a revision
id. So something like

bzr log -r <revision-id>

will show the details of the revision, including the revision
number.

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

[Lennart Borgman]

On Fri, Apr 1, 2011 at 12:06 AM, Óscar Fuentes <ofv@wanadoo.es> wrote:
> Lennart Borgman <lennart.borgman@gmail.com> writes:
>
>> On Thu, Mar 31, 2011 at 11:53 PM, Óscar Fuentes <ofv@wanadoo.es> wrote:
>>>>
>>>> Why not both rev number and rev id?
>>>
>>> If you have the revision id you know the revision number for every
>>> branch that contains the revision.
>>
>> How do you convert from rev id => rev number?
>
> Any command that accepts a revision number also accepts a revision
> id. So something like
>
> bzr log -r <revision-id>
>
> will show the details of the revision, including the revision
> number.

Thanks. That was nice.

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

[Juanma Barranquero]

> How do you convert from rev id => rev number?

C:> bzr lookup-revision 103794
lekktu@gmail.com-20110331194238-x96ra6nhxtse02uq

C:> bzr revision-info lekktu@gmail.com-20110331194238-x96ra6nhxtse02uq
103794 lekktu@gmail.com-20110331194238-x96ra6nhxtse02uq

    Juanma

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

[Juanma Barranquero]

On Thu, Mar 31, 2011 at 22:47, Óscar Fuentes <ofv@wanadoo.es> wrote:

> A revision number only makes sense on the branch where it was created
> (and this only after setting some options, as Emacs did.)

Yeah, well, we're dealing with Emacs, not some random bzr branch.

> If I'm reading
> the VC log on a random branch and see "Fix breakage introduced by rXXXX"
> and want to look at the referenced revision, I need to switch to trunk
> and hope that XXXX corresponds to one of its revisions.

Revision numbers refering to the trunk seem to be, until now, the most
common case. And I see that people sometimes uses the branch name as
an adjetive to clarify which one contains the revno:

  Merge from emacs-23 branch, up to r100386.

  emacs-23 r100373 is rendered unnecessary by pre-existing 2010-05-20
  trunk change.

  Backport revno:103582 from trunk.

  Fix the MS-Windows build broken by r102878 and emacs-23/r100409.

Seems pretty clear to me.

> If a series of
> commits on a feature branch mentions one another by revison number,
> after merging them into trunk (or into any other branch) those numbers
> are wrong.

Isn't that a case of "if it hurts, don't do that"?

> So, if you wish to refer to another revision on the commit message (or
> anywhere else) please use the revision id, which is unique for every
> commit.

It's also quite unwieldy. git SHA-1 ids seem a joy by comparison (at
least you can use a prefix of 6-8 characters and be right most of the
time).

    Juanma

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

[Thien-Thi Nguyen]

() Óscar Fuentes <ofv@wanadoo.es>
() Thu, 31 Mar 2011 22:47:27 +0200

   please use the revision id, which is unique for every commit.

I think it would both more vcs-agnostic and programmer-friendly to use a
date and commit title (presuming the commit has one).  For example:

  2011-03-31  Thien-Thi Nguyen  <ttn@gnuvola.org>
  
  	[lib] Fix bug: Reorder #include "libserveez/foo.h" in libserveez.h.
  
  	Regression (due to omission) introduced 2011-03-04,
  	"Mark #include "libservez/foo.h" as internal".
  	Lesson: Take care when discarding dependency (ordering) info!
  
  	* libserveez.h: Move ‘pipe-socket’ and ‘portcfg’ before ‘cfg’.
  
Here, the date is 2011-03-04, and the title is "Mark ... internal".
These two pieces of info are usually sufficient to uniquely identify a
particular change, and a nice side benefit is that the window of the bug
is apparently computable (in this example almost four weeks -- eep!).

More mumblings on ChangeLog format at:

  http://git.savannah.gnu.org/cgit/serveez.git/tree/HACKING?h=next#n228

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

[Óscar Fuentes]

Juanma Barranquero <lekktu@gmail.com> writes:

> On Thu, Mar 31, 2011 at 22:47, Óscar Fuentes <ofv@wanadoo.es> wrote:
>
>> A revision number only makes sense on the branch where it was created
>> (and this only after setting some options, as Emacs did.)
>
> Yeah, well, we're dealing with Emacs, not some random bzr branch.

The Emacs project has a number of branches published on a well-known
site, and hopefully other branches distributed along a number of
personal machines. I'm saying that using revision numbers is confusing
when those revisions are merged across branches. Across *any* branches,
including the "random" ones (whatever your definition of "random branch"
is.)

>> If I'm reading
>> the VC log on a random branch and see "Fix breakage introduced by rXXXX"
>> and want to look at the referenced revision, I need to switch to trunk
>> and hope that XXXX corresponds to one of its revisions.
>
> Revision numbers refering to the trunk seem to be, until now, the most
> common case.

Maybe this is because `trunk' is where almost all the work is done and
used as a centralized repo where the hackers commit as they progress
(instead of using long-lived feature branches.) That is subject to
change over time as people gets acquainted with distributed features
(or, hopefully, as new hackers join the project.)

> And I see that people sometimes uses the branch name as
> an adjetive to clarify which one contains the revno:
>
>   Merge from emacs-23 branch, up to r100386.

[snip]

> Seems pretty clear to me.

This is not terribly helpful, as it forces you to clone a number of
branches just for reference and jump from one to another, when the
mentioned revision may be already merged in your current
branch. (Usually I'm interested on seeing the revision in the context of
my current work, so I'll have to clone and switch to the other branch,
lookup the revision-id there, and use it on my branch for locating the
revision.)

>> If a series of
>> commits on a feature branch mentions one another by revison number,
>> after merging them into trunk (or into any other branch) those numbers
>> are wrong.
>
> Isn't that a case of "if it hurts, don't do that"?

So we need another rule: if you are working on a branch other than
`trunk', use revision ids, else revision numbers. Creppy.

>> So, if you wish to refer to another revision on the commit message (or
>> anywhere else) please use the revision id, which is unique for every
>> commit.
>
> It's also quite unwieldy. git SHA-1 ids seem a joy by comparison (at
> least you can use a prefix of 6-8 characters and be right most of the
> time).

Yes, bzr's revision ids sucks, but that is no reason for doing the wrong
thing.

Just in case anyone here has the time and energy, it could be suggested
to bzr hackers to implement a SHA-1 revision id in parallel of the
currrent monster. Sequential numbering is just wrong on a distributed
VCS.

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

[Óscar Fuentes]

Thien-Thi Nguyen <ttn@gnuvola.org> writes:

>    please use the revision id, which is unique for every commit.
>
> I think it would both more vcs-agnostic and programmer-friendly to use a
> date and commit title (presuming the commit has one).  For example:
>
>   2011-03-31  Thien-Thi Nguyen  <ttn@gnuvola.org>
>   
>   	[lib] Fix bug: Reorder #include "libserveez/foo.h" in libserveez.h.
>   
>   	Regression (due to omission) introduced 2011-03-04,
>   	"Mark #include "libservez/foo.h" as internal".
>   	Lesson: Take care when discarding dependency (ordering) info!
>   
>   	* libserveez.h: Move ‘pipe-socket’ and ‘portcfg’ before ‘cfg’.
>   
> Here, the date is 2011-03-04, and the title is "Mark ... internal".
> These two pieces of info are usually sufficient to uniquely identify a
> particular change, and a nice side benefit is that the window of the bug
> is apparently computable (in this example almost four weeks -- eep!).

Your proposal is much better than using revision numbers, IMO. It is
actually informative, although it makes difficult to pinpoint the
mentioned revision or to answer the question "is the mentioned revision
on branch X?" which is automatic when you have a revision id.

A different issue is to convince people to write proper commit messages,
with the first line acting as the commit title. But that is another
battle.

[snip]

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

[Juanma Barranquero]

On Fri, Apr 1, 2011 at 02:11, Óscar Fuentes <ofv@wanadoo.es> wrote:

> The Emacs project has a number of branches published on a well-known
> site, and hopefully other branches distributed along a number of
> personal machines. I'm saying that using revision numbers is confusing
> when those revisions are merged across branches.

Yes, and I'm saying that, so far, it seems quite clear from the
context which branch a revno refers to.

> Across *any* branches,
> including the "random" ones (whatever your definition of "random branch"
> is.)

My comment about "random branches" is an answer to your "(and this
only after setting some options, as Emacs did.)".

We're developing Emacs; it's irrelevant whether other projects do or
do not set these options.

> Maybe this is because `trunk' is where almost all the work is done and
> used as a centralized repo where the hackers commit as they progress
> (instead of using long-lived feature branches.) That is subject to
> change over time as people gets acquainted with distributed features
> (or, hopefully, as new hackers join the project.)

I don't foresee that super-distributed future that you imagine for
Emacs. And if it does come to pass, it's everyone's responsibility to
clearly label their revnos.

After all, if you have a branch cloned from trunk, and you do
development on it, and you do refer to revids in the changelogs, these
revids won't be meaningful for the trunk's users either unless the
branch is merged to the trunk. If you just send a patch, revids will
be as meaningless as revnos would be.

> This is not terribly helpful, as it forces you to clone a number of
> branches just for reference and jump from one to another, when the
> mentioned revision may be already merged in your current
> branch.

The Emacs project does not usually maintain a large number of active
branches. And, with a shared repo, "cloning a number of branches"
isn't that problematic, space- or time-wise.

> (Usually I'm interested on seeing the revision in the context of
> my current work, so I'll have to clone and switch to the other branch,
> lookup the revision-id there, and use it on my branch for locating the
> revision.)

It's hard to envision you cloning emacs-23 to locate a revision, then
removing it from the disk, then cloning it again to locate the next
revision...

Also, that example is currently quite artificial, because they aren't
that many revnos in the ChangeLogs right now (I know, I checked the
logs) and they overwhelming refer to the trunk. So you're describing a
future, hypothetical problem.

> So we need another rule: if you are working on a branch other than
> `trunk', use revision ids, else revision numbers. Creppy.

No. Use always revision numbers and trust the users to be smart.

> Yes, bzr's revision ids sucks, but that is no reason for doing the wrong
> thing.

Neither it is an incentive to do the "right thing".

    Juanma

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

[Stefan Monnier]

> So, if you wish to refer to another revision on the commit message (or
> anywhere else) please use the revision id, which is unique for every
> commit.

Agreed.  In the past we've also used dates as in "fix 2009-10-07
change", which aren't as precise as rev-ids and might prove ambiguous,
but are more stable than rev-nbs and more readable than rev-ids
(especially when reading the ChangeLog where the dates are available).


        Stefan

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

[Óscar Fuentes]

Juanma Barranquero <lekktu@gmail.com> writes:

[snip]

>> Across *any* branches,
>> including the "random" ones (whatever your definition of "random branch"
>> is.)
>
> My comment about "random branches" is an answer to your "(and this
> only after setting some options, as Emacs did.)".
>
> We're developing Emacs; it's irrelevant whether other projects do or
> do not set these options.

Anyone can setup a public repo anytime, anywhere. Let's think of a
long-lived feature branch of the type of lexbind or bidi which, for
whatever reason, the participating developers finds more convenient to
host outside of Savannah. Unless he remembers to set the appropriate
options on the public repo's config, it will be subjected to the same
line revision renumbering that happened to Emacs' trunk on the
past. Recommending to use revision ids instead of revision numbers would
help to avoid the problem.

> I don't foresee that super-distributed future that you imagine for
> Emacs. And if it does come to pass, it's everyone's responsibility to
> clearly label their revnos.
>
> After all, if you have a branch cloned from trunk, and you do
> development on it, and you do refer to revids in the changelogs, these
> revids won't be meaningful for the trunk's users either unless the
> branch is merged to the trunk. If you just send a patch, revids will
> be as meaningless as revnos would be.

In the case of patches, using revision ids on the commit messages is,
actually, most convenient, because on that case the referenced ids are
unambiguous no matter on which branch the patch is applied.

> The Emacs project does not usually maintain a large number of active
> branches.

On a distributed project, you don't know how many active branches exist
out there.

> And, with a shared repo, "cloning a number of branches"
> isn't that problematic, space- or time-wise.

Let me expand with an example based on my past* experience. I have a
number of heterogeneous machines (different OS, varying network
connectivity, etc) and on all of them I have Emacs running (of
course!). I've my private branch with some customizations, which is what
I use for building and installing Emacs on all those machines. Keeping
the private branch mirrored among all of them means work. Keeping
mirrors for `trunk', emacs-23 and what-not is too much of a burden (last
time I checked there was no simple & reliable method for synchronizing
sets of branches across multiple platforms.) In theory, having just my
private branch and merging trunk into it from time to time would be
enough. But then those commits messages referencing other revisions by
their numbers doesn't fit, as trunk's revision #110000 has another
number on my private branch.

(*) "That other DVCS" handled the described scenario perfectly.

> It's hard to envision you cloning emacs-23 to locate a revision, then
> removing it from the disk, then cloning it again to locate the next
> revision...
>
> Also, that example is currently quite artificial, because they aren't
> that many revnos in the ChangeLogs right now (I know, I checked the
> logs) and they overwhelming refer to the trunk. So you're describing a
> future, hypothetical problem.

Do you prefer to wait until the problem has manifested itself on all its
crudeness? :-)

[snip]

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

[Stephen J. Turnbull]

Juanma Barranquero writes:

 > > If a series of commits on a feature branch mentions one another
 > > by revison number, after merging them into trunk (or into any
 > > other branch) those numbers are wrong.
 > 
 > Isn't that a case of "if it hurts, don't do that"?

Sure.  But then everything is.  "Sometimes Emacs crashes, so don't use
Emacs."  It is very typical to refer to a parent revision in a feature
branch.  I don't see why one should stop doing so.

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

[Stephen J. Turnbull]

Juanma Barranquero writes:
 > On Fri, Apr 1, 2011 at 02:11, Óscar Fuentes <ofv@wanadoo.es> wrote:
 > 
 > > The Emacs project has a number of branches published on a well-known
 > > site, and hopefully other branches distributed along a number of
 > > personal machines. I'm saying that using revision numbers is confusing
 > > when those revisions are merged across branches.
 > 
 > Yes, and I'm saying that, so far, it seems quite clear from the
 > context which branch a revno refers to.

That's only because so far, people don't lose push races often enough
for it to matter.  Commits that from your point of view are on the
mainline really are on local branches until you succeed in pushing.
If you use a bound branch, you're saved from that, true (this is not
entirely trivial, but I'm pretty sure in practice it will be true).
But bound branches suck for anything much bigger than a typo fix.

If you lose a push race, you have to undo the commit so you can redo
the commit message.  That (a) sucks even if you know what you're
doing, and (b) is probably beyond the average Emacs committer at that
moment.  (b) is no insult, just my estimate of a fact, and I see *no
reason* why that should change.  And of course (c) a lot of people
will forget (or never know about it in the first place).  I've been
annoyed by this a couple of times in XEmacs.

 > I don't foresee that super-distributed future that you imagine for
 > Emacs.

It doesn't require a super-distributed future, just an Emacs sprint.
Then you'll see people losing push races all over the place, and
anybody who's using revnos will have to go back and fix them.

 > And if it does come to pass, it's everyone's responsibility to
 > clearly label their revnos.

Well, OK, but I don't see how you can "label" a revno that's (a) just
plain wrong and (b) embedded in a commit message that can't be changed.

The right thing to do is to use a revid (which is bzr-friendly), or
ttn's literary style of commit message (which is people-friendly,
except to the committer and people who really exercise the capability
of the VCS).

 > No. Use always revision numbers and trust the users to be smart.

"Smart" is one thing, "anal retentive" is another.  Especially at any
time it's likely to matter (ie, the commit rushes that always occur
just before a freeze).  People are going to be frustrated enough by
losing push races.  They're not going to want to rebase their local
commits (and this has to be done by hand since the commit messages
need to be changed) at that point in time.

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

[Eli Zaretskii]

> From: Lennart Borgman <lennart.borgman@gmail.com>
> Date: Thu, 31 Mar 2011 23:36:07 +0200
> Cc: emacs-devel@gnu.org
> 
> > So, if you wish to refer to another revision on the commit message (or
> > anywhere else) please use the revision id, which is unique for every
> > commit.
> 
> Why not both rev number and rev id?

Why not the whole DAG, dammit?

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

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Lennart Borgman <lennart.borgman@gmail.com>
>> Date: Thu, 31 Mar 2011 23:36:07 +0200
>> Cc: emacs-devel@gnu.org
>> 
>> > So, if you wish to refer to another revision on the commit message (or
>> > anywhere else) please use the revision id, which is unique for every
>> > commit.
>> 
>> Why not both rev number and rev id?
>
> Why not the whole DAG, dammit?

The rev id _is_ the whole DAG.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: Lennart Borgman <lennart.borgman@gmail.com>,  ofv@wanadoo.es,  emacs-devel@gnu.org
> Date: Fri, 01 Apr 2011 09:58:38 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Lennart Borgman <lennart.borgman@gmail.com>
> >> Date: Thu, 31 Mar 2011 23:36:07 +0200
> >> Cc: emacs-devel@gnu.org
> >> 
> >> > So, if you wish to refer to another revision on the commit message (or
> >> > anywhere else) please use the revision id, which is unique for every
> >> > commit.
> >> 
> >> Why not both rev number and rev id?
> >
> > Why not the whole DAG, dammit?
> 
> The rev id _is_ the whole DAG.

But if I don't have some of the branches, those parts of the DAG are
not on my machine.  And I want to have them, pronto.

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

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

> But if I don't have some of the branches, those parts of the DAG are
> not on my machine.  And I want to have them, pronto.

$ git clone git://git.sv.gnu.org/emacs

Here you are.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Eli Zaretskii]

> From: Óscar Fuentes <ofv@wanadoo.es>
> Date: Fri, 01 Apr 2011 03:20:14 +0200
> 
> Anyone can setup a public repo anytime, anywhere. Let's think of a
> long-lived feature branch of the type of lexbind or bidi

The bidi branch was never alive for a long time.  If anything, it was
_dead_ for a long time.  Once serious work on bidi support was
resumed, and it was in a shape that could be used without crashing
every several seconds, it was merged with the trunk.

In general, the current experience with branches seems to be that no
one but their developer(s), usually a single individual, uses them,
until very close to a merge.  The only exception is the release
branch, where the maintainers take care of these references.

So it looks like you are asking everyone and their dog to pay dearly
_now_ for a mostly theoretical problem, that could potentially become
a real problem in some vague future.  Good luck expecting that people
will abide by your request!

> On a distributed project, you don't know how many active branches exist
> out there.

Emacs is not currently a distributed project, and I see no signs that
it is going to become one.

> Let me expand with an example based on my past* experience. I have a
> number of heterogeneous machines (different OS, varying network
> connectivity, etc) and on all of them I have Emacs running (of
> course!). I've my private branch with some customizations, which is what
> I use for building and installing Emacs on all those machines. Keeping
> the private branch mirrored among all of them means work. Keeping
> mirrors for `trunk', emacs-23 and what-not is too much of a burden (last
> time I checked there was no simple & reliable method for synchronizing
> sets of branches across multiple platforms.) In theory, having just my
> private branch and merging trunk into it from time to time would be
> enough. But then those commits messages referencing other revisions by
> their numbers doesn't fit, as trunk's revision #110000 has another
> number on my private branch.

It is very easy to see that revision, even if it is on the other
branch, assuming that the referenced branch is in your repo, with the
"revno:NNN:/path/to/branch" revision identifier.

> Do you prefer to wait until the problem has manifested itself on all its
> crudeness? :-)

That's one way of putting it.  Another one would be "don't try to
solve problems that don't exist."

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

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 1012 bytes --]

() Óscar Fuentes <ofv@wanadoo.es>
() Fri, 01 Apr 2011 02:20:26 +0200

   It is actually informative, although it makes difficult to pinpoint the
   mentioned revision or to answer the question "is the mentioned revision on
   branch X?" which is automatic when you have a revision id.

To dereference a DATE-TITLE pair to a VCS commit the VCS needs to be able to
grep for DATE or TITLE or both in its (internal) commit log representation.
It's an extra step, true, and might be difficult if the VCS is lame.  Likewise
for localizing the commit to a branch.

   A different issue is to convince people to write proper commit messages,
   with the first line acting as the commit title. But that is another
   battle.

All it takes is for the Emacs maintainers to promote the practice from IWBN to
required.  I think concurrent to such a move should be to publish tools to make
the ChangeLog(s) -> VCS commit message flow less balky.  FWIW, i attach some
sketches (that i find useful) here.


[-- Attachment #2: changelog-to-vcs-commit-message-flow.el --]
[-- Type: application/emacs-lisp, Size: 3513 bytes --]

[-- Attachment #3: Type: text/plain, Size: 1031 bytes --]


Example flow:
(0) Munge source in file src/foo.c,
    related docs in file doc/foo.texi.

(1) C-x C-f src/ChangeLog RET
    C-c C-a TITLE RET
    foo.c (func): Change. RET RET
    C-x C-s
    C-x C-k RET

(2) C-x C-f doc/ChangeLog RET
    C-c C-a M-p RET
    foo.texi (functionality): Change. RET RET
    C-x C-s
    C-x C-k RET

(3) initiate commit sequence, specifying files:
      src/ChangeLog
      src/foo.c
      doc/ChangeLog
      doc/foo.texi
    => end up in buffer in Log Edit mode

(4) C-c C-d        ; git-scan-log-buffer-and-insert-commit-log
    tweak aesthetics (paragraph order, primarily)
    C-c C-c        ; log-edit-done
    C-c C-M-r      ; revert-some-buffers

This example assumes the details of each change fits in my head, which often
is not the case.  More typically, there is a series of ‘vc-diff’ invocations
prior to (1) and (2).  I sometimes (very rarely) interleave (0) and (1)/(2).
Anyway, the point is that (3) and (4) take little thought/effort to perform.

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

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: lennart.borgman@gmail.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
> Date: Fri, 01 Apr 2011 10:17:00 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > But if I don't have some of the branches, those parts of the DAG are
> > not on my machine.  And I want to have them, pronto.
> 
> $ git clone git://git.sv.gnu.org/emacs
> 
> Here you are.

That's outdated.

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

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andreas Schwab <schwab@linux-m68k.org>
>> Cc: lennart.borgman@gmail.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
>> Date: Fri, 01 Apr 2011 10:17:00 +0200
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> > But if I don't have some of the branches, those parts of the DAG are
>> > not on my machine.  And I want to have them, pronto.
>> 
>> $ git clone git://git.sv.gnu.org/emacs
>> 
>> Here you are.
>
> That's outdated.

No, it isn't.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Eli Zaretskii]

> From: Thien-Thi Nguyen <ttn@gnuvola.org>
> Date: Fri, 01 Apr 2011 10:38:26 +0200
> Cc: emacs-devel@gnu.org
> 
> [1:text/plain Hide]
> () Óscar Fuentes <ofv@wanadoo.es>
> () Fri, 01 Apr 2011 02:20:26 +0200
> 
>    It is actually informative, although it makes difficult to pinpoint the
>    mentioned revision or to answer the question "is the mentioned revision on
>    branch X?" which is automatic when you have a revision id.
> 
> To dereference a DATE-TITLE pair to a VCS commit the VCS needs to be able to
> grep for DATE or TITLE or both in its (internal) commit log representation.
> It's an extra step, true, and might be difficult if the VCS is lame.

Our VCS isn't lame:

  bzr log -r date:2011-03-31,23:59:59..date:2011-04-01,23:59:59

> Likewise for localizing the commit to a branch.

  bzr log -c revno:12345:../mybranch

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

[Uday S Reddy]

On 4/1/2011 2:59 AM, Stephen J. Turnbull wrote:

> That's only because so far, people don't lose push races often enough
> for it to matter.  Commits that from your point of view are on the
> mainline really are on local branches until you succeed in pushing.
> If you use a bound branch, you're saved from that, true (this is not
> entirely trivial, but I'm pretty sure in practice it will be true).
> But bound branches suck for anything much bigger than a typo fix.

I am still trying to understand how bad this problem is.

If the cross-references are to revision numbers in the trunk or to other 
revisions in the local branch, then things are clear, right?  For 
example, a reference to revision 1123 in a branch labeled 1121.2.x has 
to be 1121.2.2.

When references have to be made to branches other than the trunk or the 
local branch then, yes, using revision ids would be better.  But, why 
require them for everything?

The "push race" affects things only if one is assuming that the current 
branch will get committed at a particular place on the trunk?  Well, why 
would any one assume such a thing anyway?

Cheers,
Uday

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

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: lennart.borgman@gmail.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
> Date: Fri, 01 Apr 2011 10:54:49 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Andreas Schwab <schwab@linux-m68k.org>
> >> Cc: lennart.borgman@gmail.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
> >> Date: Fri, 01 Apr 2011 10:17:00 +0200
> >> 
> >> Eli Zaretskii <eliz@gnu.org> writes:
> >> 
> >> > But if I don't have some of the branches, those parts of the DAG are
> >> > not on my machine.  And I want to have them, pronto.
> >> 
> >> $ git clone git://git.sv.gnu.org/emacs
> >> 
> >> Here you are.
> >
> > That's outdated.
> 
> No, it isn't.

Yes, it is.

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

[Eli Zaretskii]

> Date: Fri, 01 Apr 2011 12:36:55 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: ofv@wanadoo.es, emacs-devel@gnu.org
> 
>   bzr log -r date:2011-03-31,23:59:59..date:2011-04-01,23:59:59

Err, this will be good tomorrow.  For today, this will do better:

   bzr log -r date:2011-03-31,23:59:59..

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

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andreas Schwab <schwab@linux-m68k.org>
>> Cc: lennart.borgman@gmail.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
>> Date: Fri, 01 Apr 2011 10:54:49 +0200
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Andreas Schwab <schwab@linux-m68k.org>
>> >> Cc: lennart.borgman@gmail.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
>> >> Date: Fri, 01 Apr 2011 10:17:00 +0200
>> >> 
>> >> Eli Zaretskii <eliz@gnu.org> writes:
>> >> 
>> >> > But if I don't have some of the branches, those parts of the DAG are
>> >> > not on my machine.  And I want to have them, pronto.
>> >> 
>> >> $ git clone git://git.sv.gnu.org/emacs
>> >> 
>> >> Here you are.
>> >
>> > That's outdated.
>> 
>> No, it isn't.
>
> Yes, it is.

No, it isn't.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Juanma Barranquero]

On Fri, Apr 1, 2011 at 03:20, Óscar Fuentes <ofv@wanadoo.es> wrote:

> Anyone can setup a public repo anytime, anywhere. Let's think of a
> long-lived feature branch of the type of lexbind or bidi which, for
> whatever reason, the participating developers finds more convenient to
> host outside of Savannah.

I think Eli has already answered that: if/when it happens, we can
discuss how to minimize the problems. Until now, it is entirely
hypothetical.

> In the case of patches, using revision ids on the commit messages is,
> actually, most convenient, because on that case the referenced ids are
> unambiguous no matter on which branch the patch is applied.

"Unambiguous" does not mean "I have it accessible and I know which
branch it refers to". Are you defending using revids because they are
unique, or because you don't like to having around multiple branches?

> On a distributed project, you don't know how many active branches exist
> out there.

Last time I checked, Emacs wasn't a "distributed project". It is a
centralized project with a distributed tool that helps developers.

> Let me expand with an example based on my past* experience. I have a
> number of heterogeneous machines (different OS, varying network
> connectivity, etc) and on all of them I have Emacs running (of
> course!). I've my private branch with some customizations, which is what
> I use for building and installing Emacs on all those machines. Keeping
> the private branch mirrored among all of them means work. Keeping
> mirrors for `trunk', emacs-23 and what-not is too much of a burden (last
> time I checked there was no simple & reliable method for synchronizing
> sets of branches across multiple platforms.)

Sorry, you lost me here. "trunk, emacs-23 and what-not" can be mostly
summarized to "trunk, emacs-23 and nothing else", *unless* you're
actively tracking window-pub, lexbind-new or some other branch, which
most people (even developers) apparently don't do. If we maintained
dozens of branches, all of them vibrant with activity, I could buy it.
But we use a development branch and a release branch, and a few
almost-private-development-branches-that-nobody-tracks, and that
doesn't seem likely to change in the near future.

> Do you prefer to wait until the problem has manifested itself on all its
> crudeness? :-)

Sure I do. And you know why? Because Bazaar revnos are *convenient*,
and Bazaar revids are a royal PITA. I don't want to abandon convenient
shorthands for what, at the moment, is just FUD.

    Juanma

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

[Juanma Barranquero]

On Fri, Apr 1, 2011 at 03:35, Stephen J. Turnbull <stephen@xemacs.org> wrote:

> Sure.  But then everything is.  "Sometimes Emacs crashes, so don't use
> Emacs."  It is very typical to refer to a parent revision in a feature
> branch.  I don't see why one should stop doing so.

OK, do it. In a previous message, Óscar said:

> So we need another rule: if you are working on a branch other than
> `trunk', use revision ids, else revision numbers. Creppy.

Well, yes. revnos are convenient, and it seems unfortunate to force
everyone to abandon that just because you (= collective) are
developing on a private branch. So if you want your revision
references to be universal, use revids. I'm not trying to convince
anyone *not* to use revids. I'm strongly opposed against being forced
to *use* them in the *trunk* because other people have private
branches. If that means the trunk branch is privileged, well, with our
current setup and procedures, it is.

    Juanma

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

[Juanma Barranquero]

On Fri, Apr 1, 2011 at 03:59, Stephen J. Turnbull <stephen@xemacs.org> wrote:

> That's only because so far, people don't lose push races often enough
> for it to matter.  Commits that from your point of view are on the
> mainline really are on local branches until you succeed in pushing.
> If you use a bound branch, you're saved from that, true (this is not
> entirely trivial, but I'm pretty sure in practice it will be true).

It does happen that we're using a bound branch for trunk (that's the
recommended setup), so again, you're arguing pretty convincingly for
an hypothetical situation, and I'm discussing the here-and-now.

> But bound branches suck for anything much bigger than a typo fix.

The fact that huge, successful projects are developed with
non-distributed VCS seem to indicate that your opinion is just that,
an opinion.

And no, I'm not saying I prefer CVS or Subversion to Bazaar or git,
because I don't. But the model we're using is one where there is a
preferred, centralized branch, and the distributed features of our VCS
are for the convenience of the developers, not to suddenly force some
kind of distributed model of Emacs development.

    Juanma

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

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: lennart.borgman@gmail.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
> Date: Fri, 01 Apr 2011 12:21:57 +0200
> 
> >> >> $ git clone git://git.sv.gnu.org/emacs
> >> >> 
> >> >> Here you are.
> >> >
> >> > That's outdated.
> >> 
> >> No, it isn't.
> >
> > Yes, it is.
> 
> No, it isn't.

Maybe I should keep teasing you, to keep git://git.sv.gnu.org/emacs
users happy.

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

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andreas Schwab <schwab@linux-m68k.org>
>> Cc: lennart.borgman@gmail.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
>> Date: Fri, 01 Apr 2011 12:21:57 +0200
>> 
>> >> >> $ git clone git://git.sv.gnu.org/emacs
>> >> >> 
>> >> >> Here you are.
>> >> >
>> >> > That's outdated.
>> >> 
>> >> No, it isn't.
>> >
>> > Yes, it is.
>> 
>> No, it isn't.
>
> Maybe I should keep teasing you, to keep git://git.sv.gnu.org/emacs
> users happy.

You didn't even check.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Óscar Fuentes <ofv@wanadoo.es>
>> Date: Fri, 01 Apr 2011 03:20:14 +0200
>> 
>> Anyone can setup a public repo anytime, anywhere. Let's think of a
>> long-lived feature branch of the type of lexbind or bidi
>
> The bidi branch was never alive for a long time.  If anything, it was
> _dead_ for a long time.  Once serious work on bidi support was
> resumed, and it was in a shape that could be used without crashing
> every several seconds, it was merged with the trunk.

Not from the bidi branch IIRC.

-- 
David Kastrup

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

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Date: Fri, 01 Apr 2011 13:18:27 +0200
> Cc: emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Andreas Schwab <schwab@linux-m68k.org>
> >> Cc: lennart.borgman@gmail.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
> >> Date: Fri, 01 Apr 2011 12:21:57 +0200
> >> 
> >> >> >> $ git clone git://git.sv.gnu.org/emacs
> >> >> >> 
> >> >> >> Here you are.
> >> >> >
> >> >> > That's outdated.
> >> >> 
> >> >> No, it isn't.
> >> >
> >> > Yes, it is.
> >> 
> >> No, it isn't.
> >
> > Maybe I should keep teasing you, to keep git://git.sv.gnu.org/emacs
> > users happy.
> 
> You didn't even check.

Of course I did.

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

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Fri, 01 Apr 2011 14:08:39 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Óscar Fuentes <ofv@wanadoo.es>
> >> Date: Fri, 01 Apr 2011 03:20:14 +0200
> >> 
> >> Anyone can setup a public repo anytime, anywhere. Let's think of a
> >> long-lived feature branch of the type of lexbind or bidi
> >
> > The bidi branch was never alive for a long time.  If anything, it was
> > _dead_ for a long time.  Once serious work on bidi support was
> > resumed, and it was in a shape that could be used without crashing
> > every several seconds, it was merged with the trunk.
> 
> Not from the bidi branch IIRC.

Exactly.

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

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

> Of course I did.

Then why did you lie?

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: emacs-devel@gnu.org
> Date: Fri, 01 Apr 2011 15:32:31 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Of course I did.
> 
> Then why did you lie?

I didn't.

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

[Deniz Dogan]

2011/4/1 Eli Zaretskii <eliz@gnu.org>:
>> From: Andreas Schwab <schwab@linux-m68k.org>
>> Cc: emacs-devel@gnu.org
>> Date: Fri, 01 Apr 2011 15:32:31 +0200
>>
>> Eli Zaretskii <eliz@gnu.org> writes:
>>
>> > Of course I did.
>>
>> Then why did you lie?
>
> I didn't.
>
>

Guys, what the fuck.

-- 
Deniz Dogan

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

[Stefan Monnier]

> It does happen that we're using a bound branch for trunk (that's the
> recommended setup), so again, you're arguing pretty convincingly for
> an hypothetical situation, and I'm discussing the here-and-now.

Some of the rev-numbers that appear in the ChangeLog on the lexbind
branch are not correct (because they refer to revnos on the `trunk').
In most cases I can figure out from circumstantial evidence what was the
intended meaning, but using revnos is just not a good idea.
Noone will be hung or lynched for it, but I encourage people to use
other ways to refer to changes, e.g. rev-ids or dates.


        Stefan

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

[Stephen J. Turnbull]

Uday S Reddy writes:

 > I am still trying to understand how bad this problem is.

It's this bad:

Right now, you and I simultaneously clone the mainline at r42.  You
commit, creating r43, because as far as bzr knows, you're on the
mainline.  Oops, you missed something, and you commit your r44, with
the message "Fix bug introduced in r43."  While you're fixing the bug,
I commit and push, and my commit becomes mainline r43.  Now when you
pull and merge, your commits that used to be on the (local) mainline
with revnos r43 and r44 are now off the mainline and have revnos
r42.1.1 and r42.1.2, and the commit message is now a dastardly attack
on my reputation. ;-)

Yes, if something is already in the master repo, you can refer to it
by revno, as long as you never intend to push it anywhere else, or
allow others to pull from your branch (you can't be sure that they
have the same history you do).  But you can't refer to your own
commits by revno until they've been pushed to the master.

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

[Ted Zlatanov]

On Fri, 01 Apr 2011 10:51:28 -0400 Stefan Monnier <monnier@iro.umontreal.ca> wrote: 

SM> Noone will be hung or lynched for it, but I encourage people to use
SM> other ways to refer to changes, e.g. rev-ids or dates.

What did Herman ever do to you?

(http://en.wikipedia.org/wiki/Peter_Noone of Herman's Hermits :)

Ted

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

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

>> The rev id _is_ the whole DAG.
>
> But if I don't have some of the branches, those parts of the DAG are
> not on my machine.  And I want to have them, pronto.

If you have the revision, you already have the DAG that contains all its
predecessors.

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

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

>> Anyone can setup a public repo anytime, anywhere. Let's think of a
>> long-lived feature branch of the type of lexbind or bidi
>
> The bidi branch was never alive for a long time.

bidi was mentioned as an example of a task suitable for a long lived
feature branch (and for working on a team, or at least publish the
branch and accept occasional contributions.) I was not implying that
bidi was actually managed that way.

[snip]

> So it looks like you are asking everyone and their dog to pay dearly
> _now_ for a mostly theoretical problem, that could potentially become
> a real problem in some vague future.  Good luck expecting that people
> will abide by your request!

It is not mostly theoretical. It would be affecting me if I were using
bzr (and then it would be another reason for switching to git.)

>> On a distributed project, you don't know how many active branches exist
>> out there.
>
> Emacs is not currently a distributed project, and I see no signs that
> it is going to become one.

No, you see no signs because private branches live on private machines,
which is precisely one of the specific characteristics of a dVCS. I have
two branches where I do development since a year ago. I'm sure you
wasn't aware of their existence until now :-)

>> Let me expand with an example based on my past* experience. I have a
>> number of heterogeneous machines (different OS, varying network
>> connectivity, etc) and on all of them I have Emacs running (of
>> course!). I've my private branch with some customizations, which is what
>> I use for building and installing Emacs on all those machines. Keeping
>> the private branch mirrored among all of them means work. Keeping
>> mirrors for `trunk', emacs-23 and what-not is too much of a burden (last
>> time I checked there was no simple & reliable method for synchronizing
>> sets of branches across multiple platforms.) In theory, having just my
>> private branch and merging trunk into it from time to time would be
>> enough. But then those commits messages referencing other revisions by
>> their numbers doesn't fit, as trunk's revision #110000 has another
>> number on my private branch.
>
> It is very easy to see that revision, even if it is on the other
> branch, assuming that the referenced branch is in your repo, with the
> "revno:NNN:/path/to/branch" revision identifier.

Precisely, what I described above was a setup where having the "other
branch" (say better "the other brancheS") is a burden. So I don't have
them.

[snip]

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

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

[snip]

>> Likewise for localizing the commit to a branch.
>
>   bzr log -c revno:12345:../mybranch

Here you are assuming that the user knows that 12345 is the revno of
mybranch.

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

[Óscar Fuentes]

Juanma Barranquero <lekktu@gmail.com> writes:

> On Fri, Apr 1, 2011 at 03:20, Óscar Fuentes <ofv@wanadoo.es> wrote:
>
>> Anyone can setup a public repo anytime, anywhere. Let's think of a
>> long-lived feature branch of the type of lexbind or bidi which, for
>> whatever reason, the participating developers finds more convenient to
>> host outside of Savannah.
>
> I think Eli has already answered that: if/when it happens, we can
> discuss how to minimize the problems. Until now, it is entirely
> hypothetical.

See my response to Eli about this.

>> In the case of patches, using revision ids on the commit messages is,
>> actually, most convenient, because on that case the referenced ids are
>> unambiguous no matter on which branch the patch is applied.
>
> "Unambiguous" does not mean "I have it accessible and I know which
> branch it refers to". Are you defending using revids because they are
> unique, or because you don't like to having around multiple branches?

Both reasons. Please note that if I read a reference to revision #XXXX
on a commit message (or bug report...) and want to see its log on my
machine, the scenario is at least as bad as if we were using revision
ids.

>> On a distributed project, you don't know how many active branches exist
>> out there.
>
> Last time I checked, Emacs wasn't a "distributed project". It is a
> centralized project with a distributed tool that helps developers.

Once Emacs switched to a dVCS, it is a distributed project. You can
insist on its centralization all the time, but the truth is that working
on Emacs on a distributed way is a decisions that now belongs to each
and every hacker. I can have my private branches, I can publish them
from my machine, I can exchange revisions with other hackers. Eventually
I can contribute those changes to "central" Emacs, but the process was
distributed all the way, because I chose to do so. Whatever informal
policy some Emacs hackers follow, it is irrelevant to me.

> Sorry, you lost me here. "trunk, emacs-23 and what-not" can be mostly
> summarized to "trunk, emacs-23 and nothing else", *unless* you're
> actively tracking window-pub, lexbind-new or some other branch, which
> most people (even developers) apparently don't do. If we maintained
> dozens of branches, all of them vibrant with activity, I could buy it.
> But we use a development branch and a release branch, and a few
> almost-private-development-branches-that-nobody-tracks, and that
> doesn't seem likely to change in the near future.

This looks like defeatism :-)

>> Do you prefer to wait until the problem has manifested itself on all its
>> crudeness? :-)
>
> Sure I do. And you know why? Because Bazaar revnos are *convenient*,
> and Bazaar revids are a royal PITA. I don't want to abandon convenient
> shorthands for what, at the moment, is just FUD.

Maybe you perceive the issue as FUD because your workflow?

I admit that the problem is negligible *now*. How much importance it
will adquire on the future depends on how Emacs development evolves. You
say it will not turn serious because Emacs development will not
change. Okay, time will tell.

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

[Uday S Reddy]

Stephen J. Turnbull writes:

> Right now, you and I simultaneously clone the mainline at r42.  You
> commit, creating r43, because as far as bzr knows, you're on the
> mainline.  Oops, you missed something, and you commit your r44, with
> the message "Fix bug introduced in r43."  While you're fixing the bug,
> I commit and push, and my commit becomes mainline r43.  Now when you
> pull and merge, your commits that used to be on the (local) mainline
> with revnos r43 and r44 are now off the mainline and have revnos
> r42.1.1 and r42.1.2, and the commit message is now a dastardly attack
> on my reputation. ;-)

Not really.  Since r43 is a reference to a revision _local_ to the
merged branch, it is easy to interpret it as a reference to 42.1.1.  I
already have a few such references in the VM mainline and they haven't
posed a problem.  What happens when there are multiple mainlines or
when you cherry pick revisions into another release branch, I am not
sure.

Cheers,
Uday

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

[Thien-Thi Nguyen]

() Eli Zaretskii <eliz@gnu.org>
() Fri, 01 Apr 2011 13:14:46 +0300

   Err, this will be good tomorrow.  For today, this will do better:

      bzr log -r date:2011-03-31,23:59:59..

Thanks for the tip.

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

[Stephen J. Turnbull]

Uday S Reddy writes:

 > Not really.  Since r43 is a reference to a revision _local_ to the
 > merged branch, it is easy to interpret it as a reference to 42.1.1.

You only know it's local to the branch if you have global knowledge of
the whole project.  But if you do have that knowledge, it doesn't much
matter how you make these references.

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

[Uday S Reddy]

Stephen J. Turnbull writes:

>  > Not really.  Since r43 is a reference to a revision _local_ to the
>  > merged branch, it is easy to interpret it as a reference to 42.1.1.
> 
> You only know it's local to the branch if you have global knowledge of
> the whole project.  But if you do have that knowledge, it doesn't much
> matter how you make these references.

No, the assumption is that the numeric references to revisions are
either to the mainline or to the local branch.  I think these cover
90% of the cases.  Others would have to be more explicit references
(either by revision id or by specific description of the branch/date
etc.)

So, a reference to revision 43 inside a branch that starts from
revision 42 is very very likely to be a local reference.  In the very
odd case where the author is trying to refer to the revision 43 of the
trunk (which is sort of the in "future"), he/she would probably
describe it as "revision 43 of the trunk".

If there is a reference to revision 40, then it would have to be
revision 40 of the mainline, because this branch starts only at
revision 42.

So, the two cases that are important seem to be easily discernible and
problem doesn't seem to be as bad as it is being made out to be.

But then I haven't seen all the weird cases that might occur in a
large multi-developer project.

Cheers,
Uday

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

[Eli Zaretskii]

> From: Óscar Fuentes <ofv@wanadoo.es>
> Date: Fri, 01 Apr 2011 17:38:38 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> [snip]
> 
> >> Likewise for localizing the commit to a branch.
> >
> >   bzr log -c revno:12345:../mybranch
> 
> Here you are assuming that the user knows that 12345 is the revno of
> mybranch.

That 12345 is the number you don't like to see in the logs.  And
mybranch is trunk, known to everyone.  Puff! the problem is gone.

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

[Eli Zaretskii]

> From: Óscar Fuentes <ofv@wanadoo.es>
> Date: Fri, 01 Apr 2011 17:26:14 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> The rev id _is_ the whole DAG.
> >
> > But if I don't have some of the branches, those parts of the DAG are
> > not on my machine.  And I want to have them, pronto.
> 
> If you have the revision, you already have the DAG that contains all its
> predecessors.

The logs only mention the revision IDs, so what I have the revision
ID, not the revision itself.

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

[Eli Zaretskii]

> From: Óscar Fuentes <ofv@wanadoo.es>
> Date: Fri, 01 Apr 2011 17:35:58 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Anyone can setup a public repo anytime, anywhere. Let's think of a
> >> long-lived feature branch of the type of lexbind or bidi
> >
> > The bidi branch was never alive for a long time.
> 
> bidi was mentioned as an example of a task suitable for a long lived
> feature branch (and for working on a team, or at least publish the
> branch and accept occasional contributions.) I was not implying that
> bidi was actually managed that way.

And I was trying to say that you won't find more than a very small
number of examples of long-living (as opposed to long dead) branches.

> >> On a distributed project, you don't know how many active branches exist
> >> out there.
> >
> > Emacs is not currently a distributed project, and I see no signs that
> > it is going to become one.
> 
> No, you see no signs because private branches live on private machines,
> which is precisely one of the specific characteristics of a dVCS. I have
> two branches where I do development since a year ago. I'm sure you
> wasn't aware of their existence until now :-)

And I have 3 branches, so what?  As long as we don't push or pull or
merge from/to those as a matter of routine, Emacs is not a distributed
project.  It has a potential of becoming one, but to make that happen,
we will need much more than use revision IDs.

> > It is very easy to see that revision, even if it is on the other
> > branch, assuming that the referenced branch is in your repo, with the
> > "revno:NNN:/path/to/branch" revision identifier.
> 
> Precisely, what I described above was a setup where having the "other
> branch" (say better "the other brancheS") is a burden. So I don't have
> them.

The above works with URLs as well, of course.  You don't need to have
the branches locally.

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

[Juanma Barranquero]

On Fri, Apr 1, 2011 at 16:51, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Noone will be hung or lynched for it

Well, that's good to hear.

    Juanma

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

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Óscar Fuentes <ofv@wanadoo.es>
>> Date: Fri, 01 Apr 2011 17:35:58 +0200
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> Anyone can setup a public repo anytime, anywhere. Let's think of a
>> >> long-lived feature branch of the type of lexbind or bidi
>> >
>> > The bidi branch was never alive for a long time.
>> 
>> bidi was mentioned as an example of a task suitable for a long lived
>> feature branch (and for working on a team, or at least publish the
>> branch and accept occasional contributions.) I was not implying that
>> bidi was actually managed that way.
>
> And I was trying to say that you won't find more than a very small
> number of examples of long-living (as opposed to long dead) branches.

Well, the Unicode branch was certainly one of the most impressively
long-lived branches.  Multitty had a non-trivial life-time as well, and
lexbind has been around for even longer than Unicode IIRC.

-- 
David Kastrup

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

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

>> >> The rev id _is_ the whole DAG.
>> >
>> > But if I don't have some of the branches, those parts of the DAG are
>> > not on my machine.  And I want to have them, pronto.
>> 
>> If you have the revision, you already have the DAG that contains all its
>> predecessors.
>
> The logs only mention the revision IDs, so what I have the revision
> ID, not the revision itself.

Using the revision number makes things no better here. At least with the
revision id you have the key for finding the revision, if you have it in
some branch.

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

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

>> >   bzr log -c revno:12345:../mybranch
>> 
>> Here you are assuming that the user knows that 12345 is the revno of
>> mybranch.
>
> That 12345 is the number you don't like to see in the logs.  And
> mybranch is trunk, known to everyone.  Puff! the problem is gone.

So you are in favor of using revnos when you know that the revision you
are referencing is on trunk, and revids otherwise?

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

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Fri, 01 Apr 2011 22:04:53 +0200
> 
> > And I was trying to say that you won't find more than a very small
> > number of examples of long-living (as opposed to long dead) branches.
> 
> Well, the Unicode branch was certainly one of the most impressively
> long-lived branches.  Multitty had a non-trivial life-time as well, and
> lexbind has been around for even longer than Unicode IIRC.

I had all those in mind.  3 or 4 are still very small numbers, and you
are talking about what? 4 years?

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

[Eli Zaretskii]

> From: Óscar Fuentes <ofv@wanadoo.es>
> Date: Fri, 01 Apr 2011 22:21:52 +0200
> 
> So you are in favor of using revnos when you know that the revision you
> are referencing is on trunk, and revids otherwise?

I see no problem with what we do now.

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

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

[snip]

>> > It is very easy to see that revision, even if it is on the other
>> > branch, assuming that the referenced branch is in your repo, with the
>> > "revno:NNN:/path/to/branch" revision identifier.
>> 
>> Precisely, what I described above was a setup where having the "other
>> branch" (say better "the other brancheS") is a burden. So I don't have
>> them.
>
> The above works with URLs as well, of course.  You don't need to have
> the branches locally.

URLs are useless when you have no internet. I usally work on my hobby
projects on isolated places.

In general you are assuming that others share your work environment,
views and practices. Please note that the transition to a dVCS removed a
lot of implicit policies.

Anyways I was just suggesting a sane practice for any project: avoid
ambiguity on communication. Commit messages are communication devices
just like code comments, function names, etc. You write them once, but
are read a million times. You can argue that a revno is as clear as a
revid for those working on trunk. I say that it is a burden for those
who work on branches, and a potential source of confussion if the
practice is used by those who work on branches.

I've made my point. Now, everyone do as you please. 

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

[Stephen J. Turnbull]

Uday S Reddy writes:

 > So, a reference to revision 43 inside a branch that starts from
 > revision 42 is very very likely to be a local reference.

OK, you win.

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

[Uday S Reddy]

On 4/1/2011 9:21 PM, Óscar Fuentes wrote:

>
> So you are in favor of using revnos when you know that the revision you
> are referencing is on trunk, and revids otherwise?

Dear Oscar, In the subthread started by Stephen Turnbull, I have argued 
that it is easy enough to decode revision numbers as long as they are 
referring to the mainline or the local branch.  He has agreed with that 
argument.

Can you comment on whether this convention suits you?

Cheers,
Uday

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

[Juanma Barranquero]

On Fri, Apr 1, 2011 at 17:55, Óscar Fuentes <ofv@wanadoo.es> wrote:

> Once Emacs switched to a dVCS, it is a distributed project. You can
> insist on its centralization all the time, but the truth is that working
> on Emacs on a distributed way is a decisions that now belongs to each
> and every hacker. I can have my private branches, I can publish them
> from my machine, I can exchange revisions with other hackers. Eventually
> I can contribute those changes to "central" Emacs, but the process was
> distributed all the way, because I chose to do so. Whatever informal
> policy some Emacs hackers follow, it is irrelevant to me.

Or, to see it from the other side, the way some people use the dVCS to
"develop in a distributed way" is irrelevant to the Emacs project
policies... because, as has already been said, the project is
currently, and for the foreseeable future, using a centralized
repository.

> This looks like defeatism :-)

s/defe/pragm/;

> Maybe you perceive the issue as FUD because your workflow?

Yeah. Maybe you see the issue as very big because of yours?

> I admit that the problem is negligible *now*.

I'm glad we agree.

> How much importance it
> will adquire on the future depends on how Emacs development evolves. You
> say it will not turn serious because Emacs development will not
> change. Okay, time will tell.

No, I'm saying we can cross that bridge once we reach it.

    Juanma

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

[Óscar Fuentes]

Uday S Reddy <u.s.reddy@cs.bham.ac.uk> writes:

> On 4/1/2011 9:21 PM, Óscar Fuentes wrote:
>
>>
>> So you are in favor of using revnos when you know that the revision you
>> are referencing is on trunk, and revids otherwise?
>
> Dear Oscar, In the subthread started by Stephen Turnbull, I have
> argued that it is easy enough to decode revision numbers as long as
> they are referring to the mainline or the local branch.  He has agreed
> with that argument.
>
> 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:

16 merge uday's awesome feature into trunk
16.1.2 Fix bug introduced on revision 11
16.1.1 Implement awesome feature
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
....

So 16.1.2 mentions revision 11, which is wrong.

Other issues with your proposal are:

 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.

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

 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.

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

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

[Chong Yidong]

Óscar Fuentes <ofv@wanadoo.es> writes:

> The Emacs project has a number of branches published on a well-known
> site, and hopefully other branches distributed along a number of
> personal machines. I'm saying that using revision numbers is confusing
> when those revisions are merged across branches. Across *any* branches,
> including the "random" ones (whatever your definition of "random branch"
> is.)

Most commit messages containing revision numbers seem to refer to things
like reverting the changes in a prior revision.  Here, there is not much
scope for ambiguity, so I think the practice is acceptable.

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

[Stephen J. Turnbull]

Uday S Reddy writes:

 > Dear Oscar, In the subthread started by Stephen Turnbull, I have argued 
 > that it is easy enough to decode revision numbers as long as they are 
 > referring to the mainline or the local branch.

No, I've agreed that I'm not going to change your mind, that's all.
"Easy enough" is a matter of taste.  "De gustibus non est disputandum."

I encourage Óscar to stop wasting his time on this, too, as Stefan has
pronounced the official policy.

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

[Uday S Reddy]

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

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

[Óscar Fuentes]

Uday S Reddy <u.s.reddy@cs.bham.ac.uk> writes:

> 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

You are right.

[snip]

> 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".

Yes, that works as long as those commits are merged in the same
operation.

But even on that case we would be better without the arithmetic. Think a
feature branch with dozens or hundreds of commits. And I'm not talking
just about commit messages. References on bug reports or e-mail
exchanges suffer from the same.

[snip]

>>   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.

My branch log doesn't show the revnos of trunk as they are on trunk, but
some renumbered version. As you mention, I can start counting merged
revisions across merge points until reaching the referenced revision,
but that's impractical.

[snip]

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

[Uday S Reddy]

On 4/2/2011 2:47 PM, Óscar Fuentes wrote:

>
>> 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".
>
> Yes, that works as long as those commits are merged in the same
> operation.

I think it always works independent of how you merge.  The local 
revision 11 will always be 10.x.1 and local revision 12 will always be 
10.x.2.  Whether you merge in one steps or multiple steps doesn't make a 
difference.

> But even on that case we would be better without the arithmetic. Think a
> feature branch with dozens or hundreds of commits. And I'm not talking
> just about commit messages. References on bug reports or e-mail
> exchanges suffer from the same.

In that case, you are talking about a tradeoff, what will be easier to 
the committer versus what will be easier for somebody to analyze things 
later on.  My feeling is that committing is done much more often and 
doing additional chores in the middle of committing is distracting.  So 
I would want to make it easier for committing.

If one states the branch nickname and the original revision id on the 
branch, then it can always be found on the trunk after merging.  You can 
find the branch nickname in the log and then do the little bit of 
arithmetic to find the right revision.

When bug reports are submitted for a branch, the Emacs reporter should 
be including the branch nickname as part of the version information (if 
it isn't doing so already).  That would ensure that the context is included.

> My branch log doesn't show the revnos of trunk as they are on trunk, but
> some renumbered version. As you mention, I can start counting merged
> revisions across merge points until reaching the referenced revision,
> but that's impractical.

Every revision is marked by the branch nick(name) and a revision number. 
  If the branch nick is stated as "trunk" for a top-level revision then 
it is the revision number on the trunk.  Otherwise, it is your local 
revision which would again be identified by your branch nick.

There is no counting involved.  A maximum of one addition or subtraction.

And, it should also be easy enough to write an Emacs command or two to 
automate it.

Cheers,
Uday

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

[Óscar Fuentes]

Uday S Reddy <u.s.reddy@cs.bham.ac.uk> writes:

[snip]

>> But even on that case we would be better without the arithmetic. Think a
>> feature branch with dozens or hundreds of commits. And I'm not talking
>> just about commit messages. References on bug reports or e-mail
>> exchanges suffer from the same.
>
> In that case, you are talking about a tradeoff, what will be easier to
> the committer versus what will be easier for somebody to analyze
> things later on.  My feeling is that committing is done much more
> often and doing additional chores in the middle of committing is
> distracting.  So I would want to make it easier for committing.

I see that as a tradeoff writer vs readers. As explained elsewhere, you
write things once but they are read lots of times. It is the same case
as naming functions and writing comments.

[snip]

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

[Uday S Reddy]

Óscar Fuentes writes:

> I see that as a tradeoff writer vs readers. As explained elsewhere, you
> write things once but they are read lots of times. It is the same case
> as naming functions and writing comments.

That is of course a very good point.  Revision notes should be easy
enough to read, but *analyzing* them might involve some work.  In
practice, it involves a lot of work, and one addition/subtraction
isn't going to make much of a difference.

Going back to your original example, which is presumably fictitious:

> If I'm reading the VC log on a random branch and see "Fix breakage
> introduced by rXXXX" and want to look at the referenced revision,
> ...

the problem with such a note is that it says precious little unless
you go and find the revision XXXX.  Those of us that write technical
articles have been taught to use the convention that the text should
stand on its own without having to follow the cross-references to
understand what it is saying.  (I have been told that it is what is
recommended by the Chicago Manual of Style, though I haven't read the
manual myself.)  Your example fails that test.  If there is enough
information in the note for the reader to decide whether it is
necessary to follow the cross-reference, then readability would be
preserved.

The various real examples cited by Juanma seem to be mostly fine.

Cheers,
Uday

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

[Nils Ackermann]

Juanma Barranquero <lekktu@gmail.com> writes:

> Sure I do. And you know why? Because Bazaar revnos are *convenient*,
> and Bazaar revids are a royal PITA. I don't want to abandon convenient
> shorthands for what, at the moment, is just FUD.

They are a convenience only locally in space (branch) and time (bzr
version).  Bazaar provides no guarantee with respect to stability of
revision numbers.

For example, revision numbers may change if one pushes by accident to a
(public) branch that should not be pushed to, and that doesn't have the
`append-revisions-only'-property set (it has happened before, even to
trunk, as far as I can recall).

More importantly, revision numbers not only depend on the branch, but
also on the bzr version.  I recall that the numbering, which is only
calculated at use time, has changed twice since 2005.  As recently as a
year ago there was a discussion on new ideas for calculating revision
numbers:

http://thread.gmane.org/gmane.comp.version-control.bazaar-ng.general/67756

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

[Juanma Barranquero]

On Mon, Apr 4, 2011 at 18:32, Nils Ackermann <nils-gmane@ackermath.info> wrote:

> As recently as a
> year ago there was a discussion on new ideas for calculating revision
> numbers:

I'll be happy to switch to using revids as soon as they give the users
more convenient way to handle them.  The current schema of
email-yyyymmddhhmmss-randomshit does not give itself easily to
abbreviation.

    Juanma

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

[Lennart Borgman]

On Mon, Apr 4, 2011 at 11:27 PM, Juanma Barranquero <lekktu@gmail.com> wrote:
> On Mon, Apr 4, 2011 at 18:32, Nils Ackermann <nils-gmane@ackermath.info> wrote:
>
>> As recently as a
>> year ago there was a discussion on new ideas for calculating revision
>> numbers:
>
> I'll be happy to switch to using revids as soon as they give the users
> more convenient way to handle them.  The current schema of
> email-yyyymmddhhmmss-randomshit does not give itself easily to
> abbreviation.

In what way is it difficult to handle the current schema? (I guess you
never type the revid?)

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

[Juanma Barranquero]

On Mon, Apr 4, 2011 at 23:36, Lennart Borgman <lennart.borgman@gmail.com> wrote:

> In what way is it difficult to handle the current schema? (I guess you
> never type the revid?)

Git ids hare 40-char "random" strings, but they are hashes, so they
vary from the start, and most of the time you get around by typing
just 6 to 8 chars. Bazaar ids are longer (14 char timestamps + 16 char
random string + 2 separators + e-mail, so longer unless the e-mail is
shorter than 8 chars) and for a given year and user, the first
significant character is at (length e-mail) + 5... but even if the
random string were at the start would still be irrelevant because the
Bazaar interface doesn't allow shortening revids. You have to type
them in full.

If they allowed passing just the random-string part it would be a bit
easier. As it is, you always have to type long strings, or cut&paste
them.

    Juanma

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

[Lennart Borgman]

On Mon, Apr 4, 2011 at 11:49 PM, Juanma Barranquero <lekktu@gmail.com> wrote:
> On Mon, Apr 4, 2011 at 23:36, Lennart Borgman <lennart.borgman@gmail.com> wrote:
>
>> In what way is it difficult to handle the current schema? (I guess you
>> never type the revid?)
>
> Git ids hare 40-char "random" strings, but they are hashes, so they
> vary from the start, and most of the time you get around by typing
> just 6 to 8 chars. Bazaar ids are longer (14 char timestamps + 16 char
> random string + 2 separators + e-mail, so longer unless the e-mail is
> shorter than 8 chars) and for a given year and user, the first
> significant character is at (length e-mail) + 5... but even if the
> random string were at the start would still be irrelevant because the
> Bazaar interface doesn't allow shortening revids. You have to type
> them in full.
>
> If they allowed passing just the random-string part it would be a bit
> easier. As it is, you always have to type long strings, or cut&paste
> them.

Cut&paste is perhaps not that awful. If it really is then perhaps
Emacs could provide some completion (if bzr has can support it).

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

[Juanma Barranquero]

On Tue, Apr 5, 2011 at 00:03, Lennart Borgman <lennart.borgman@gmail.com> wrote:

> Cut&paste is perhaps not that awful. If it really is then perhaps
> Emacs could provide some completion (if bzr has can support it).

I'm not talking inside Emacs. Most revnos I type I do from the command line.

    Juanma

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

[Stefan Monnier]

>> As recently as a year ago there was a discussion on new ideas for
>> calculating revision numbers:
> I'll be happy to switch to using revids as soon as they give the users
> more convenient way to handle them.  The current schema of
> email-yyyymmddhhmmss-randomshit does not give itself easily to
> abbreviation.

Agreed, rev-ids are inconvenient to use (and really ugly: SHA-1 hashes
are visually stunning in comparison).  That's why I use dates instead.
They're also good in ChangeLog since the date can be used the find the
relevant commit without using Bzr at all.


        Stefan

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

[Juanma Barranquero]

On Tue, Apr 5, 2011 at 00:27, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Agreed, rev-ids are inconvenient to use (and really ugly: SHA-1 hashes
> are visually stunning in comparison).

Irony, on emacs-devel? Shame on you, Stefan, shame on you.

> That's why I use dates instead.
> They're also good in ChangeLog since the date can be used the find the
> relevant commit without using Bzr at all.

I couldn't agree more; that's why I usually write the revno *and* the date ;-)

    Juanma

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

[Stephen J. Turnbull]

Uday S Reddy writes:

 > the problem with such a note is that it says precious little unless
 > you go and find the revision XXXX.

I don't think Óscar meant that as an example of log style.  He was
focusing on the the issue of following the reference to a revision.

 > Those of us that write technical articles have been taught to use
 > the convention that the text should stand on its own without having
 > to follow the cross-references to understand what it is saying.

Sorry, but you're misrepresenting the convention you cite.  Editors of
technical articles require both well-written notes and bibliographies
"for those proofs that won't fit in this narrow margin."  Similarly,
the revision log should describe the semantics of the change, while
the diff against the revision gives its syntax.

Therefore, a commit log message should both describe the change made,
and provide a machine-friendly cross-reference (machine-friendly
because this is Emacs; we may expect that the developers will have
machine assistance in following cross-references).  I think there are
more important things for the people who will be writing the log
browser to do than catch the edge cases that your algorithm doesn't
handle, since the browser mode doesn't exist yet.  OTOH,
change-log-mode does exist; adding something to find and insert
unambiguous revision identifiers from any revision specification seems
to be more in scope.

FWIW IMHO YMMV.  HAND.

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

[Thien-Thi Nguyen]

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

[Thien-Thi Nguyen]

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

[Stefan Monnier]

>>>>> "Thien-Thi" == Thien-Thi Nguyen <ttn@gnuvola.org> writes:
> [void]

I'm not sure I agree.


        Stefan

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

[Stephen J. Turnbull]

Stefan Monnier writes:
 > >>>>> "Thien-Thi" == Thien-Thi Nguyen <ttn@gnuvola.org> writes:
 > > [void]
 > 
 > I'm not sure I agree.

But it's vacuously true!

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

[Thien-Thi Nguyen]

() "Stephen J. Turnbull" <stephen@xemacs.org>
() Wed, 06 Apr 2011 11:55:05 +0900

   Stefan Monnier writes:

    > I'm not sure I agree.

   But it's vacuously true!

Yes, if the surrounding control operator is ‘and’.  The accumulating
nature (outer form) of mailing list threads might suggest that it is
‘and’, but the substance (inner form) is often ‘or’, as in this case:

The intent was originally to comment on the unsuitability of date-only
disambiguation in the face of push races, but then i realized (after
having goofed twice) that date of commit and date of authorship being
different can indeed provide a toe-grip.

Sorry for the noise; back to the grind...