Re: Is it time to drop ChangeLogs?

[Óscar Fuentes]

Richard Stallman <address@hidden> writes:

>   > GNU ChangeLogs, as used in practice, are so lame and thin on content
>   > that they certainly can't be taken seriously as a method of documenting
>   > changes.
>
> They are good for their purpose, which is to summarize which functions
> or objects were changed, when, and by whom.  That's useful when
> you want to see which changes to look at to figure out when a bug
> got introduced.

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

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 haven't said what "content" you think is missing, so it is hard
> for me to respond further than that.

Just a few minutes ago I responded to another developer that asked on a
private email about details about what a "proper commit message" means
to me. Here is my response:

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.

> However, if you're talking about
> explanations of the code, those are supposed to go in comments in the
> code.

Absolutely agreed. That's about putting each piece where it belongs.
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.

>   > GNU ChangeLogs always looked to me as cargo cult and an excuse for not
>   > writing proper commit messages.
>
> There was no such thing as a commit message in 1985.

Exactly. I'm pretty sure that if you had a good VCS at that time
ChangeLogs would never came into being.