Re: Is it time to drop ChangeLogs?

[Óscar Fuentes]

Eli Zaretskii <address@hidden> 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.)
Using the `annotate' interface has the advantage of bringing in the rest
of VC: one key and you see the patch that introduced the change, another
key and you see the commit message, yet another key and you can annotate
the function as it was before the change, and so on. Tools such as
git-timemachine.el makes the process even more effective.

>> But the real damage ChangeLogs cause is their formulaic, almost mechanic
>> aspect: people write a lot of minutiae instead of writing a commit
>> message intended to help the reader, the same way good code comments are
>> written. It is true that some hackers write good commit messages *and*
>> ChangeLogs, but I'm under the impression that most people just write the
>> changelog and consider that their job is done (after all, current policy
>> for commit messages is to write a summary line and the 
>
> You are invited to look at our recent commit log messages, which are
> in the ChangeLog format, and point out the ones that fit the above
> description.  I don't think you will find a lot of them, but maybe I'm
> mistaken.

Just the second commit on the log output:

  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.

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# (I hope the
reason for the change is documented there, along with its implications;
the bug is still open). 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.

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.

>> In a nutshell, a proper commit message shall contain, either explicitly
>> or implicitly, the what, why, where and how of the change. It must be
>> informative and provide the info that the reader is interested on,
>> without entering on unnecessary detail (the diff is readily available,
>> there is no need to name each function touched by the change). The
>> author must write it with the same mindset he chooses function and
>> variable names, decides when it is a good idea to put a code comment,
>> etc.
>
> 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.

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

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

Usually you are interested on either how a given function evolved or on
how the introduction of a fix/feature affected the code base. For the
first case you have vc-region-history and for the second a combination
of VC features and text search.

>> Some times, however, the code is not the best place to put some
>> explanation (think of an scattered change or why some alternative that,
>> at first, seems more adequate was discarded) and the commit message
>> offers an alternative. The commit message is a good place to direct the
>> reader to the key areas for understanding the change, inform the reader
>> about current status and future steps and any other info that the author
>> thinks is relevant for current and/or future hackers with an interest on
>> the affected area.
>
> 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.