Re: Using VC for change descriptions

[Joseph Myers]

On Wed, 10 Jan 2018, Mike Gerwitz wrote:

> Unfortunately we can't know at the time of writing a change whether
> those entities might be useful in the future.

That's generically the case for any aspect of a change description.  What 
we can judge is what's most useful for understanding the change *now*, and 
write that.  We can also judge what's hard to reconstruct from the diff, 
which is generally the higher-level information, versus what could be 
reconstructed from the diff in future if needed, which includes the list 
of entities.

If the average number of times a list of entities is needed is much 
smaller than 1 per commit (and I suspect it's much smaller, for the 
projects I work on), it makes more sense for the reader to construct it if 
needed rather than for the writer to construct such lists that will 
probably never be needed.

> Entities are concrete,
> unambiguous---you can phrase them only one way.

For the example I gave of Makefile entity names involving complicated GNU 
make constructs, that needed to be wrapped over multiple lines, that's not 
the case.

For cases where what's really changing is conditionals rather than 
entities, there's significant ambiguity about how to write them in the 
ChangeLog entry.  [foo || bar] or [defined foo || defined bar]?  Do you do 
"* [foo]: Remove conditional code." or list the individual entities 
removed within [foo]?  If it's a makefile conditional, do you use [ifeq 
($(foo), bar)] or [$(foo) = bar]?

Where the full name of an entity is long - with namespace or class 
qualification, or requiring parameter types for an overloaded function - 
exactly what form do you use?

> Trying to search through English describing a change can be very 
> difficult.

Trying to shoehorn the cases above into ChangeLog format can be very 
difficult.  You can produce something vaguely plausible, but there's no 
reason to expect that someone else would come up with the same form of the 
names so as to be able to search for them, or that what you've produced 
will be particularly useful.

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

The meaning behind the diff is what I think the commit messages should be 
providing - at a logical level, as appropriate to the diff in question.

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

I want to make life easier for developers by being able to concentrate on 
the changes themselves and a description at the logical, human level, 
without needing to spend time on a second description at a level only 
slightly above that of the diffs themselves, for projects where the level 
of ChangeLog entries is not generally the most helpful level for 
understanding the changes.

-- 
Joseph S. Myers
address@hidden