Re: ChangeLog or not?

[Ludovic Courtès]

Hi!

Mark H Weaver <address@hidden> skribis:

> I agree with you.  While I see nothing inherently wrong with verbose
> commit logs, in practice this tends to come at the expense of comments
> in the code itself, and that is a very serious problem.

Yes, exactly.

In addition, there’s value IMO in having change logs be exactly that: a
log of changes made to the source code’s AST.  This tells how the
changes were implemented (useful when reviewing), while the comments
and/or posts would explain why.

Andy Wingo <address@hidden> skribis:

> I wonder though about some specific cases.  For example,
> performance-related changes.  Justifying performance improvements
> necessarily depends on a description of two different revisions of a
> piece of functionality

Not necessarily.  The source code could have a comment close to the data
structure, algorithm, etc. that would say “this is done this way because
it has such and such nice performance characteristics.”

The advantage is that future readers would notice and have those
concerns in mind when touching the code.

[...]

> Similarly for "X is temporarily moved to Y but will be moved to Z in a
> future commit".

I can’t really see what that pattern would be.

Anyway, there are surely exceptions, but I think the basic rationale
holds most of the time.

> There are probably other cases.  Dunno, perhaps I have not yet been
> fully indoctrinated :-)

I actually view the change log chapter of the GCS as a rational
justification of the practice, more than as a a doctrine.  :-)

Thanks,
Ludo’.