ChangeLog entry complexity

[Petr Baudis <pasky at ucw dot cz>]

  Hi!

On Mon, Mar 11, 2013 at 05:14:12PM -0400, Carlos O'Donell wrote:
> The code in question is a macro, therefore the ChangeLog is
> considerably more complicated by the conditionals.
> 
> Please see the conditional ChangeLog section in the 
> GNU Coding Standard:
> http://www.gnu.org/prep/standards/html_node/Conditional-Changes.html#Conditional-Changes
> 
> If I had to create a ChangeLog for this the first part would
> look like this:
> 
> 	* string/bits/string2.h [__GNU_C_PREREQ (3,2)]
> 	(__BUILTIN_SINCE_GCC_3_2): Define as call to __builtin_##fn.
> 	[!__GNU_C_PREREQ (3,2)]
> 	(__BUILTIN_SINCE_GCC_3_2): Define as call to fn.
> 	[!_HAVE_STRING_ARCH_strchr && __GNU_C_PREREQ (3,2)] (strchr): Remove.
> 	[!_HAVE_STRING_ARCH_strchr] (strchr): Define with __BUILTIN_SINCE_GCC_3_2.
> 
> Does that help?
> 
> Even I get these complex conditionals wrong sometimes ;-)

  I'm sorry if this is revisiting some past discussion. However,
it seems that many patches get stalled on ChangeLog entries, and
I always wince a little when I see that, since it seems our community
is spending a lot of resources (including an additional barrier to
new contributors) just on the ChangeLog. I didn't compute any actual
stats, but the portion of patches that gets re-spinned just on the
grounds of fine-tuning the ChangeLog seems massive.

  So, I wonder

  (i) Is it worth it? I think we should take few steps back and
consider the costs of ChangeLog maintenance and whether it is worth
the benefits the ChangeLog brings. Of course there *are* some benefits
even when tracking history with Git, I'm just saying we should keep
in mind that there are costs as well. Even if the answers is "it is
worth it",

 (ii) Do we need to be so strict about it? Some parts of the syntax
that are often wrong on the first try are important to keep so that
the file remains machine-readable. However, the above example with
conditional changes seems like something utterly useless to insist
on in this particular case. *Sometimes,* conditionals are useful to
include, but I wouldn't reject patches just because this is missing
even if I thought so.

  (My personal view is that ChangeLog is just too expensive to maintain.
When investigating the history, I always used 'git log' anyway except
for the CVS-imported history, and maybe sometimes turn to ChangeLog for
extra information, but this could be just kept in the commit message.)

				Petr "Pasky" Baudis