Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Juanma Barranquero]

On Mon, Mar 3, 2014 at 6:03 PM, Glenn Morris <rgm@gnu.org> wrote:

>   ChangeLog entries should be usable without the VCS

I disagree.

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[David Kastrup]

Juanma Barranquero <lekktu@gmail.com> writes:

> On Mon, Mar 3, 2014 at 6:03 PM, Glenn Morris <rgm@gnu.org> wrote:
>
>>   ChangeLog entries should be usable without the VCS
>
> I disagree.

As long as our primary distribution medium is a tarball containing a
ChangeLog, that disagreement does not make a lot of sense.

A ChangeLog that is only usable with the VCS seems like it should rather
be folded into the VCS in the first place.

-- 
David Kastrup

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Juanma Barranquero]

On Mon, Mar 3, 2014 at 6:31 PM, David Kastrup <dak@gnu.org> wrote:

> As long as our primary distribution medium is a tarball containing a
> ChangeLog, that disagreement does not make a lot of sense.

I question your axiom: our "primary distribution method" is a tarball,
for people (and GNU/Linux distributions) who builds Emacs, not that
modifies it or fixes bugs. I'd be surprised to discover that people
tinkering with Emacs innards' (outside emacs-devel people, I mean) do
it without accessing the public repo.

I don't think the ChangeLogs make much sense without access to the
history. The last few entries (or the last few hundred), perhaps.
Older than that, they talk about code or functions or variables (or
sometimes files) that often don't exist anymore, or have been
rewritten from scratch, or modified in ways that a simple ChangeLog
description doesn't really explain enough about. It'd be interesting
to know if there's people out there who delves into the Emacs code
without accessing the public repository, and who, *simultaneously*,
find the ChangeLogs significantly useful.

But the point is moot. I disagree, but I'm not going to reintroduce
the reference.

> A ChangeLog that is only usable with the VCS seems like it should rather
> be folded into the VCS in the first place.

Isn't that what Stefan wants to do?

    J

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Alan Mackenzie]

On Mon, Mar 03, 2014 at 06:09:16PM +0100, Juanma Barranquero wrote:
> On Mon, Mar 3, 2014 at 6:03 PM, Glenn Morris <rgm@gnu.org> wrote:

> >   ChangeLog entries should be usable without the VCS

> I disagree.

One feels at this stage that a critical amount of context has been
expunged here.  Is this a side-thread of a previously existing thread?
If so, what was its subject?

What is meant by a ChangeLog "entry"?  The ChangeLog is a text file,
therefore its entries are trivially "usable" (whatever that's meant to
mean) by visiting it in Emacs.

Is somebody proposing making ChangeLog entries somehow "unusable"?  If
so, I'm against such a proposal.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Juanma Barranquero]

On Mon, Mar 3, 2014 at 7:09 PM, Alan Mackenzie <acm@muc.de> wrote:

> Is somebody proposing making ChangeLog entries somehow "unusable"?  If
> so, I'm against such a proposal.

No one is proposing anything, I think. I included a reference to a
revno, Glenn changed it. I disagree with the philosophy behind the
change (I mean, we won't be able to include references to git ids in
ChangeLog entries after the switch?), but not with the change per se.

    J

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Dmitry Gutov]

Juanma Barranquero <lekktu@gmail.com> writes:

> No one is proposing anything, I think. I included a reference to a
> revno, Glenn changed it. I disagree with the philosophy behind the
> change (I mean, we won't be able to include references to git ids in
> ChangeLog entries after the switch?)

FWIW, I also disagree.

Being able to refer to commits directly is very useful, and especially
in Git where revision identifiers (hashes) are global.

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Andreas Schwab]

Dmitry Gutov <dgutov@yandex.ru> writes:

> Being able to refer to commits directly is very useful, and especially
> in Git where revision identifiers (hashes) are global.

Using only the hash is frowned upon, the best practice is to follow it
with the subject of the commit message.

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: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Alan Mackenzie]

Hi, Andreas.

On Mon, Mar 03, 2014 at 10:23:22PM +0100, Andreas Schwab wrote:
> Dmitry Gutov <dgutov@yandex.ru> writes:

> > Being able to refer to commits directly is very useful, and especially
> > in Git where revision identifiers (hashes) are global.

> Using only the hash is frowned upon, the best practice is to follow it
> with the subject of the commit message.

Is this because the hashes don't count as human-readable, in contrast to
the sequential revision numbers that other systems (such as bzr and hg)
use?

> Andreas.

> -- 
> Andreas Schwab, schwab@linux-m68k.org

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Andreas Schwab]

Alan Mackenzie <acm@muc.de> writes:

> Hi, Andreas.
>
> On Mon, Mar 03, 2014 at 10:23:22PM +0100, Andreas Schwab wrote:
>> Dmitry Gutov <dgutov@yandex.ru> writes:
>
>> > Being able to refer to commits directly is very useful, and especially
>> > in Git where revision identifiers (hashes) are global.
>
>> Using only the hash is frowned upon, the best practice is to follow it
>> with the subject of the commit message.
>
> Is this because the hashes don't count as human-readable, in contrast to
> the sequential revision numbers that other systems (such as bzr and hg)
> use?

Neither revision numbers nor hashes are readable.

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: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Alan Mackenzie]

'Evening, Andreas!

On Mon, Mar 03, 2014 at 11:28:24PM +0100, Andreas Schwab wrote:
> Alan Mackenzie <acm@muc.de> writes:

> > Hi, Andreas.

> > On Mon, Mar 03, 2014 at 10:23:22PM +0100, Andreas Schwab wrote:
> >> Dmitry Gutov <dgutov@yandex.ru> writes:

> >> > Being able to refer to commits directly is very useful, and especially
> >> > in Git where revision identifiers (hashes) are global.

> >> Using only the hash is frowned upon, the best practice is to follow it
> >> with the subject of the commit message.

> > Is this because the hashes don't count as human-readable, in contrast to
> > the sequential revision numbers that other systems (such as bzr and hg)
> > use?

> Neither revision numbers nor hashes are readable.

On the contrary, r116644 is eminently readable and memorisable, so much
so that I was able to transfer it to a "bzr log -r116644" instruction
without even having to bother with copy and paste.

Earlier on in the evening, I'd just done an informal bisect on the CC
Mode repository using "hg cat -r768", etc.  Worked like a dream.

Things are a bit different if you've got to use some arbitrary head of
something like df91e9880a3156ae1d236e88f.....

> Andreas.

> -- 
> Andreas Schwab, schwab@linux-m68k.org

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Andreas Schwab]

Alan Mackenzie <acm@muc.de> writes:

> On the contrary, r116644 is eminently readable and memorisable,

It doesn't tell you what it is about.

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: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Stephen J. Turnbull]

Alan Mackenzie writes:
 > 'Evening, Andreas!

 > > Neither revision numbers nor hashes are readable.
 > 
 > On the contrary, r116644 is eminently readable and memorisable,

But here we're discussing use in log messages.  Besides Andreas' point
about lack of log information, unlike the hash, it's context-dependent
and unstable.  It means different things in different branches, and
even different things in different instances of (what users consider
to be) the *same* branch.  Consider:

Before merge:

trunk branch (== working copy of trunk, cloned at r10)

  |     |
 r10 = r10
  |     |
 r11   r11
        |
       r12 ... "fix bug introduced in r11"

Note two r11s, and the log message refers to the unstable one.  After
merging into trunk:

  |
 r10
  |\
  | \
  |  r10.1.1
 r11    |
  |  r10.1.2 ... "fix bug introduced in r11"
  | /
  |/
 r12

After pulling merge back into branch:

  |
 r10
  |\
  | \
  |  r10.1.1
 r11    |
  |  r10.1.2 ... "fix bug introduced in r11"
  | /
  |/
 r12

Oops.  This happens because bzr pull insists on duplicating the DAG,
which is nice for later development in some ways.  You could merge
from trunk instead of pulling, which would preserve the branch's
numbering.  But then the DAGs are different, and after merges to trunk
bzr log will show those merges as spurious isolated merge commits.

As far as I can see, there is no way to refer stably to a revision in
a non-trunk branch from a later revision in that branch, unless it is
never merged into another branch at all.  It's even unsafe in the same
branch if you may pull from upstream.

Often, perhaps most of the time, a fix in branch will use a revision
number reference because it happened "far away", probably in trunk (or
a branch already merged to trunk and obsoleted).  In the case of
revision numbers referring to trunk numbering, this will be OK.  I
prefer the much higher reliability (ie, SHA1 collision probability) of
hashes since both are unreadable in Andreas' sense, but YMMV.

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Date: Tue, 04 Mar 2014 17:26:14 +0900
> Cc: Juanma Barranquero <lekktu@gmail.com>, Dmitry Gutov <dgutov@yandex.ru>,
> 	Andreas Schwab <schwab@linux-m68k.org>,
> 	Emacs developers <emacs-devel@gnu.org>
> 
> Alan Mackenzie writes:
>  > 'Evening, Andreas!
> 
>  > > Neither revision numbers nor hashes are readable.
>  > 
>  > On the contrary, r116644 is eminently readable and memorisable,
> 
> But here we're discussing use in log messages.

No, we are discussing ChangeLog entries, see the subject line.

For commit log messages, Glenn, whose change started this thread, does
use references to bzr revision numbers, even across branches:

  115194: Glenn Morris 2013-11-23 [merge] Merge from emacs-24; up to r111408

So what you say about bzr revision numbers is not really relevant to
the subject of this thread.

> After pulling merge back into branch:
> 
>   |
>  r10
>   |\
>   | \
>   |  r10.1.1
>  r11    |
>   |  r10.1.2 ... "fix bug introduced in r11"
>   | /
>   |/
>  r12
> 
> Oops.  This happens because bzr pull insists on duplicating the DAG,

No oops.  "bzr pull" makes the target branch a perfect clone
(a.k.a. "mirror") of the source branch.  This in effect nukes the
previous history of the target branch, and replaces it with that of
trunk.  Therefore, pulling from trunk into a branch that doesn't track
trunk is (or should be, at least IMO) done only when the branch's
previous history is no longer interesting, and thus its revno's are
not important.

IOW, a user who "bzr pull"s like that actually _asks_ for the above to
happen.  She asked to destroy the previous history of the branch.  I
agree that referencing revision numbers of such ephemeral branches and
then merging those commits to trunk is unwise at best.  But again,
this is not what started this thread.

> You could merge from trunk instead of pulling, which would preserve
> the branch's numbering.  But then the DAGs are different, and after
> merges to trunk bzr log will show those merges as spurious isolated
> merge commits.

They are not spurious.  They mark the merges and record the parents.

> As far as I can see, there is no way to refer stably to a revision in
> a non-trunk branch from a later revision in that branch, unless it is
> never merged into another branch at all.

??? As long as the branch history exists and is not overwritten by
pulling from a divergent branch, referencing its own revisions is
stable, AFAIK.  Whether it is wise to do that in branches that are
intended to be merged onto trunk is another question (and my answer is
"probably no").

> It's even unsafe in the same branch if you may pull from upstream.

AFAIU, you should never "bzr pull" from a divergent branch, unless you
want to nuke the history of yours, or as a shortcut of removing the
branch and cloning the remote one anew.

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Dmitry Gutov]

Andreas Schwab <schwab@linux-m68k.org> writes:

> Using only the hash is frowned upon, the best practice is to follow it
> with the subject of the commit message.

Considering that many commits in Emacs don't have an actual subject
(only a list of changes, changelog-style), that won't always be possible.

And when they have, inserting the whole line may be too much. But if you
replace "the subject" with "a few words from the message", it would
work.

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Glenn Morris]

The ChangeLog should be understandable to someone sitting there with
just the source tarball and no VCS. "Fix revno:foo" is literally useless
to such a person. There's nothing to discuss here. Git hashes versus bzr
revisions, generated ChangeLogs, what gets written in *commit* logs, the
various ways people access the Emacs sources, it's all irrelevant.

Anyway, none of this gets us any closer to 24.4.
So I hope this thread will die, and that people with the time to comment
will instead look at documenting the remaining issues in NEWS and fixing
the numerous outstanding bugs.

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Juanma Barranquero]

On Tue, Mar 4, 2014 at 6:28 PM, Glenn Morris <rgm@gnu.org> wrote:

> The ChangeLog should be understandable to someone sitting there with
> just the source tarball and no VCS.

As previously stated, I disagree because I don't think these people
are the real target. The ChangeLogs already do not match that
description. Some entries, particularly the more recent ones, if
unusually well written, *might* approach that goal, but most won't,
not without looking at the corresponding changesets. I know that for a
fact: I often look at the ChangeLog entry, then to the annotate
listing, and then to the diff to really see what was going on.

Our ChangeLogs, much as I like them and don't want to see them go, are
in that nebulous place between being a list of changes for outside
people (not really, too verbose and rambling*, that's what NEWS is for
and does a much better job), and a complete list of changes for the
source code tinkerer and developer (it isn't near complete enough, for
serious work you need the repo). So the goal that our ChangeLogs
satisfy right now is as a helpful tool to speed locating relevant
changes, or as a (incomplete) reminder of when was something done, and
by whom.

(*Like many of my posts ;-)

If you think that I'm exaggerating and our ChangeLogs are really
pretty complete, I posit that, as an example, while "Follow-up to
revno:XXXX" doesn't say much, "Fix last change." doesn't really say
much more (yes, you can locate the change it refers to, but, how was
it fixed, and what was the problem that required such fixing?). And
there are literally hundreds of such entries in our ChangeLogs.

> Git hashes versus bzr
> revisions, generated ChangeLogs, what gets written in *commit* logs, the
> various ways people access the Emacs sources, it's all irrelevant.

No, I don't think so.

> Anyway, none of this gets us any closer to 24.4.
> So I hope this thread will die, and that people with the time to comment
> will instead look at documenting the remaining issues in NEWS and fixing
> the numerous outstanding bugs.

Writing docs, no thanks. Unable to. As for the rest, my feature-freeze
patches are all bug fixes or typo fixes (which are bugs IMO); so I
tend to agree.

   J

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[David Kastrup]

Juanma Barranquero <lekktu@gmail.com> writes:

> On Tue, Mar 4, 2014 at 6:28 PM, Glenn Morris <rgm@gnu.org> wrote:
>
>> The ChangeLog should be understandable to someone sitting there with
>> just the source tarball and no VCS.
>
> As previously stated, I disagree because I don't think these people
> are the real target.

The tarball _is_ the corresponding source to a version of Emacs.  That's
what the GPL will guarantee to provide.  Nothing else is guaranteed to
be available to somebody getting binaries to some version of Emacs.

As long as we decide it is part of the corresponding source (I don't see
that it has to according to the definition of the GPL) and distribute it
with it, it should be useful on its own.

-- 
David Kastrup

Re: [Emacs-diffs] trunk r116644: ChangeLog entries should be usable without the VCS

[Juanma Barranquero]

On Tue, Mar 4, 2014 at 7:13 PM, David Kastrup <dak@gnu.org> wrote:

> The tarball _is_ the corresponding source to a version of Emacs.  That's
> what the GPL will guarantee to provide.  Nothing else is guaranteed to
> be available to somebody getting binaries to some version of Emacs.

That does not mean that everything included in the tarball is useful
per se, or that the ChangeLogs are (or aren't). At the end, it's
having the *source* (and Makefiles, config, and everything that allows
to rebuild the software) what gives freedom to the user. ChangeLogs
are a (tiny) help. We could strip them from our tarballs and it
wouldn't be a catastrophe, as witnessed by the fact that many projects
do not keep ChangeLogs.

   J