Re: [PATCH v2 3/5] manual: Add new header and standards annotations.

[Rical Jasan <ricaljasan@pacific.net>]

On to 2.26!

I apologize for the sudden absence.  I was pulled away by some
priorities that kept me longer than I expected.  I've caught up on
libc-alpha and picked back up the work on header and standards annotations.

On 12/15/2016 05:01 AM, Joseph Myers wrote:
> On Thu, 15 Dec 2016, Rical Jasan wrote:
>> To confirm the approved pieces for once I'm prepared to push the commit
>> button, were you referring to only the chapters so far in this patch
>> ([v2 3/5] {argp,arith,lang,string}.texi) or also the first two
>> (patches)?  [v2 1/5] has been OK'd, no other comments; [v2 2/5] also
>> was, though a typo was pointed out in the commit message.
> 
> I'm referring to all patches or parts of patches that have been approved.
> 
>> On the topic of commit messages, How would you like me to write them if
>> this patch goes in piecewise?  Should the first one look how I submitted
>> it in this patch and subsequent patches can refer back to it or
>> duplicate it?  Or should they be rewritten to be more specific for each
>> commit (maybe if committed by file)?
> 
> The commit messages should be accurate in relation to the patch version 
> actually committed.

If I'm going to piecemeal [1], I have a question about how best to
change the commit message.  Chapter-by-chapter it's easier to provide
more detail, so I wrote the following for argp.texi, for example:

----
argp.texi contains several @vtables with variables lacking header and
standard annotations.  All ARGP_* variables are GNU extensions
declared in argp.h, and are annotated accordingly.

        * manual/argp.texi: Annotate variables declared in argp.h
        as GNU extensions.
----

The commit message in [1], however, contains the rationale behind these
changes, which is lost if I break the chapters apart and give specifics.
 If I were to include the rationale in every chapter, that would be
overly redundant.  I feel the patches speak for themselves, given the
rationale, but I also understand the need to ease review for larger diffs.

So, how would you like the per-chapter commits to read?

Thank you,
Rical

[1] https://sourceware.org/ml/libc-alpha/2016-12/msg00141.html