Re: Generating the ChangeLog files from the commit messages

[David Engster]

Eli Zaretskii writes:
>> From: David Engster <address@hidden>
>> Date: Wed, 19 Nov 2014 23:51:11 +0100
>> Cc: Bastien <address@hidden>, address@hidden
>> 
>> >     <changelog-style details>
>> 
>> That's precisely what I'd drop. It's just a verbose diff.
>
> No, it's a summary of diffs.  As such, it many times presents a
> bird-eye view that is hard to grasp by looking at the diffs.

Well, this is also because our commits are often too large.

> It is also much shorter, so if you want to decide whether a particular
> changeset is of interest, you have much less text to read.

A good commit title is often enough to raise interest. This entails a
location prefix to mark which area of the code is affected, so that the
person who maintains that area can immediately see it, filter by it,
etc.

As I've said: the Changelog is not completely useless. But most of its
information is automatically generated from the diff. Just go through
the log and in your mind strip all the generated stuff (like filenames
and affected symbols), and see what information provided by the *author*
actually remains - it's usually very little, and often stating the
obvious, instead of saying *why* something was done. This is not
primarily the author's fault: since you have to break down your changes
function by function, you often cannot really describe the broader
picture these changes accomplish, so you just do the mandatory
book-keeping.

This makes our commit logs mostly useless for actually understanding how
code evolved. You may feel differently, but keep in mind there are not
many people who know the Emacs code base as well as you do. When I dig
into files which are unfamiliar to me (like recently into compile.el),
and hit 'l' on an annotated line, it's usually a pretty frustrating
experience.

I encourage anyone to browse through the commit logs from projects like
Git or Linux. If people then still tell me that our style is superior,
so be it.

-David