Properties of ChangeLog/Commit Messages

[Joel Sherrill]

Hi

Richard Kenner (old GCC maintainer) listed these in a post and I thought it
was worth passing along:

=====================
In other words, there are three levels (of information in ChangeLog
entries) here:

(1) What the code currently does
(2) How we changed the code from what it did to what it does
(3) Why we made the change

#1 is always in the code and #2 is always in the ChangeLog.  #3
*should* be in the ChangeLog, but isn't always.  However #2 is very
useful information.

This is especially valuable because it gives the intent of the change in
the case where an error was made (say, some part of the change was missed).
It's much harder to figure out intent from even the diff and certainly
impossible from the code itself.
===========================

Richard is right that the commit message/ChangeLog is supposed to
provide insight into the why of the change. Referencing a PR can be
part of that.

--joel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20180705/7f46525b/attachment.html>