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
