Re: Using VC for change descriptions

[Mike Gerwitz]

On Tue, Jan 09, 2018 at 17:39:02 +0000, Joseph Myers wrote:
> I think we are going ever further into the wrong problem.  My hypothesis 
> is that for the vast bulk of changes, a list of changed entities is never 
> going to be of use in future development - so in the rare cases where it's 
> both relevant and complicated to generate, it can entirely appropriately 
> be left to the person who will use the list to generate it by examining 
> the diffs.

Unfortunately we can't know at the time of writing a change whether
those entities might be useful in the future.  Entities are concrete,
unambiguous---you can phrase them only one way.  Trying to search through
English describing a change can be very difficult.

When working with a team of developers, I frequently try to use `git log -G'
(and variants) to try to find entities that have changed.  Or
recursively `git bisect'.  Those are powerful features of Git, but
they're usually interactive, require the repository, require knowledge
of Git, and can be cumbersome depending on the types of changes that
were made.  Sometimes it's difficult to get the answer that I'm looking
for.  And once I've found it, more often than not, I have to figure out the
meaning behind the diff, possibly recursively until I find the change I
need.

As you say---which is true---changes can be discovered from diffs, and
often quite effectively.  I always get the answer I'm looking for.  I
can't recall a time where I didn't (unless the history simply didn't
exist).  I've learned dozens of tricks over the years using all tools at
my disposal.

But that doesn't mean that it's easy.  My goal is to make life easier for
those who come after me (including the future me).

ChangeLogs require only a program that can find a pattern in text and
display it to the user.  In many cases, I have found my answer in
ChangeLogs using nothing more than `grep -{A,B,C}`.  Further, I get a
concise history of _every_ time that entity was changed.  I don't have
to look at paragraphs of commit messages for every commit matched by
`git log -G`.  I don't have to keep recursively bisecting.

This isn't always the case, of course.  A combination of the history and
the ChangeLog are ideal.

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