Re: [gnu-prog-discuss] An experimental GNU Assembly

[Stefano Lattarini]

On 12/22/2011 06:19 PM, Thien-Thi Nguyen wrote:
> () Stefano Lattarini <address@hidden>
> () Wed, 21 Dec 2011 09:52:55 +0100
> 
>    I have a few objections against making the format you propose the base of
>    the ChangeLog entry format to be suggested in the GCS.  See my comments
>    inline, below.
> 
> Thanks for looking it over.
>
Thanks to you for working on it ;-)

>    bug-standards perhaps?  (but I'm not any more sure that you are).
> 
> Fine w/ me.  CC changed.
>
Good.

>    >       Most information about the change should be placed in the source
>    >       code comments.  SHORT-PARAGRAPH is for referencing bug reports,
>    >       giving credit (i.e., "Reported by" and "Suggested by" blurbs),
>    >       and pointers to the origin of regressions
>    >
>    So your proposed format doesn't explicitly allow for a high-level, "global"
>    explanation of what a change does, and perhaps even more importantly, why.
>    This is an unacceptable limitation IMO.
> 
> After reading your explanation of this kind of text (in another part of
> the thread), i have come to agree.  SHORT-PARAGRAPH should include
> "motivation for change".  How about this?
> 
>  SHORT-PARAGRAPH is for describing the motivation for the change,
>  i.e., "why", including perhaps a summary of the pre-change state.
>  (Information about the post-change state should be placed in the
>  source code comments.)
>
I'd do "s/should be placed/are usually better placed/", to give some slack and
accomodate the not-so-common-but-no-so-rare cases where adding comments about
the post-change state to the ChangeLog entry is useful or worthwhile.

Maybe, if you fee like it, you could add a mild warning against the mistake
of placing too much comments in the ChangeLog entry and too few in the code
(I succumbed to this error few times already, and I see why warning against
it might be warranted).  Your call.

  SHORT-PARAGRAPH should also reference bug
>  reports, give credit (i.e., "Reported by" and "Suggested by"
>  blurbs), and give pointers to the origin of regressions.
> 
>    > (using conventional format "Regression introduced YYYY-MM-DD [TITLE].")
> 
>    Some packages prefer to refer to the VCS revision as well (or exclusively).
>    This is a point were we can give individual packages some slacks IMHO.
>    WDYT?
> 
> Agreed.  I think ‘s/conventional/the suggested/’ is indicated, plus the
> sentence: "(The intent of this format is to make it easy to search for
> that particular ChangeLog entry as well as give an immediate sense of
> how long the problem persisted.)"
> 
+1 on this.  But you might also want to point out explicitly that some projects
also refer to VCS revision, and that it is accepted practice.

>    >         "U" means "Use ‘func’".
>    >
>    This just seems confusing to me; while I don't strongly object to 
> individual
>    packages using this "trick" if they find it useful, I'd rather not see it 
> in
>    an examples in the GCS.
> 
> Right, too ttn-specific.  Drop it.
>
Thanks.

>    >       In this particular example, you can also write:
>    > 
>    >         Here, all C files now #include "header.h".
>    >         * foo.c (foo): Use ‘func’.
>    >         * bar.c (bar, baz): Likewise.
>    >         (qux): Update call to ‘bar’.
>    >         * doc.texi (ref): Mention "header.h".
>    >
>    This is what I'd do.
> 
> Then we can just drop the first part, or explain better the idea
> behind it.
> 
>  ENTRY-CONVENTIONS describe entry-specific abbreviations or
>  implicitly shared descriptions.  The idea is to factor out common
>  bits of text, for readability, while preserving the full name of
>  functions or other code elements.
>
This might be overly-specific...  I'm not opposed to it (rather I'm somewhat
indifferent), but I so think it would be better to propose it in a separate,
follow-up patch.  Your choice though, I won't object anyway.

>    > ***** entries titled with suffix "; nfc."
> 
>    No strong opinion about this; but it seems to me that it might preferable 
> to
>    explicitly leave it to individual projects to decide whether to use this
>    particular convention, or to always prefer something like:
> 
>            [maint] Add top-level file HACKING
> 
>            * HACKING: New file.
> 
>    instead.
> 
> Probably best to drop this entirely.
>
Yes.  Thanks.

>    > ***** conventions for TITLE
>    > ******* tag
>    >  To help identify the area of the change, include one or more
>    >  tags in square braces at the beginning of the TITLE.
>    >
>    Many other gnu packages prefer the format:
> 
>       topic: brief description
> 
>    to the one you are proposing, that if I'm not mistaken is:
> 
>      [topic] brief description
> 
>    Should we try a poll of existing packages to decide which format to
>    choose, or is this another area where to leave the packages some
>    slack?
> 
> Hmm...
> 
>    >  For
>    >  example, ‘maint’ for maintenance, ‘int’ for internal, ‘api’,
>    >  ‘guile’, etc.  Because space in the TITLE is limited, tags
>    >  should be short and (if more than one) separated by a space.
>    >  For example:
>    > 
>    >  [guile int] Avoid deprecated libguile elements.
> 
> This example shows why i prefer tags: you can use them multiply.
>
Or you could do:

  guile, int:  Avoid deprecated libguile elements.

;-)

> Having said that, i realize that people see things differently.
> How about adding:
> 
>  Alternatively, if there is no need for multiple tags, you can use
>  the more succinct form:
> 
>     TOPIC: BRIEF-DESCRIPTION
> 
> This way, there is slack, but not too much slack.
>
Hmm... I'd rather not have two ways of formatting the so-fundamental
title line.  I think we should try to settle on one if possible.

Regards,
  Stefano