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

[Rical Jasan <ricaljasan at pacific dot net>]

On 02/07/2017 08:40 AM, Joseph Myers wrote:
> On Mon, 6 Feb 2017, Rical Jasan wrote:
> 
>> 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.
> 
> I'd say the first commit should give the general description of the issues 
> / design of changes being made, then describe what's being done in that 
> particular commit.  Subsequent ones might then refer back to the first 
> commit / submission of that patch for details of the overall issue / 
> changes.

I was reflecting on this project today and yet another option crossed my
mind.  When I originally submitted this patchset, I had no idea what the
eventual framework would look like (well, had some ideas, but nothing
proposed or discussed)---I only knew that at least completing the header
and standards comments, even if just stubs, would make it easier later.
This patchset, however, kicked off some discussion about that framework,
resulting in a proposal like the following (very brief; see [1]):

  @def... foo
  @standards{GNU, foo.h}

There remains a good bit of detail to work out, including:

  * handling multiple headers/standards
  * handling @*x lists
  * placement in block (e.g., above/below @safety)
  * formatting of output
  * standardized standard names
  * generating the Summary
  * enforcing/checking annotations

but I think we have a good enough idea to start playing with it.

More to my point, though, how do you feel about abandoning this patchset
in favour of a v3 that tries to get us all the way through to the end,
now that I have something to work with in that regard?

I hate to unnecessarily burden reviewers, and having to review the
entirety of the comment-based changes, and then eventually having to
review the conversion, is probably more time-consuming than it needs to
be.  Given the discussion around [1], going directly there at this point
should only require a single pass for review (after all the other review
deciding how we want it look, etc., etc. ;).

I'd envision a v3 containing patches for:

  1. Introducing the @standards and related macros.
  2. Script(s) to generate the Summary and check annotations.
  3. Adding and converting annotations.

I imagine it's best to apply that kind of change all at once, but the
annotations are probably easier to review by chapter (as evidenced by
this thread).  I suppose I could kick out chapter-based patches for
review as I finish them (that review is basically for correctness;
output formatting and standards names can be ironed out separately/along
the way) and just wait until everything's ack'd to push?  Is that a
reasonable approach?

That also solves the problem of per-chapter v2 patches feeling out of
context, which I think is where my thought process started this
morning...  The new macros would have to go in first, so the stage will
already be set for all subsequent commits.

Thank you for your patience.  :)

Rical

[1] https://sourceware.org/ml/libc-alpha/2016-11/msg00923.html