Re: Writing changelog entries

["Randy Brukardt" <randy@rrsoftware.com>]

"Florian Weimer" <fw@deneb.enyo.de> wrote in message
news:87wtus3do0.fsf@deneb.enyo.de...
> Generating the changelog is not the problem.  It's the format of the
> entries in it.  Many projects have explicit guidelines which ensure
> that you can grep the changelog and find the change which affected a
> particular entity.  However, these guidelines are C-specific and do
> not take homographs into account (and neither nested subprograms, and
> so on).

My personal opinion is that that is not worth it. Changes should have been
at least minimally tested before being checked it, and if they cause a
regression test to fail, they should be fixed immediately while the
programmer still remembers what he did. (They then won't need to work back
through the system.)

That leaves the rare cases where a problem shows up much later. In those
cases, it's usually necessary to debug the entire thing again anyway. So,
leaving comments in the place where the code is the most valuable, because
it's where you're going to be looking anyway.

If it takes two extra minutes (probably conservative) to create structured
changelogs, you'd have to save more than 4 hours of development time to come
out ahead on the 1 out of 100 (probably pessimistic) changes that you have
go back and debug in the future. While that's possible, it seems unlikely.
Just having the CM (with no changelog at all) seems to save most of the
time; I do try to put the bug report number into the code and/or edit
history (presuming it is formally tracked; we only do that for outside bug
reports, because of the time investment), which helps find the change again
if needed.

                    Randy.