Re: Is it time to drop ChangeLogs?

[Eli Zaretskii <eliz@gnu.org>]

> From: Óscar Fuentes <ofv@wanadoo.es>
> Date: Fri, 08 Jul 2016 17:07:05 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> That information is already available from the VCS, on steroids. You can
> >> query the history of a function, ask which changes introduced or deleted
> >> a call to certain function...
> >
> > Yes, but doing so on a large file that saw many changes is relatively
> > slow.  Scanning a ChangeLog is much faster, so I always use it as the
> > first approximation, and only go to the likes of "git log -L" and
> > "git annotate" if I have to.
> 
> You rarely are interested on the whole file. vc-region-history makes
> wonders when you care about part of the file (a function, for instance.)

That's "git log -L" that I mentioned.  It's startup time is not
negligible.

>   Remove just input mark
> 
>   * lisp/ibuffer.el (ibuffer-unmark-all): When MARK is not ?\r remove
>   just MARK.
> 
> no hint about why it was necessary.

Did you look at the comments?

> About 3 commits below:
> 
>   Disable App Nap (bug#22993)
> 
>   * nextstep/templates/Info.plist.in: Insert AppNap disable code.
> 
> No hint about why it was necessary, except for the bug#

Which is more than enough.

> Besides, having to jump to the bug is a nuisance
> (some people mentioned that having the ChangeLogs readily available on
> the tarballs is an advantage.) It is not necessary to duplicate the
> whole discussion, but briefly mentioning what the problem was and why it
> was decided to solve it this way would be helpful.

This request is unreasonable.  If nothing else, it will make the bar
for contributing higher, not lower.  The information is recorded in
the bug discussion, and there's no need to reproduce it in the log
message.

> Yet a two or three commits below:
> 
>  Fix an error in Tramp for rsync
> 
>  * lisp/net/tramp-sh.el (tramp-do-copy-or-rename-file-out-of-band):
>  Make it work for "rsync".
>  (tramp-make-copy-program-file-name): Apply `directory-file-name'.
> 
> There is no even bug # here.
> 
> And so on.

I see no problems in these log messages.

> > This conflates several distinct places where this information is held,
> > making it sound that all of it should be in the commit log message.
> > That is false, or at least I couldn't disagree more.  First and
> > foremost, the code should speak for itself, so the most detailed
> > explanations should be in comments there.  We didn't just replace the
> > code by the VCS!
> 
> I never said otherwise. I talked about the "right place" for putting
> information on the next paragraph.

Which we already do.  Improvements are always possible, but by and
large our commit log messages are good.

> > Second, many times the information is in a prolonged discussion, in
> > particular on the bug tracker.  By including a reference to the bug
> > report, we implicitly include all of it in the log message.
> 
> It is not helpful to point the reader to a long discussion if the
> rationale for the change can be summarized (mentioning the bug# is a
> good thing, of course.)

There's no other practical way.  It's unreasonable to ask people to
summarize such discussions in a log message.

> > As for "the diff is readily available, there is no need to name each
> > function touched by the change" part, it is inaccurate: the VCS diff
> > tool doesn't always show the name of the function or macro that is
> > being changed.  Moreover, if several functions/macros are changed in a
> > single hunk, at most one of them will be named in the hunk header, the
> > rest need to be deduced by painfully reading the diffs.  I don't think
> > we can say in good faith that this information is as readily available
> > as in ChangeLog-style log messages.
> 
> Possibly not as readily available but, to be fair, how many times you
> are interested on the functions affected on a trivial way by a change?

Always.  For me, digging into an issue usually begins with a function
I know is misbehaving.  The very next question is: when was it last
changed, how, and why.

> Usually you are interested on either how a given function evolved or on
> how the introduction of a fix/feature affected the code base.

No, that's rarely the case.  It only happens when I find a very old
bug, and am curious who and when introduced it.

> > I find comments to be a better place for these situations as well (and
> > made many comments of this kind over the years myself).  The most
> > important reason is discoverability: when one reads code, they usually
> > won't look at the Git history of the code they go through, but
> > comments they will see.  Scattered changes are not a problem, you can
> > always say "see such-and-such function".
> 
> I see this on a different way: commit messages add to, and complement,
> code comments.

They shouldn't.