ChangeLogs in the elpa branch

ChangeLogs in the elpa branch

[Michael Albinus]

Hi,

| revno: 131
| committer: Stefan Monnier <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.

Re: ChangeLogs in the elpa branch

[Julien Danjou]

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

On Mon, Sep 26 2011, Michael Albinus wrote:

> | revno: 131
> | committer: Stefan Monnier <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.

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

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: ChangeLogs in the elpa branch

[Lars Magne Ingebrigtsen]

Julien Danjou <julien@danjou.info> writes:

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

Re: ChangeLogs in the elpa branch

[Michael Albinus]

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

> Julien Danjou <julien@danjou.info> writes:
>
>> 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.

> Lars, bikesheddin'

Best regards, Michael.

Re: ChangeLogs in the elpa branch

[Ted Zlatanov]

On Mon, 26 Sep 2011 12:35:30 +0200 Michael Albinus <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

Re: ChangeLogs in the elpa branch

[Stefan Monnier]

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

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

Re: ChangeLogs in the elpa branch

[Ted Zlatanov]

On Mon, 26 Sep 2011 11:52:24 -0400 Stefan Monnier <monnier@IRO.UMontreal.CA> wrote: 

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

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

Re: ChangeLogs in the elpa branch

[Richard Stallman]

    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/

Re: ChangeLogs in the elpa branch

[Dave Abrahams]

on Mon Sep 26 2011, Julien Danjou <julien-AT-danjou.info> wrote:

> On Mon, Sep 26 2011, Michael Albinus wrote:
>
>> | revno: 131
>> | committer: Stefan Monnier <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.
>
> 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

Re: ChangeLogs in the elpa branch

[Stefan Monnier]

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

> 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

Re: ChangeLogs in the elpa branch

[Michael Albinus]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

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

>         Stefan

Best regards, Michael.

Re: ChangeLogs in the elpa branch

[Glenn Morris]

Stefan Monnier wrote:

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

Re: ChangeLogs in the elpa branch

[Lars Magne Ingebrigtsen]

Glenn Morris <rgm@gnu.org> writes:

> Reasons I can see why people want to do this:
>
> 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/

Re: ChangeLogs in the elpa branch

[Andreas Schwab]

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

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

Re: ChangeLogs in the elpa branch

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Mon, 26 Sep 2011 12:26:53 -0400
> Cc: Michael Albinus <michael.albinus@gmx.de>, emacs-devel@gnu.org
> 
> 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.

Re: ChangeLogs in the elpa branch

[Stefan Monnier]

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

That doesn't seem like an objection but more like a reason why you're
willing to live with the duplication.

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

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

> 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

Re: ChangeLogs in the elpa branch

[Michael Albinus]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

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

>         Stefan

Best regards, Michael.

Re: ChangeLogs in the elpa branch

[Lars Magne Ingebrigtsen]

Michael Albinus <michael.albinus@gmx.de> writes:

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

Re: ChangeLogs in the elpa branch

[Michael Albinus]

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

> In the check-in message, say
>
> Author: Stefan Monnier <monnier@IRO.UMontreal.CA>
>
> 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.

Re: ChangeLogs in the elpa branch

[Bastien]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> 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

Re: ChangeLogs in the elpa branch

[Andreas Schwab]

Bastien <bzg@altern.org> writes:

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

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

Re: ChangeLogs in the elpa branch

[Bastien]

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

> 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

Re: ChangeLogs in the elpa branch

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Date: Tue, 27 Sep 2011 10:57:22 +0200
> Cc: Michael Albinus <michael.albinus@gmx.de>,
> 	Stefan Monnier <monnier@IRO.UMontreal.CA>, emacs-devel@gnu.org
> 
> > 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.

Re: ChangeLogs in the elpa branch

[Stefan Monnier]

> 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

Re: ChangeLogs in the elpa branch

[Glenn Morris]

Stefan Monnier wrote:

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

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

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

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

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

Re: ChangeLogs in the elpa branch

[Juanma Barranquero]

On Tue, Sep 27, 2011 at 09:10, Glenn Morris <rgm@gnu.org> wrote:

> Stefan Monnier wrote:

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

Re: ChangeLogs in the elpa branch

[joakim]

Juanma Barranquero <lekktu@gmail.com> writes:

> On Tue, Sep 27, 2011 at 09:10, Glenn Morris <rgm@gnu.org> wrote:
>
>> Stefan Monnier wrote:
>
>>> 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. 

>
>     Juanma
>

-- 
Joakim Verona

Re: ChangeLogs in the elpa branch

[Stephen J. Turnbull]

Juanma Barranquero writes:
 > On Tue, Sep 27, 2011 at 09:10, Glenn Morris <rgm@gnu.org> wrote:

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

Re: ChangeLogs in the elpa branch

[Stefan Monnier]

> 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

Re: ChangeLogs in the elpa branch

[Juanma Barranquero]

> Reasons I object to getting rid of ChangeLogs:
[...]
> 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

Re: ChangeLogs in the elpa branch

[Thien-Thi Nguyen]

() Glenn Morris <rgm@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.