Re: Using VC for change descriptions

[John Darrington]

On Tue, Nov 28, 2017 at 01:47:42PM -0500, Richard Stallman wrote:
     [[[ To any NSA and FBI agents reading my email: please consider    ]]]
     [[[ whether defending the US Constitution against all enemies,     ]]]
     [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
     
       > It's important to have commit messages that provide that high-level 
       > overview.  The problem I'm concerned with is that the ChangeLog format 
       > forces descriptions at the level of individual files and named 
entities 
       > therein, and for many changes that's not a high-level overview, it's a 
       > low-level repetition of the diffs in English,
     
     Although it might seem to be a repetition, it actually adds something:
     the names of the entities that were changed.  That is a crucial piece
     of information that isn't in the diff.
     
     Thus, the question of whether ChangeLog files are truly superfluous
     reduces to the question of whether we can regenerate this crucial
     information from the repository.
     
The names of the files which have been changed can most certainly can be 
regenerated from the repository (at least in all VCSs that I have encountered).

The names of the changed functions (if any) cannot be (without help from some
external program).  However, to anyone who is familiar with the language of
the files concerned, this information is obvious from the diff.  

Thus, if it is desired that the change log contain the names of changed 
functions, then the developer must put this into the commit message when she 
commits.

However, I think I have said before, IMO that information is of little use.
After all, if I am really interested to know which function a commit affected,
I can just look at the diff and see.   But what I more often want to know
is *why* a particular change was made.

I have had this conversation with a few people in the past, and some have 
suggested "put the reason in a comment in the source code".  But this
suggestion is rather naive.  A single change could affect many files and
dozens of functions (for example it might change a function parameter from
pass by value to pass by pointer - which would have a knock-on effect for
all contained functions)  It would be simply rediculous to put a comment
next to every use of the variable saying: 
  /* This used to be a char - now it is a pointer to char, because ... */

So I agree with Joseph, that ChangeLog messages / commit messages should give
a high level overview (with rationale) rather than the details of what has
changed, which can be gleaned from the repository anyway.

J'

-- 
Avoid eavesdropping.  Send strong encrypted email.
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.

signature.asc
Description: Digital signature