On Tue, Jan 02, 2018 at 21:17:51 +0000, Joseph Myers wrote: > On Tue, 2 Jan 2018, Alfred M. Szmidt wrote: >> A ChangeLog entry is far easier to process by a human, than a large >> diff. For some languages the diffs become really ugly, specially for > > A logical description of the change at an appropriate level for that > change is even easier for a human to process than the ChangeLog entry.
I think logical descriptions are important too. But the high-level description is sometimes different than the description of the actual change that was made.[0][1] > If someone is studying the details of the source code and how it changed > at the level of wanting to know how individual bits of the internals > changed in a given revision, then the diffs are much clearer than the > ChangeLog at showing those details of the change. That's true if you're familiar with the code. But even as the author of my code, it's often easier for me to just read my ChangeLog-style commit to understand my change, and then dive into the diff for further information. I started using ChangeLog entries in my commits at work to aid in the code review process. While the team can certainly read the diff and evaluate it, they're not necessarily familiar with all of the details for that particular task/change. It takes a lot of time to read through a diff, even if it's code that you understand. My time as a code reviewer is limited, so I appreciate any clarity I can be given. Unfortunately I'm the only one writing ChangeLog entries. Sometimes commits are granular enough that the ChangeLog entry is just repeating the summary line. I simply include them for formality in that case. Sometimes diffs just contain too much---maybe the diff displays 30 lines of changes when all I really did was change a couple function arguments and rename a couple variables. But it makes the diff daunting. > ChangeLog format effectively doubles the time required to implement > certain kinds of changes - first you have to make the change (some logical > change involving many repetitive edits to many entities), then repeat the > description for each individual edit in a way that's often more verbose > than the diffs themselves. Any benefit from having it is much less than > the benefit from another change fully implemented and written up in the > time otherwise required to write the ChangeLog entry for the first change. That's an exaggeration. There are occasions where I've had to write excessively long ChangeLog entries because there was no easy way to break it up into separate commits (or doing so required too much effort)[0], but it's rare that I have to sit down and spend tens of minutes doing so. I always use `git add -p` to make sure I commit only what I intended, and during that, I write the ChangeLog. That also obviates unrelated changes---it's easy to lump too much crap into a single commit, which just makes the diff even more difficult to understand (and a ChangeLog more useful). [0]: https://gitlab.com/lovullo/liza/commit/68649dfd9b07f664cd2600d5206d758dac3682c5 The ChangeLog actually allows others on my team to understand why I made certain changes. Certain things don't belong in code comments (history descriptions). [1]: https://gitlab.com/lovullo/tame/commit/2af0daceb320b59d13e312c6c9b65ae04e7a615b Here's a situation that I regret. There's a high-level description, but I created a horridly useless ChangeLog entry. The high-level description describes why the change was necessary and what it does, but it does nothing to describe how I actually did it. -- Mike Gerwitz Free Software Hacker+Activist | GNU Maintainer & Volunteer GPG: D6E9 B930 028A 6C38 F43B 2388 FEF6 3574 5E6F 6D05 https://mikegerwitz.com
signature.asc
Description: PGP signature
