bug-standards
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: changelog format


From: Stefano Lattarini
Subject: Re: changelog format
Date: Wed, 18 Jan 2012 11:12:10 +0100

On 01/17/2012 10:16 PM, Alfred M. Szmidt wrote:
>
> [SNIP parts I've already replied to]
>

>    >    + @item give credit
>    >    + It is courteous to acknowledge the help of others.  Although such
>    >    + information may be available indirectly through a URL, including it
>    >    + in the change log fosters community spirit and makes it more
>    >    + self-contained.
>    >    + @end table
>    > 
>    > I don't think ChangeLog shouldn't be used to give credit, that is what
>    > AUTHORS and then THANKS files are used for;
> 
>    But the ChangeLog let you register *why* are you giving credit.
>    For example, in Automake, the policy is to list any "helping
>    person" in THANKS (with full name and associated e-mail address),
>    and then cite it (full name only)
> 
> You can do similar in THANKS.
>
But doing that in the commit message is more natural, since it easily and
naturally keeps the thanking near to the change for which it is warranted.
It make things self-explanatory.  Also, for projects with multiple branches,
Keeping the THANKS file simple and linear (with only additions of new names
and e-mails) avoids potential spurious merge conflicts in the THANKS file
itself.

>   Stefano Lattarini: Added numerous test cases, ....
> 
> This is more concise, and easier to look at.
>
And become unwieldy for users that have contributed with lots of suggestions
and bug reports.

>    in the relevant ChangeLog entry.  As an example, see some excerpts of real
>    ChangeLog entries in Automake:
> 
>      "Report and suggestions by Peter Rosin and Eric Blake."
>      "Reported by Jim Meyering in automake bug#10418."
>      "Report and analysis by Paul Eggert."
>
(You haven't said anything about these, so I assume they are good examples).

>      "Report and initial patch by Zack Weinberg, test cases added by
>       Stefano Lattarini."
>
This is a bad example OTOH, I agree.

[SNIP good objections to my bad example]

> The CL header should state who _wrote_ the change; not who commited it.
>
I definitely know and I absolutely agree.  Sorry if I gave a different
impression.

>    >    ***************
>    >    *** 3544,3550 ****
>    >      Here are some simple examples of change log entries, starting with 
> the
>    >      header line that says who made the change and when it was installed,
>    >      followed by descriptions of specific changes.  (These examples are
>    >    ! drawn from Emacs and GCC.)
>    > 
>    >      @example
>    >      1998-08-17  Richard Stallman  <rms@@gnu.org>
>    >    --- 3561,3567 ----
>    >      Here are some simple examples of change log entries, starting with 
> the
>    >      header line that says who made the change and when it was installed,
>    >      followed by descriptions of specific changes.  (These examples are
>    >    ! drawn from Emacs and GCC, from back when the title was optional.)
>    > 
>    > Making it the description line mandatory is definitly a bad idea.
> 
>    FWIW, I *strongly* disagree.
> 
> Which makes it more prudent to make it optional; since everyone will
> have a differnt opinion on it.
>
But I'm convinced mine is not an opinion, but a *position* motivated by
sound technical arguments (see my previous answer for them).  That's why
I'm pushing so hard (and will continue to) to make the summary line
*unconditionally mandatory*.

OTOH, its exact format can be left more flexible, since different projects has
already different policies, all with their pros and cons, and no one of which
is clearly superior to the other ones (here we are in the realm of tastes and
opinions).

> The maintainer can decide if it should be mandatory or not for per project.
>
IMHO no, not anymore than he can decide whether his project should have a
GCS-conforming configure script or not.

Regards,
  Stefano





reply via email to

[Prev in Thread] Current Thread [Next in Thread]