GNU bug report logs - #21998
Run 'make change-history' on release branch

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 21998 in the body.
You can then email your comments to 21998 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #3 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: submit <at> debbugs.gnu.org
Subject: Run 'make change-history' on release branch
Date: Mon, 23 Nov 2015 14:08:20 -0500

Package: emacs
Version: 25.0.50

It needs to be possible to run 'make change-history' on the release branch.
See discussion in

http://lists.gnu.org/archive/html/emacs-devel/2015-11/msg01461.html

Message #10 received at 21998-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: 21998-done <at> debbugs.gnu.org
Subject: Re: Run 'make change-history' on release branch
Date: Fri, 12 Feb 2016 16:52:07 -0800

This was done by Nicolas Petton on 2016-01-30 in commit 
a4ab2a563a062e76b9e79befd3a80fdbea523f16 so I am marking the bug as done.

Message #13 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 21998 <at> debbugs.gnu.org
Cc: eggert <at> cs.ucla.edu
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Tue, 16 Feb 2016 11:41:28 -0500

The point of this report was that merging between branches will create a
complete mess. Simply ignoring the actual issue doesn't constitute a fix.

Message #18 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Glenn Morris <rgm <at> gnu.org>, 21998 <at> debbugs.gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Tue, 16 Feb 2016 09:54:20 -0800

On 02/16/2016 08:41 AM, Glenn Morris wrote:
> The point of this report was that merging between branches will create a
> complete mess. Simply ignoring the actual issue doesn't constitute a fix.

Ah, sorry, I misinterpreted the original report, which talked only about 
the ability to run 'make change-history' on the release branch. Although 
that's doable now, obviously more work needs to be done as far as 
merging goes. I reopened the bug report with that in mind.

Message #21 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 21998 <at> debbugs.gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Fri, 04 Mar 2016 11:46:49 -0500

Glenn Morris wrote:

> The point of this report was that merging between branches will create a
> complete mess.

I hope people appreciate this point.

For example, the Feb 15th merge skipped the "Auto-commit of ChangeLog" 
cc6d906  but did not skip "make change-history-commit" 2b7d006.
Obviously this makes no sense and means the master ChangeLog is in some
weird messed-up state. But even without this specific problem, it still
would be, since, as I said a long time ago, AFAICS there's no sensible
way to merge this stuff between branches, which is why it was disabled
on non-master branches to start with.

At this point, I give up, since it seems fairly clear that maintaining
an accurate ChangeLog just isn't of interest. Even the bare minimum
legally relevant mistakes (missing "tiny change") don't seem to be being
corrected. Probably just deleting it from the repo would be more honest.
This will simplify things, eg the "correct log entries" step for making
a release can be dropped, and the AUTHORS file can become less accurate.
A rough non-versioned ChangeLog can still be generated for tarballs, if
anyone cares. Or, a version of the above, stop keeping a versioned copy
on any branch but master.

Message #24 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>, John Wiegley <johnw <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Sat, 05 Mar 2016 21:11:40 +0200

> From: Glenn Morris <rgm <at> gnu.org>
> Date: Fri, 04 Mar 2016 11:46:49 -0500
> 
> At this point, I give up, since it seems fairly clear that maintaining
> an accurate ChangeLog just isn't of interest. Even the bare minimum
> legally relevant mistakes (missing "tiny change") don't seem to be being
> corrected. Probably just deleting it from the repo would be more honest.
> This will simplify things, eg the "correct log entries" step for making
> a release can be dropped, and the AUTHORS file can become less accurate.
> A rough non-versioned ChangeLog can still be generated for tarballs, if
> anyone cares. Or, a version of the above, stop keeping a versioned copy
> on any branch but master.

I think if we care at all about having ChangeLog in the releases, we
should simply reinstate the file and maintain it in the repository.  I
think this one-year experiment clearly demonstrates that creating
ChangeLog from VCS logs simply doesn't work well enough.  Look how
much energy we invested in making that happen, and we are still
nowhere as close to the solution as we'd like to be.

OTOH, if one has git-merge-changelog installed, the conflicts in
merging ChangeLog are very rare, and their resolution is simple.

Other projects, like GDB, still maintain ChangeLog files, and don't
seem to have any problems.

So I'd say let's go back to maintaining a ChangeLog (a single file in
the top-level directory), if we want a ChangeLog in the releases.  And
if we don't do that, let's decide there will be no ChangeLog files in
the release tarballs at all, and stop worrying about these issues.
What we have been trying to do -- both eat the cake and have it --
simply doesn't work.

John?

Message #27 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, Glenn Morris <rgm <at> gnu.org>,
 John Wiegley <johnw <at> gnu.org>
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Sun, 06 Mar 2016 10:47:46 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> So I'd say let's go back to maintaining a ChangeLog (a single file in
> the top-level directory), if we want a ChangeLog in the releases.  And
> if we don't do that, let's decide there will be no ChangeLog files in
> the release tarballs at all, and stop worrying about these issues.
> What we have been trying to do -- both eat the cake and have it --
> simply doesn't work.

I agree, and I think we should ditch the ChangeLogs.  I think the
ChangeLog "style" encourages less informative commit log messages.  The
normal, free-form commit style encourages people explaining, in their
own words, why they do changes, and what they hope to achieve with
them.

The ChangeLog style, on the other hand, pretty much uselessly lists all
files and functions affected, and after getting all that formalism in
place, many people don't have more stamina left than to add "Fix bug".  :-)

The back-and-forth-and-back-again formalism we've gone for (add things
to ChangeLog and then make vc.el reformat it) is a hindrance to people
being able to contribute to Emacs development.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #30 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, John Wiegley <johnw <at> gnu.org>
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Sun, 6 Mar 2016 20:02:30 +0200

On 03/06/2016 11:47 AM, Lars Magne Ingebrigtsen wrote:

> I agree, and I think we should ditch the ChangeLogs.  I think the
> ChangeLog "style" encourages less informative commit log messages.  The
> normal, free-form commit style encourages people explaining, in their
> own words, why they do changes, and what they hope to achieve with
> them.

Whether it's "less" or "more", depends on what one is comparing to. I 
rather feel it establishes a quality baseline, and by being required to 
mention every change, you're encouraged to document them all at least 
somehow. And you can still prepend the whole thing with a free-form 
explanation, if it's needed.

So while the ChangeLog files can go, I'd rather we keep to that style in 
the commit messages. At least until we switch to some other well-defined 
standard.

> The ChangeLog style, on the other hand, pretty much uselessly lists all
> files and functions affected, and after getting all that formalism in
> place, many people don't have more stamina left than to add "Fix bug".  :-)

IME, except for trivial changes, writing a log entry takes comparatively 
little time compared to the rest (like designing and writing the code). 
Or maybe I'm just slow.

Message #33 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: John Wiegley <jwiegley <at> gmail.com>
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: 21998 <at> debbugs.gnu.org, Glenn Morris <rgm <at> gnu.org>,
 Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Sun, 06 Mar 2016 13:07:22 -0800

[Message part 1 (text/plain, inline)]

>>>>> Lars Magne Ingebrigtsen <larsi <at> gnus.org> writes:

> I agree, and I think we should ditch the ChangeLogs. I think the ChangeLog
> "style" encourages less informative commit log messages. The normal,
> free-form commit style encourages people explaining, in their own words, why
> they do changes, and what they hope to achieve with them.

I have always wanted to drop the ChangeLogs, so if the other developers agree,
I'm all for it. Keeping ChangeLog style in the commit entry is not terribly
useful either, since the diff output of log -p lets you know which function or
variable is being modified. I've never missed not having that ChangeLog data
in other projects, of any size. But that's up to the other developers and what
makes their lives easier.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

[signature.asc (application/pgp-signature, inline)]

Message #36 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Ingo Lohmar <i.lohmar <at> gmail.com>
To: John Wiegley <johnw <at> gnu.org>, Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: 21998 <at> debbugs.gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Sun, 06 Mar 2016 22:25:19 +0100

On Sun, Mar 06 2016 13:07 (-0800), John Wiegley wrote:
>
> I have always wanted to drop the ChangeLogs, so if the other developers agree,
> I'm all for it. Keeping ChangeLog style in the commit entry is not terribly
> useful either, since the diff output of log -p lets you know which function or
> variable is being modified. I've never missed not having that ChangeLog data
> in other projects, of any size. But that's up to the other developers and what
> makes their lives easier.

+1

I am but a lowly one- or two-time committer to Emacs' core, but I
definitely concur that the Changelogs are one extra entry barrier to
contribution, especially for starters or not-so-frequent contributors.

And incidentally, I messed up the Changelog not too long ago and others
patiently helped me out.

Message #39 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: John Wiegley <jwiegley <at> gmail.com>
To: Emacs developers <emacs-devel <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Subject: Is it time to drop ChangeLogs? (Was: bug#21998: Run 'make
 change-history' on release branch)
Date: Sun, 06 Mar 2016 13:52:04 -0800

[Message part 1 (text/plain, inline)]

 On Sun, Mar 06 2016 13:07 (-0800), John Wiegley wrote:
> 
> I have always wanted to drop the ChangeLogs, so if the other developers agree,
> I'm all for it. Keeping ChangeLog style in the commit entry is not terribly
> useful either, since the diff output of log -p lets you know which function or
> variable is being modified. I've never missed not having that ChangeLog data
> in other projects, of any size. But that's up to the other developers and what
> makes their lives easier.

I'd like to open this up to discussion on emacs-devel, so that we hear from
our other developers. What do you all think about ChangeLogs, and their value
to you in your work on Emacs?

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

[signature.asc (application/pgp-signature, inline)]

Message #42 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: "Eric S. Raymond" <esr <at> thyrsus.com>
To: Emacs developers <emacs-devel <at> gnu.org>,
 Lars Magne Ingebrigtsen <larsi <at> gnus.org>, 21998 <at> debbugs.gnu.org
Subject: Re: Is it time to drop ChangeLogs? (Was: bug#21998: Run 'make
 change-history' on release branch)
Date: Sun, 6 Mar 2016 17:05:02 -0500

[Message part 1 (text/plain, inline)]

John Wiegley <jwiegley <at> gmail.com>:
>  On Sun, Mar 06 2016 13:07 (-0800), John Wiegley wrote:
> > 
> > I have always wanted to drop the ChangeLogs, so if the other developers agree,
> > I'm all for it. Keeping ChangeLog style in the commit entry is not terribly
> > useful either, since the diff output of log -p lets you know which function or
> > variable is being modified. I've never missed not having that ChangeLog data
> > in other projects, of any size. But that's up to the other developers and what
> > makes their lives easier.
> 
> I'd like to open this up to discussion on emacs-devel, so that we hear from
> our other developers. What do you all think about ChangeLogs, and their value
> to you in your work on Emacs?

I advocated dropping ChangeLogs at the time I did the repository conversion.
That is still my position.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

[signature.asc (application/pgp-signature, inline)]

Message #45 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Emacs developers <emacs-devel <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org
Subject: Re: Is it time to drop ChangeLogs? (Was: bug#21998: Run 'make
 change-history' on release branch)
Date: Sun, 6 Mar 2016 14:34:12 -0800

John Wiegley wrote:
> What do you all think about ChangeLogs, and their value
> to you in your work on Emacs?

I regularly do the equivalent of:

grep PATTERN $(git ls-files | grep -v ChangeLog)

That is, in searches I typically ignore ChangeLog* files because of their 
less-useful chatter. I'd be happy if we stopped maintaining these files in the 
master branch (we should keep them for emacs-25). I'd be happy if we removed the 
existing ChangeLog* files from the master branch.

Even if we remove ChangeLogs, we should still have guidelines for commit message 
format, as saying "anything goes" would make it harder to read the output of 
'git log'. I don't mind using ChangeLog format in commit messages, as it's a 
well-understood format and switching to some other format could well be more 
trouble than it's worth.

Message #48 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: John Wiegley <johnw <at> gnu.org>, Emacs developers <emacs-devel <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Subject: RE: Is it time to drop ChangeLogs? (Was: bug#21998: Run 'make
 change-history' on release branch)
Date: Sun, 6 Mar 2016 15:06:36 -0800 (PST)

Maybe see this thread?
http://lists.gnu.org/archive/html/emacs-devel/2013-03/msg00904.html

(FWIW, I have no opinion about where Emacs Dev puts change-log info.)

Message #51 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: John Wiegley <jwiegley <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21998 <at> debbugs.gnu.org, Lars Magne Ingebrigtsen <larsi <at> gnus.org>,
 Richard Stallman <rms <at> gnu.org>, Emacs developers <emacs-devel <at> gnu.org>
Subject: Re: Is it time to drop ChangeLogs?
Date: Sun, 06 Mar 2016 16:15:14 -0800

[Message part 1 (text/plain, inline)]

>>>>> Drew Adams <drew.adams <at> oracle.com> writes:

> Maybe see this thread?
> http://lists.gnu.org/archive/html/emacs-devel/2013-03/msg00904.html

I respect that Richard may use them in a constructive way, but he's no longer
doing the majority of the work on Emacs, and I want to choose the path that
works for the core developers, and will make Emacs more welcoming to new
contributors.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

[signature.asc (application/pgp-signature, inline)]

Message #54 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Mathieu Lirzin <mthl <at> gnu.org>
To: Emacs developers <emacs-devel <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Subject: Re: Is it time to drop ChangeLogs?
Date: Mon, 07 Mar 2016 01:22:11 +0100

Hi,

John Wiegley <jwiegley <at> gmail.com> writes:

>  On Sun, Mar 06 2016 13:07 (-0800), John Wiegley wrote:
>> 
>> I have always wanted to drop the ChangeLogs, so if the other developers agree,
>> I'm all for it. Keeping ChangeLog style in the commit entry is not terribly
>> useful either, since the diff output of log -p lets you know which function or
>> variable is being modified. I've never missed not having that ChangeLog data
>> in other projects, of any size. But that's up to the other developers and what
>> makes their lives easier.
>
> I'd like to open this up to discussion on emacs-devel, so that we hear from
> our other developers. What do you all think about ChangeLogs, and their value
> to you in your work on Emacs?

Discussing such thing seems reasonable.  However I don't think any
decision should be made by Emacs developpers on their own.  Change Logs
are part of the GCS so relaxing their requirement should be made at a
GNU level instead.

In my short experience, Change Logs has generally been useful both when
reading and composing them.  When writing them it helps me structure
large changes in logical commits that are modelled by the Change Log
format.  Finally It helps me being precise in my wordings which is not
trivial for non-native english speakers.

On a more spiritual side, I think they belong to the zen of contributing
to a GNU project.  :)

-- 
Mathieu Lirzin

Message #57 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: John Wiegley <johnw <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, Lars Magne Ingebrigtsen <larsi <at> gnus.org>,
 Richard Stallman <rms <at> gnu.org>, Emacs developers <emacs-devel <at> gnu.org>
Subject: RE: Is it time to drop ChangeLogs?
Date: Sun, 6 Mar 2016 16:24:15 -0800 (PST)

> > Maybe see this thread?
> > http://lists.gnu.org/archive/html/emacs-devel/2013-
> > 03/msg00904.html
> 
> I respect that Richard may use them in a constructive way, but he's
> no longer doing the majority of the work on Emacs, and I want to
> choose the path that works for the core developers, and will make
> Emacs more welcoming to new contributors.

I meant the thread, not that message.
I meant to link to the first, not the third, message of the thread:
http://lists.gnu.org/archive/html/emacs-devel/2013-03/msg00879.html

The point is that the subject was the same, so it might serve as
a good starting point now, to see what was said before about it.

Message #60 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: "Eric S. Raymond" <esr <at> thyrsus.com>
To: Mathieu Lirzin <mthl <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, Lars Magne Ingebrigtsen <larsi <at> gnus.org>,
 Emacs developers <emacs-devel <at> gnu.org>
Subject: Re: Is it time to drop ChangeLogs?
Date: Sun, 6 Mar 2016 20:19:58 -0500

Mathieu Lirzin <mthl <at> gnu.org>:
> On a more spiritual side, I think they belong to the zen of contributing
> to a GNU project.  :)

Dear Goddess, I hope you're joking.

Speaking as a very, *very* long-time GNU contributor (I'm pretty sure
my earliest Emacs patches predated the formation of the FSF), I
consider ChangeLogs a relic of a bygone era.

Changelogs made some sense as a way of grouping together what we now
call a changeset back in the days of file-oriented version-control
systems.  Nowadays, set against the actual changeset comments in
version-control histories, Changelogs are a pointless and duplicative
ritual.

I think we should have dispensed with this practice during the CVS-to-bzr
transition. As it is, the sooner gone the better.  It's not as if retaining
arbitrary hoops for new developers to have to jump through is a *good* idea.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Message #63 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Mon, 07 Mar 2016 01:51:17 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > At this point, I give up, since it seems fairly clear that maintaining
  > an accurate ChangeLog just isn't of interest. Even the bare minimum
  > legally relevant mistakes (missing "tiny change") don't seem to be being
  > corrected.

In concrete terms, what is the problem with these mistakes?

Where is the master record of this information now?
Is it being maintained correctly there?

	       Probably just deleting it from the repo would be more honest.

What exactly are you proposing as the new practice
for handling ChangeLog files?

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Message #66 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Emacs developers <emacs-devel <at> gnu.org>,
 Lars Magne Ingebrigtsen <larsi <at> gnus.org>, 21998 <at> debbugs.gnu.org
Subject: Re: Is it time to drop ChangeLogs?
Date: Mon, 7 Mar 2016 09:29:55 +0000

Hello, John.

On Sun, Mar 06, 2016 at 01:52:04PM -0800, John Wiegley wrote:
>  On Sun, Mar 06 2016 13:07 (-0800), John Wiegley wrote:

> > I have always wanted to drop the ChangeLogs, so if the other
> > developers agree, I'm all for it. Keeping ChangeLog style in the
> > commit entry is not terribly useful either, ....

I find that a strange thing to say.  I frequently search the ChangeLog
for the name of a function, to find out when it was last changed.  I
think the relatively rigid format of the ChangeLog/git commit messages
very helpful.

> > ...., since the diff output of log -p lets you know which function
> > or variable is being modified. I've never missed not having that
> > ChangeLog data in other projects, of any size. But that's up to the
> > other developers and what makes their lives easier.

The ChangeLog is easy to use.  git is difficult to use (more precisely,
is difficult to find out how to use).  I've no idea what git log -p
does, for example (though I'll be looking it up after I've posted this
post :-).  If we drop the ChangeLog we're cutting off its contents from
those for whom discovering the appropriate git commands is too much
work.

> I'd like to open this up to discussion on emacs-devel, so that we hear from
> our other developers. What do you all think about ChangeLogs, and their value
> to you in your work on Emacs?

The ChangeLog is useful, enabling things to be done that can't be done
without it.  If I want to see whether some change was made in Emacs
23.2, for example, I can either inspect 23.2's ChangeLog or spend
several hours working out how to get the information out of git.  No
contest.

The ChangeLog is distributed with the release, enabling our users to
access its information.  They typically don't have and/or don't know how
to use git repositories.

I'm decidedly in favour of keeping the ChangeLog.  But surely an
important consideration is whether the person/people who put in the work
to generate it are prepared to carry on doing this.

> -- 
> John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
> http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #69 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 21998 <at> debbugs.gnu.org, rgm <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Mon, 07 Mar 2016 18:02:00 +0200

> From: Richard Stallman <rms <at> gnu.org>
> Date: Mon, 07 Mar 2016 01:51:17 -0500
> Cc: 21998 <at> debbugs.gnu.org
> 
> > At this point, I give up, since it seems fairly clear that maintaining
>   > an accurate ChangeLog just isn't of interest. Even the bare minimum
>   > legally relevant mistakes (missing "tiny change") don't seem to be being
>   > corrected.
> 
> In concrete terms, what is the problem with these mistakes?

The mistakes are not being corrected.  Experience shows that
correcting them is enough of an annoyance to discourage people.

> Where is the master record of this information now?

In the Git commit messages.

> Is it being maintained correctly there?

When a mistake is made there, it cannot be corrected, because Git
commit log is immutable.  Corrections must be made manually to a
ChangeLog file produced from the Git log by a script.  That proved not
to work well, see above.  It also proved to be a non-trivial problem
when merging changes from the release branch to master -- for this
latter issue we still don't have any idea for how to solve it reliably
and without requiring a lot of manual labor.

>                Probably just deleting it from the repo would be more honest.
> 
> What exactly are you proposing as the new practice
> for handling ChangeLog files?

There are 3 possibilities:

  . Keep the current system, where ChangeLog is produced from Git log
    and mistakes made in Git log should be corrected manually after
    producing ChangeLog

  . Give up on having ChangeLog files, either produced from Git log or
    maintained in the repository -- meaning a tarball will not include
    any ChangeLog at all

  . Go back to previous practice where we maintained ChangeLog files
    in the repository, and Git log messages were just copies of the
    ChangeLog entries

Message #72 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 21998 <at> debbugs.gnu.org, emacs-devel <at> gnu.org
Subject: Re: Is it time to drop ChangeLogs? (Was: bug#21998: Run 'make
 change-history' on release branch)
Date: Mon, 07 Mar 2016 18:26:49 +0200

> From: Paul Eggert <eggert <at> cs.ucla.edu>
> Date: Sun, 6 Mar 2016 14:34:12 -0800
> Cc: 21998 <at> debbugs.gnu.org
> 
> John Wiegley wrote:
> > What do you all think about ChangeLogs, and their value
> > to you in your work on Emacs?
> 
> I regularly do the equivalent of:
> 
> grep PATTERN $(git ls-files | grep -v ChangeLog)
> 
> That is, in searches I typically ignore ChangeLog* files because of their 
> less-useful chatter.

It is a truism that when you know ChangeLog files don't included the
information you are after, you'd like to exclude them.  Likewise, when
I'm looking for information that can only be found in ChangeLog files,
I will filter out everything else as "less-useful chatter".

> Even if we remove ChangeLogs, we should still have guidelines for commit message 
> format

We won't be able to enforce that rule for long.  It's a slippery
slope.  Very slippery.

Message #75 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: John Wiegley <jwiegley <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Mon, 07 Mar 2016 08:35:16 -0800

>>>>> Eli Zaretskii <eliz <at> gnu.org> writes:

>   . Keep the current system, where ChangeLog is produced from Git log
>     and mistakes made in Git log should be corrected manually after
>     producing ChangeLog

If you really do want to keep ChangeLogs around, I'd prefer this over the
third option.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Message #78 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "John Wiegley" <johnw <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Mon, 07 Mar 2016 19:00:37 +0200

> From: John Wiegley <jwiegley <at> gmail.com>
> Cc: rms <at> gnu.org,  21998 <at> debbugs.gnu.org
> Date: Mon, 07 Mar 2016 08:35:16 -0800
> 
> >>>>> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >   . Keep the current system, where ChangeLog is produced from Git log
> >     and mistakes made in Git log should be corrected manually after
> >     producing ChangeLog
> 
> If you really do want to keep ChangeLogs around, I'd prefer this over the
> third option.

That's the system we tried for the past year, and it clearly failed.
Why should we continue to invest good money after bad money?

Is it really that hard to copy/paste an entry from the ChangeLog to
Git log, or the other way around?

Message #81 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: John Wiegley <jwiegley <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Mon, 07 Mar 2016 09:51:58 -0800

>>>>> Eli Zaretskii <eliz <at> gnu.org> writes:

> Is it really that hard to copy/paste an entry from the ChangeLog to Git log,
> or the other way around?

I find it annoying and needlessly cumbersome. But you're doing far more work
than I am, Eli. If this will make your life better, it's a change I can live
with.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Message #84 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, John Wiegley <johnw <at> gnu.org>
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Tue, 08 Mar 2016 02:32:12 -0500

Eli Zaretskii wrote:

> I think if we care at all about having ChangeLog in the releases, we
> should simply reinstate the file and maintain it in the repository.

FWIW, that's not what I was hoping would come from this, and I think
that would be a retrograde step.

> if we don't do that, let's decide there will be no ChangeLog files in
> the release tarballs at all, and stop worrying about these issues.

It's an option; however, there are two issues, which aren't directly
related:

a) an undetermined number of people may be interested in following the
history of Emacs changes without the VCS. Eg, those looking at release
tarfiles.

b) if you care about the quality of your history, you need a way to
correct commit logs, which are (effectively) immutable in git. IMO Emacs
should care about this, if only for legal reasons (eg you get the author
wrong while committing, or forget "tiny change").

I care about b), but not really about a).
Or maybe b) is irrelevant too, I don't know.


Other options:

1) Fix the merging problem. Eg the idea of using differently named
ChangeLog.2/.3 files for emacs-25 and master was mentioned. This is a
mess for people in a) trying to follow the Clog in time order.

2) Go back to only allowing versioned ChangeLog.2 on master branch. This
is least-effort, and removes the merging problem. a) doesn't benefit
from corrections, but at least the legal corrections can be made in
master.

For 1) and 2), experience shows that few people will bother to make
corrections.

3) Stop keeping a versioned ChangeLog.2 in the repo, include a
generated, unfixed ChangeLog in release tarfiles. This addresses a) at
some level but ignores b).

4) Develop a better method for correcting commit log errors. Eg, a file
that lists problematic git hashes and the corrected log message. This
could be similar to git notes, but could just be a text file. You'd need
to develop a little bit of infrastructure to help people use the system.
Recent experience suggests few people would use it. It would not have
the merging problem that the current system does. It would address b),
and a) if you used it while generating the ChangeLog.


PS For the record, to explain the actual merging issue as I see it:

Suppose emacs-25 and master are synced at revision aaa and ChangeLog.2
is up-to-date. emacs-25 advances to rev xxx, and independently master to
rev xxx'. emacs-25 gets ChangeLog.2 updated, and merged to master. Now
the footer of master ChangeLog.2 reports that it is up-to-date to rev
xxx. What does this mean for the changes on master between aaa and xxx'?
Because xxx on master is "after" xxx', I suspect it means they end up
missing from ChangeLog.2 forever, which is bad. But maybe there's no
such issue, or it is fixable with some git trivia. I don't know. That's
why I made this bug report. AFAICS, the adopted "solution" was simply to
ignore the issue, which means master/ChangeLog.2 is (probably) messed up
at the moment.

Message #87 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, johnw <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Tue, 08 Mar 2016 18:08:15 +0200

> From: Glenn Morris <rgm <at> gnu.org>
> Cc: John Wiegley <johnw <at> gnu.org>,  21998 <at> debbugs.gnu.org
> Date: Tue, 08 Mar 2016 02:32:12 -0500
> 
> > I think if we care at all about having ChangeLog in the releases, we
> > should simply reinstate the file and maintain it in the repository.
> 
> FWIW, that's not what I was hoping would come from this, and I think
> that would be a retrograde step.

Can you tell why?  It solves all the problems you mention in your
mail, at negligible costs.  So it seems to be a clear winner.

> For 1) and 2), experience shows that few people will bother to make
> corrections.

Is it an important drawback that few people bother to make
corrections?  If it is, then any solution that involves such
corrections is not what we want.

Also, is the situation with corrections worse or better than what it
was when we maintained ChangeLog files in the repository?

> PS For the record, to explain the actual merging issue as I see it:
> 
> Suppose emacs-25 and master are synced at revision aaa and ChangeLog.2
> is up-to-date. emacs-25 advances to rev xxx, and independently master to
> rev xxx'. emacs-25 gets ChangeLog.2 updated, and merged to master. Now
> the footer of master ChangeLog.2 reports that it is up-to-date to rev
> xxx. What does this mean for the changes on master between aaa and xxx'?
> Because xxx on master is "after" xxx', I suspect it means they end up
> missing from ChangeLog.2 forever, which is bad.

No, they don't end up missing.  They will in general be in the "wrong"
order, time-wise, though.  But what is the "right" order for this
situation, where changes are made in parallel on several branches?  Do
we want them interwoven, in strict order of their commit times?  Or do
we want all the entries of a merge from the branch be kept together
with the time stamp of the merge?  If we want to continue keeping a
single generated ChangeLog file on master and on the branch, we need
to decide what is the desired result.

> But maybe there's no such issue, or it is fixable with some git
> trivia.

The only "git trivia" that's possible is a custom merge driver (which
AFAIK doesn't exist).  Git itself is not aware of the special meaning
of the time stamps in ChangeLog entries.

We could also have some Lisp rearranging the entries in whatever order
we decide we want it, after git-merge-changelog puts them in the order
it thinks is right.

> I don't know. That's why I made this bug report. AFAICS, the adopted
> "solution" was simply to ignore the issue, which means
> master/ChangeLog.2 is (probably) messed up at the moment.

It is not messed, but it isn't in chronological order, either.  And it
looks like no one ran "make change-history" on master for several
moons, so problems might become worse when they do.

Message #90 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, rgm <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Tue, 08 Mar 2016 13:23:20 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > In concrete terms, what is the problem with these mistakes?

  > The mistakes are not being corrected.

If some people don't correct some mistakes, that is unfortunate,
but the existence of the file ChangeLog does no harm in that case.
It merely provides an opportunity that was missed.
The file imposes no extra work when people leave mistakes uncorrected.

When some mistakes do get corrected, then the file does good.

Moreover someone else who notices the mistake could correct it later.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Message #93 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 21998 <at> debbugs.gnu.org, rgm <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Tue, 08 Mar 2016 20:30:12 +0200

> From: Richard Stallman <rms <at> gnu.org>
> CC: rgm <at> gnu.org, 21998 <at> debbugs.gnu.org
> Date: Tue, 08 Mar 2016 13:23:20 -0500
> 
>   > > In concrete terms, what is the problem with these mistakes?
> 
>   > The mistakes are not being corrected.
> 
> If some people don't correct some mistakes, that is unfortunate,
> but the existence of the file ChangeLog does no harm in that case.
> It merely provides an opportunity that was missed.
> The file imposes no extra work when people leave mistakes uncorrected.
> 
> When some mistakes do get corrected, then the file does good.
> 
> Moreover someone else who notices the mistake could correct it later.

I agree, but you seem to assume that ChangeLog files are kept in the
repository.  If they were, there wouldn't be a problem.  They aren't;
they are generated from Git log.  And mistakes in Git log cannot be
fixed.

Message #96 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, rgm <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Wed, 09 Mar 2016 11:38:24 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I agree, but you seem to assume that ChangeLog files are kept in the
  > repository.  If they were, there wouldn't be a problem.  They aren't;
  > they are generated from Git log.

I am trying to understand the situation from what I read in some of
these messages.  If the ChangeLog files are only generated from the
Git log mssages, which cannot be corrected, then how does fixing ChangeLog
entries work?

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Message #101 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 21998 <at> debbugs.gnu.org, rgm <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Wed, 09 Mar 2016 18:51:05 +0200

> From: Richard Stallman <rms <at> gnu.org>
> CC: rgm <at> gnu.org, 21998 <at> debbugs.gnu.org
> Date: Wed, 09 Mar 2016 11:38:24 -0500
> 
> I am trying to understand the situation from what I read in some of
> these messages.  If the ChangeLog files are only generated from the
> Git log mssages, which cannot be corrected, then how does fixing ChangeLog
> entries work?

We fix the generated ChangeLog.  The person who makes a mistake is
supposed to invoke "make change-history", which updates the file
ChangeLog.2 with the log messages of the recent commits (by running
Git with a suitably computed command line), and then edit the updated
file and commit the result.  "make change-history" incrementally
updates ChangeLog.2, so the next time it is invoked, only the later
commits will be added to the file.

This worked, more or less, as long as we only developed on master
(except that not everyone who made mistakes bothered to correct them).
But as soon as we started to work on both master and the release
branch, this broke down because merges from the release branch to
master don't live well with the manual corrections.  This was never
fixed because there appears to be no motivation for fixing it.

Message #108 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21998 <at> debbugs.gnu.org, rgm <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Thu, 10 Mar 2016 16:23:49 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > But as soon as we started to work on both master and the release
  > branch, this broke down because merges from the release branch to
  > master don't live well with the manual corrections.  This was never
  > fixed because there appears to be no motivation for fixing it.

Maybe this discussion gives people the motivation to fix it.
Is there a clear path for fixing it?


-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Message #111 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 21998 <at> debbugs.gnu.org, rgm <at> gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Fri, 11 Mar 2016 10:48:43 +0200

> From: Richard Stallman <rms <at> gnu.org>
> CC: rgm <at> gnu.org, 21998 <at> debbugs.gnu.org
> Date: Thu, 10 Mar 2016 16:23:49 -0500
> 
>   > But as soon as we started to work on both master and the release
>   > branch, this broke down because merges from the release branch to
>   > master don't live well with the manual corrections.  This was never
>   > fixed because there appears to be no motivation for fixing it.
> 
> Maybe this discussion gives people the motivation to fix it.

I hope so.

> Is there a clear path for fixing it?

Not yet, AFAICT.

Message #114 received at 21998 <at> debbugs.gnu.org (full text, mbox):

From: Nicolas Petton <nicolas <at> petton.fr>
To: Glenn Morris <rgm <at> gnu.org>, 21998 <at> debbugs.gnu.org
Subject: Re: bug#21998: Run 'make change-history' on release branch
Date: Fri, 11 Mar 2016 11:05:00 +0100

[Message part 1 (text/plain, inline)]

Glenn Morris <rgm <at> gnu.org> writes:

> At this point, I give up, since it seems fairly clear that maintaining
> an accurate ChangeLog just isn't of interest. Even the bare minimum
> legally relevant mistakes (missing "tiny change") don't seem to be being
> corrected.

Just catching up with emails, so I might have missed your point, but for
each pretest, I try to fix the ChangeLog, or are you talking about
something else?

Nico

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.