Re: Using VC for change descriptions

[Mike Gerwitz]

On Tue, Nov 28, 2017 at 20:14:12 +0100, John Darrington wrote:
> 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.  

Not without sufficient context.  If a diff contains only lines changed
in a middle of a function, then you may not know what function was
actually changed.  I frequently experience that problem.  Usually I'm
looking at the diff in a VCS, in which case obtaining additional lines
of context is simple.  But if I were looking at a patch file, that isn't
the case.

A ChangeLog is also different from a diff---in a source distribution, I
expect that a ChangeLog will provide useful information.  I also expect
that such a distribution will not contain a diff for every change in
that ChangeLog.  There have been cases where I looked through a
ChangeLog for a project (e.g. Emacs) having downloaded a distribution
tarball rather than the actual repository.  And I was searching for the
name of a procedure that changed.  And I found it, easily, and
understood from the ChangeLog entry why the change was made, without
ever having to consider a diff and try to understand what all of the
surrounding code was doing.

The formality and (parsable) convention is also nice.  When writing
commit messages, someone may or may not even mention the name of the
procedure that was changed.

I only recently started writing ChangeLogs in the past year or so after
my experiences convinced me of its benefits.  But I write them as part
of my commit message.

> 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.

I agree.

> 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.

ChangeLogs also don't require special software to use.  They are plain
text---both human readable and easily parsable.  Repositories are a
binary format, and typical Unix-philosophy arguments apply.

-- 
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