Re: ChangeLog entry complexity

[Alexandre Oliva <aoliva at redhat dot com>]

On Mar 28, 2013, Allan McRae <allan@archlinux.org> wrote:

> Given this thread is now 40 messages long, I decided to read through and
> make a summary of the pros/cons to keeping ChangeLogs that have been
> mentioned so far.

Thanks a lot for that!

> The only thing that I will add is that I find it rather difficult to
> find the "why" of many changes - although it is better now that we
> enforce all but trivial patches to go via the mailing list, so there is
> some (although far from ideal) reference there.

I agree with that.  Quite often, in my years of work in GCC and
binutils, I found myself locating changes I was interested in by
searching the ChangeLog, and then proceeding to look for further details
by searching mailing list archives.  While this shows the ChangeLog does
not contain all info I was looking for (which, per GNU standards, is the
way it should be), it also shows it was quite useful.  VCS logs that
aren't similarly structured wouldn't allow searching for e.g. function
names, and that's a frequent source of grief for me as I try to hunt
down changes in other projects that don't offer anything like
ChangeLogs.  There, the more detailed explanations in git logs provide
another piece of the puzzle, and they require a slightly different
workflow to locate the same information.

To me, what this means is that both pieces of information are valuable,
and people coming from one side or the other will have come up with a
workflow optimized for the sort of information available to them, which
might lead them (and us) to regard the information that's not part of
our optimized fastpath as far less useful, even unnecessary.

However, as I hope to have described above, *both* pieces of information
are useful, depending on what you're looking for and how you're looking
for it: terse statements of what changed at a function level enable some
kinds of searches that longer rationales don't, and vice-versa.

I'm now asking myself, why couldn't we have both?  Currently, it's not
uncommon for us to just use the ChangeLog entry as the VCS commit
message; why couldn't we add a longer rationale there, *besides* the
ChangeLog entry?  If we standardize how ChangeLogs are to be placed in
the commit logs, we can even get subsequent ChangeLog entries
automatically extracted from the commit history, so that it could be
included in releases that are not accompanied by the git history, so
that it could be machine-searched just as it is now, with the added
benefit that we'd be able to manually search for the same info in the
commit logs, and at the same time locate the rationale for the change.

And then, I get to ask myself why the heck are we not doing that
already? :-)

-- 
Alexandre Oliva, freedom fighter    http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/   FSF Latin America board member
Free Software Evangelist      Red Hat Brazil Compiler Engineer