[Development] ChangeLogs

[Oswald Buddenhagen]

On Fri, Jan 18, 2013 at 07:49:41PM +0800, Thiago Macieira wrote:
> On sexta-feira, 18 de janeiro de 2013 11.49.12, Oswald Buddenhagen wrote:
> > yes, and the purist in me agrees. but as both kai and eskil pointed out,
> > this isn't so much additional clutter, so whatever - i kind of don't
> > see the change-id lines when i browse logs anyway.
> 
> The Change-Id is not redundant information. It's new information, not present 
> elsewhere.
> 
that wasn't the point. for the human reader, the change-id is noise most
of the time. still, it's necessary for the system. the same could be
said about the new footer, in a slightly different way.

> > an additional upside of doing this while creating the commit is that one
> > may be more thorough with the message and the whole commit, as one is
> > forced to consider it from an additional angle. so it plays in the same
> > league as "needlessly" insisting on commit atomicity and other "process
> > stuff".
> 
> And that leads to another downside: what if two or more commits were necessary 
> to fix a bug? Then the ChangeLog line would be referring to changes that are 
> not found in that commit, which could be confusing later on.
> 
the actual, final bug fix should be in the last commit. if multiple
"terminal" commits refer to the same bug, i'd venture the assertion that
something is wrong with the definition of the bug (atomicity). and if the
same type of bug is fixed in multiple places, the placement of the
changelog footer is arbitrary (provided no reference to the specific
function is deemed necessary. otherwise the lines need duplication, and
can be manually merged at log generation time (the automatic log
extractor can be made clever enough to pre-group similar entries to ease
this)).

> I don't buy the "be more thorough" argument. If the commit message was written 
> properly, the ChangeLog line is redundant because it's rephrasing what has 
> already been said before, except that it's less detailed and is written in the 
> past tense (as opposed to the imperative that most people seem to prefer).
> 
the point is that the commit message is often *not* written properly,
because people have a too focused mindset at the time of writing (or are
just too lazy, but that's another topic ;). bringing in the additional
aspect to consider is exactly what may help addressing this problem to
some degree.
and yes, i know that *your* commit messages are (usually) already as
perfect as it gets. but let's face it: you are the exception.

> If we're going to do this, then let's agree that it must always be the 
> *second* paragraph of the commit message -- that is, the first paragraph of the 
> body -- and it must go with the flow.
> 
i'd already add an exception to that: if the description is a
grammatical continuation of the summary, shift one down:

============
don't do foobar when bazbaking terzknolfs and some other stuff

... because otherwise frudings will crash in yeeeeHa().

ChangeLog: oh, well

you know, things happen ...
====

the point is that it gets arbitrarily complex, and adding more rules
won't help. of course we can endorse a particular style to reduce
redundancy, but it's technically not necessary and can be left to the
discretion of the contributor (and his reviewers).

what is much more important is that the ChangeLog entries need to be
"tagged", so they can be automatically sorted into the right categories:

ChangeLog: Core: SIC: renamed brokenName() to usefulName()

i.e., what many people do with commit message summaries (which i find
just plain annoying, because it adds noise and doesn't really solve the
problem it supposedly tries to address (the one we are discussing now)).