Re: Using VC for change descriptions

[Mike Gerwitz]

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