Discussion:
ChangeLogs in the elpa branch
(too old to reply)
Michael Albinus
2011-09-26 07:09:41 UTC
Permalink
Hi,

| revno: 131
| committer: Stefan Monnier <***@iro.umontreal.ca>
| branch nick: elpa
| timestamp: Sun 2011-09-25 21:33:06 -0400
| message:
| Remove ChangeLogs; use "bzr log" instead

Is this necessary? I find the ChangeLogs helpful, especially for the
debbugs package which is still actively developped.

And for packages distributed by the package manager, "bzr log" is not
applicable.

IIRC, a similar discussion was about ChangeLogs in trunk, and the
decision (compromise?) was to keep them.

Best regards, Michael.
Julien Danjou
2011-09-26 09:56:17 UTC
Permalink
Post by Michael Albinus
| revno: 131
| branch nick: elpa
| timestamp: Sun 2011-09-25 21:33:06 -0400
| Remove ChangeLogs; use "bzr log" instead
Is this necessary? I find the ChangeLogs helpful, especially for the
debbugs package which is still actively developped.
FTR, I don't know if it's necessary, but Changelogs are just duplication
of information, so I'm on Stefan side on this one. :)
--
Julien Danjou
Lars Magne Ingebrigtsen
2011-09-26 10:23:53 UTC
Permalink
Post by Julien Danjou
FTR, I don't know if it's necessary, but Changelogs are just duplication
of information, so I'm on Stefan side on this one. :)
They're not just duplication of information, but I think the utility of
them probably no longer justifies the work of maintaining them.

Lars, bikesheddin'
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog http://lars.ingebrigtsen.no/
Michael Albinus
2011-09-26 10:35:30 UTC
Permalink
Post by Lars Magne Ingebrigtsen
Post by Julien Danjou
FTR, I don't know if it's necessary, but Changelogs are just duplication
of information, so I'm on Stefan side on this one. :)
They're not just duplication of information, but I think the utility of
them probably no longer justifies the work of maintaining them.
If I'm the only one who likes them I won't insist in maintaining them
any longer. But I find it useful to check the history of packages, even
if there is no bzr access. As for the majority of the Emacs users.
Post by Lars Magne Ingebrigtsen
Lars, bikesheddin'
Best regards, Michael.
Ted Zlatanov
2011-09-26 14:23:54 UTC
Permalink
On Mon, 26 Sep 2011 12:35:30 +0200 Michael Albinus <***@gmx.de> wrote:

MA> If I'm the only one who likes them I won't insist in maintaining them
MA> any longer. But I find it useful to check the history of packages, even
MA> if there is no bzr access. As for the majority of the Emacs users.

I find them useful and "bzr log" doesn't always work as well as plain
text comments. For instance it's much harder to go back and edit a
published VCS log than a ChangeLog file.

Perhaps the ELPA .el files should have a ChangeLog section in the usual
format, which can then be collected into a compendium for the whole
package by package.el. `C-x 4 a' would need a parallel command to edit
the built-in ChangeLog.

Ted
Stefan Monnier
2011-09-26 15:52:24 UTC
Permalink
Post by Ted Zlatanov
I find them useful and "bzr log" doesn't always work as well as plain
text comments. For instance it's much harder to go back and edit a
published VCS log than a ChangeLog file.
They each have their advantage and inconvenients, but they're not
sufficient to justify keeping both. So for the "edit the VCS log",
you'll want to file a feature request with the Bazaar guys (or rather,
add your voice to the existing bug number).
Post by Ted Zlatanov
`C-x 4 a' would need a parallel command to edit the built-in ChangeLog.
Yes, C-x 4 a will need work so it's useful even without a ChangeLog.
Maybe a simple way to do that is to have *VC-Log* save itself into
a .changelog file which gets auto-removed upon commit, and then have C-x
4 use/create such a .changelog file (at the root of the checkout) if there's
no ChangeLog. This has been discussed already in the past, but there
hasn't been any progress, so I hope this change to `elpa' will be
a motivating factor.


Stefan
Ted Zlatanov
2011-09-26 16:49:33 UTC
Permalink
Post by Ted Zlatanov
I find them useful and "bzr log" doesn't always work as well as plain
text comments. For instance it's much harder to go back and edit a
published VCS log than a ChangeLog file.
SM> They each have their advantage and inconvenients, but they're not
SM> sufficient to justify keeping both. So for the "edit the VCS log",
SM> you'll want to file a feature request with the Bazaar guys (or rather,
SM> add your voice to the existing bug number).

I'd rather edit a file and append commit messages to the VCS log :)
That's why I think the ChangeLog should be in the file.
Post by Ted Zlatanov
`C-x 4 a' would need a parallel command to edit the built-in ChangeLog.
SM> Yes, C-x 4 a will need work so it's useful even without a ChangeLog.
SM> Maybe a simple way to do that is to have *VC-Log* save itself into
SM> a .changelog file which gets auto-removed upon commit, and then have C-x
SM> 4 use/create such a .changelog file (at the root of the checkout) if there's
SM> no ChangeLog. This has been discussed already in the past, but there
SM> hasn't been any progress, so I hope this change to `elpa' will be
SM> a motivating factor.

I see what you mean. So you really want to move all commit messages to
the VCS log, not just remove ChangeLog files per se. OK, I think if
it's pushed in a solid way as you've done with ELPA it's a great idea.
The people that need editable ChangeLogs will use inline commentaries or
whatever. Having a single source of commit messages will be a good
thing and I take back any objections I may have had :)

Ted
Richard Stallman
2011-09-26 21:13:14 UTC
Permalink
I find them useful and "bzr log" doesn't always work as well as plain
text comments. For instance it's much harder to go back and edit a
published VCS log than a ChangeLog file.

When I have to fix a change, shortly after installing it, I edit its
ChangeLog entry rather than making a separate one.
--
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
Use free telephony http://directory.fsf.org/category/tel/
Dave Abrahams
2011-09-26 11:46:31 UTC
Permalink
Post by Julien Danjou
Post by Michael Albinus
| revno: 131
| branch nick: elpa
| timestamp: Sun 2011-09-25 21:33:06 -0400
| Remove ChangeLogs; use "bzr log" instead
Is this necessary? I find the ChangeLogs helpful, especially for the
debbugs package which is still actively developped.
FTR, I don't know if it's necessary, but Changelogs are just duplication
of information, so I'm on Stefan side on this one. :)
ChangeLogs that are just duplication of information are useless, but not
all ChangeLogs are like that. Some maintainers use ChangeLogs to
highlight out the changes that they think are relevant to their users.
--
Dave Abrahams
BoostPro Computing
http://www.boostpro.com
Stefan Monnier
2011-09-26 13:03:54 UTC
Permalink
Post by Michael Albinus
Is this necessary? I find the ChangeLogs helpful, especially for the
debbugs package which is still actively developped.
IIRC, a similar discussion was about ChangeLogs in trunk, and the
decision (compromise?) was to keep them.
The decision for Emacs ChangeLogs was "to keep them for now".
So my decision for GNU ELPA is to "not introduce them" instead, and use
it as a testbed and motivation to make "bzr log" work as well as
ChangeLogs, so that we ultimately will be able to get rid of Emacs's
ChangeLogs as well.
Post by Michael Albinus
And for packages distributed by the package manager, "bzr log" is not
applicable.
That's one of the things we need to fix, yes: when building the
packages, we should extract that "bzr log" and place it into
a ChangeLog file.


Stefan
Michael Albinus
2011-09-26 13:49:36 UTC
Permalink
Post by Stefan Monnier
Post by Michael Albinus
And for packages distributed by the package manager, "bzr log" is not
applicable.
That's one of the things we need to fix, yes: when building the
packages, we should extract that "bzr log" and place it into
a ChangeLog file.
That would be reasonable. Thanks.
Post by Stefan Monnier
Stefan
Best regards, Michael.
Glenn Morris
2011-09-26 16:26:53 UTC
Permalink
Post by Stefan Monnier
The decision for Emacs ChangeLogs was "to keep them for now".
I'm very much against getting rid of ChangeLogs, but every time the
issue has been mentioned it has been with some kind of "but we won't do
this now", so I never know when to voice my objections. Seems like now
may be too late, and this is not a democracy anyway, but here goes:

Reasons I object to getting rid of ChangeLogs:

1) Using Emacs VC, you only have to write the ChangeLog, then use C-c
C-a to insert it into the commit buffer. So there is no need to "write
the same thing twice".

2) Sometimes I want to put more detail into the commit log, which is
not appropriate for the ChangeLog.

3) ChangeLogs can be edited to correct mistakes, commit logs cannot.

4) I have the impression that having to write ChangeLogs leads to
higher quality entries than just using commit logs would.

Reasons I can see why people want to do this:

1) It makes merging between branches a bit easier.

I don't think this is a compelling reason to change practice.
bzr has a changelog_merge plugin that makes this easier, and I wrote
some notes on how to use it with Emacs. Anyone who feels burdended by
having to merge ChangeLogs between branches should try it out. It seems
like a simple problem, conceptually.

Personally I think the slight extra time involved in maintaining a
ChangeLog is more than justified by the higher quality of said log.
Lars Magne Ingebrigtsen
2011-09-26 16:38:16 UTC
Permalink
Post by Glenn Morris
1) It makes merging between branches a bit easier.
My work flow when fixing small bugs (and most of them are small bugs)
are:

1) fix the bug

2) `C-x 4 a', and write the bug entry

3) `M-x vc-dir RET'

4) Do something depending on what's shown in the vc-dir buffer, like
mark ChangeLog and the file in question, in case I have other changes
pending, which I often have

5) `='

6) `v'

7) `C-c C-a' to pull in the log

8) Remove the bit too much that `C-a C-a' pulled in, since I perhaps
just did another change to the same file.

9) Rewrite the entry to fit a commit; i.e., make a complete first
sentence that shows up as the summary

10) `C-c C-c'

11) Profit!


If we didn't have a ChangeLog, my work flow would be:

1) fix the bug

2) `C-x v ='

3) `C-x v v'

4) Write the entry

5) `C-c C-c'

Won't anybody think of the poor developers' fingers!
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog http://lars.ingebrigtsen.no/
Andreas Schwab
2011-09-26 19:18:15 UTC
Permalink
Post by Lars Magne Ingebrigtsen
4) Do something depending on what's shown in the vc-dir buffer, like
mark ChangeLog and the file in question, in case I have other changes
pending, which I often have
You shouldn't. Commit early, commit often.

Andreas.
--
Andreas Schwab, ***@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5
"And now for something completely different."
Eli Zaretskii
2011-09-26 17:06:27 UTC
Permalink
Date: Mon, 26 Sep 2011 12:26:53 -0400
Personally I think the slight extra time involved in maintaining a
ChangeLog is more than justified by the higher quality of said log.
I agree with everything Glenn wrote, FWIW.
Stefan Monnier
2011-09-26 17:08:16 UTC
Permalink
Post by Glenn Morris
1) Using Emacs VC, you only have to write the ChangeLog, then use C-c
C-a to insert it into the commit buffer. So there is no need to "write
the same thing twice".
That doesn't seem like an objection but more like a reason why you're
willing to live with the duplication.
Post by Glenn Morris
2) Sometimes I want to put more detail into the commit log, which is
not appropriate for the ChangeLog.
Without stating why, I can't assess how serious this is.
Post by Glenn Morris
3) ChangeLogs can be edited to correct mistakes, commit logs cannot.
That's not written in stone. CVS can edit its commit logs, and there's
no reason the same can't be done for other revision control systems.
Better yet: there's no reason we can't do it ourselves in a (potentially
even backend-agnostic) way that will work for C-x v l and for
auto-generation of a ChangeLog file.
Post by Glenn Morris
4) I have the impression that having to write ChangeLogs leads to
higher quality entries than just using commit logs would.
I think this just reflects the better support in change-log-mode, with
highlighting, C-x 4 a and things like that. We indeed need to improve
the commit-log-editor accordingly.


Stefan
Michael Albinus
2011-09-26 21:18:28 UTC
Permalink
Post by Stefan Monnier
Post by Glenn Morris
1) Using Emacs VC, you only have to write the ChangeLog, then use C-c
C-a to insert it into the commit buffer. So there is no need to "write
the same thing twice".
That doesn't seem like an objection but more like a reason why you're
willing to live with the duplication.
Sometimes, I commit for somebody else. I mark it in the ChangeLog.

Without a ChangeLog, I need to add --author to the (bzr) commit. How
is this possible with Emacs' VC?
Post by Stefan Monnier
Stefan
Best regards, Michael.
Lars Magne Ingebrigtsen
2011-09-26 21:27:00 UTC
Permalink
Post by Michael Albinus
Without a ChangeLog, I need to add --author to the (bzr) commit. How
is this possible with Emacs' VC?
In the check-in message, say

Author: Stefan Monnier <***@IRO.UMontreal.CA>

as the first line. (Well, in the header.)
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog http://lars.ingebrigtsen.no/
Michael Albinus
2011-09-27 03:10:17 UTC
Permalink
Post by Lars Magne Ingebrigtsen
In the check-in message, say
as the first line. (Well, in the header.)
Thanks. (I fear, it is more unlikely that I will commit in Stefan's name :-)

Best regards, Michael.
Bastien
2011-09-27 05:22:49 UTC
Permalink
Post by Stefan Monnier
That's not written in stone. CVS can edit its commit logs, and there's
no reason the same can't be done for other revision control systems.
At least for git, you can edit the last commit message with a simple
~$ git commit --amend

But editing the commit logs beyond that goes against a principle that
is somewhat carved in stone: "Don't modify the commit logs history."

I don't know how bzr devs feel about this.
--
Bastien
Andreas Schwab
2011-09-27 08:57:22 UTC
Permalink
Post by Bastien
At least for git, you can edit the last commit message with a simple
~$ git commit --amend
git rebase -i can conveniently do that for older commits as well.
Post by Bastien
But editing the commit logs beyond that goes against a principle that
is somewhat carved in stone: "Don't modify the commit logs history."
The principle is actually: "Don't modify published history." It is
perfectly ok to edit commits locally until you are happy with them
before publishing them.

Andreas.
--
Andreas Schwab, ***@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5
"And now for something completely different."
Bastien
2011-09-27 09:04:58 UTC
Permalink
Post by Andreas Schwab
The principle is actually: "Don't modify published history." It is
perfectly ok to edit commits locally until you are happy with them
before publishing them.
You're perfectly right, thanks for the precision.
--
Bastien
Eli Zaretskii
2011-09-27 09:25:52 UTC
Permalink
Date: Tue, 27 Sep 2011 10:57:22 +0200
Post by Bastien
But editing the commit logs beyond that goes against a principle that
is somewhat carved in stone: "Don't modify the commit logs history."
The principle is actually: "Don't modify published history." It is
perfectly ok to edit commits locally until you are happy with them
before publishing them.
If your bzr branch is not bound, then your log messages will be
invisible anyway after merging to mainline (unless people actually
_want_ to see logs from non-mainline history); what matters is the log
you write when you merge. If your branch _is_ bound, then there are
no local commits. (If you are thinking about "bzr ci --local", then
these again look after pushing as non-mainline commits, so this option
doesn't change the basic facts.)

I suspect that people who care about lack of the ability to edit log
messages are talking about the latter situation. So the "you can edit
non-published history" stance does not help them.
Stefan Monnier
2011-09-27 13:00:15 UTC
Permalink
Post by Bastien
But editing the commit logs beyond that goes against a principle that
is somewhat carved in stone: "Don't modify the commit logs history."
If you go read the Bazaar ticket about this issue, you'll see that the
unchanging nature of the past is not incompatible with "editing past
commit messages". You only need to commit a new additional change that
contains a note "in the future, whenever the user asks for the commit
message of commit nb XXX, please return this new text instead of the one
stored in the immutable history".


Stefan
Glenn Morris
2011-09-27 07:10:42 UTC
Permalink
Post by Stefan Monnier
Post by Glenn Morris
1) Using Emacs VC, you only have to write the ChangeLog, then use C-c
C-a to insert it into the commit buffer. So there is no need to "write
the same thing twice".
That doesn't seem like an objection but more like a reason why you're
willing to live with the duplication.
OK. But much of the motivation to make the change seems to be "there will
be less to type". I'm saying I don't find that compelling.
I find the extra work involved in maintaining a ChangeLog to be worth it.

(Did I miss some other reason why this change is desirable, beyond
"somewhat fewer keypresses", and "slightly easier merging between
branches"?

CVS had both editable logs, and a cvs2log program, so what's changed?
I guess it's that people tend to use more branches now, and find merging
ChangeLogs difficult? As I said, try the changelog_merge plugin for
that. Or don't keep (versioned) ChangeLogs in your personal branches.)
Post by Stefan Monnier
Post by Glenn Morris
2) Sometimes I want to put more detail into the commit log, which is
not appropriate for the ChangeLog.
Without stating why, I can't assess how serious this is.
It tends to be things like adding hrefs to emacs-devel discussions, or
explaining more _why_ a change is needed as opposed to simply stating
what the change was.
Post by Stefan Monnier
Post by Glenn Morris
3) ChangeLogs can be edited to correct mistakes, commit logs cannot.
That's not written in stone. CVS can edit its commit logs, and there's
no reason the same can't be done for other revision control systems.
Shall we wait till bzr gets a good implementation of this feature then?
Post by Stefan Monnier
Better yet: there's no reason we can't do it ourselves in a (potentially
even backend-agnostic) way that will work for C-x v l and for
auto-generation of a ChangeLog file.
This doesn't sound "better" to me.
Post by Stefan Monnier
Post by Glenn Morris
4) I have the impression that having to write ChangeLogs leads to
higher quality entries than just using commit logs would.
I think this just reflects the better support in change-log-mode, with
highlighting, C-x 4 a and things like that.
I disagree, I think people take more care with ChangeLogs.
Juanma Barranquero
2011-09-27 09:05:50 UTC
Permalink
Post by Glenn Morris
Post by Stefan Monnier
I think this just reflects the better support in change-log-mode, with
highlighting, C-x 4 a and things like that.
I disagree, I think people take more care with ChangeLogs.
I'm with Glenn again. And part of the fact is, IMO, the immediacy of
writting the commit logs. I'd bet not many people write them at a
leisurely pace before even starting the commit.

    Juanma
j***@verona.se
2011-09-27 09:45:43 UTC
Permalink
Post by Juanma Barranquero
Post by Glenn Morris
Post by Stefan Monnier
I think this just reflects the better support in change-log-mode, with
highlighting, C-x 4 a and things like that.
I disagree, I think people take more care with ChangeLogs.
I'm with Glenn again. And part of the fact is, IMO, the immediacy of
writting the commit logs. I'd bet not many people write them at a
leisurely pace before even starting the commit.
A ChangeLog is somewhat similar to a Tag. That is, when you are pleased
with something you write a little more detail than you usually do in
commits. So, in bazaar you could presumably work on a branch, committing
as usual. Before you merge to trunk you optionaly tag, then merge. The
Tag will contain the fantastically superior commit message. This could
potentially even be an improvement over the ChangeLog format which
sometimes is a bit terse IMHO.

That said I don't have a strong opinion. I personally don't like the
hassle of the ChangeLogs for small changes. Historically I haven't made
many small changes to Emacs so I don't get hit often. Instead I've made
some larger patches and when merging them handling the ChangeLog is the
least of my worries.

Anyway, compared to many projects I'm involved Emacs is a shining beacon
of light with regards to the lucidity of the commit history so whatever
changes we do we should preserve that aspect.
Post by Juanma Barranquero
    Juanma
--
Joakim Verona
Stephen J. Turnbull
2011-09-27 12:02:04 UTC
Permalink
Post by Juanma Barranquero
Post by Glenn Morris
I disagree, I think people take more care with ChangeLogs.
I'm with Glenn again. And part of the fact is, IMO, the immediacy of
writting the commit logs. I'd bet not many people write them at a
leisurely pace before even starting the commit.
That's because not many people write ChangeLogs at a leisurely pace
before even starting the commit. Anyway, the right time to write log
message (of either type) is before starting to code. ;-)

This particular issue is easy enough to solve, though.

1. Disable the log message prompt in the vc-commit code.
2. Add -F .emacs-vc-commit-log (or whatever the equivalent is in .bzr)
to the commit command (and maybe some sort of "up-to-date" check on
that file).
3. Have "C-x 4 a" look for that file as well as/instead of ChangeLog,
and create it (in preference to ChangeLog) if neither is found.

There are some rough edges there, but once the basic idea is
implemented, you'll never notice you're not writing ChangeLogs any
more.
Stefan Monnier
2011-09-27 13:05:33 UTC
Permalink
Post by Stephen J. Turnbull
1. Disable the log message prompt in the vc-commit code.
2. Add -F .emacs-vc-commit-log (or whatever the equivalent is in .bzr)
to the commit command (and maybe some sort of "up-to-date" check on
that file).
3. Have "C-x 4 a" look for that file as well as/instead of ChangeLog,
and create it (in preference to ChangeLog) if neither is found.
That's pretty much the plan, yes.
We do want to store the comment in a file, so that you can write it little
by little.


Stefan

Juanma Barranquero
2011-09-27 09:00:31 UTC
Permalink
[...]
Post by Glenn Morris
Personally I think the slight extra time involved in maintaining a
ChangeLog is more than justified by the higher quality of said log.
I agree at 100%

    Juanma
Thien-Thi Nguyen
2011-09-27 12:24:49 UTC
Permalink
() Glenn Morris <***@gnu.org>
() Mon, 26 Sep 2011 12:26:53 -0400

4) I have the impression that having to write ChangeLogs leads to
higher quality entries than just using commit logs would.

FWIW, this is the main reason i support maintaining separate ChangeLog files.
Continue reading on narkive:
Loading...