This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v2 3/5] manual: Add new header and standards annotations.
- From: Rical Jasan <ricaljasan at pacific dot net>
- To: libc-alpha at sourceware dot org
- Cc: Joseph Myers <joseph at codesourcery dot com>, mtk dot manpages at gmail dot com, carlos at redhat dot com
- Date: Mon, 6 Feb 2017 21:12:46 -0800
- Subject: Re: [PATCH v2 3/5] manual: Add new header and standards annotations.
- Authentication-results: sourceware.org; auth=none
- References: <20161206105525.21117-1-ricaljasan@pacific.net> <20161206105525.21117-4-ricaljasan@pacific.net> <alpine.DEB.2.20.1612071624470.23761@digraph.polyomino.org.uk> <665e49d4-dfa0-e14d-a793-d4acdca8e617@pacific.net> <alpine.DEB.2.20.1612081401130.3473@digraph.polyomino.org.uk> <7dd6da88-601f-e6f2-1f16-c24d7fdf84e2@pacific.net> <alpine.DEB.2.20.1612141818020.32751@digraph.polyomino.org.uk> <8c01ffc4-fcee-d584-bfab-d74a0b552b77@pacific.net> <8e8b0d56-b001-1870-1b5c-9895a1301c07@pacific.net> <alpine.DEB.2.20.1612151300180.15350@digraph.polyomino.org.uk>
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