From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 23894 invoked by alias); 8 Feb 2017 08:50:58 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Received: (qmail 23877 invoked by uid 89); 8 Feb 2017 08:50:57 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.1 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,RP_MATCHES_RCVD,SPF_PASS autolearn=ham version=3.3.2 spammy=completing, abandoning, eventual, standardized X-HELO: mail.pacific.net Subject: Re: [PATCH v2 3/5] manual: Add new header and standards annotations. To: Joseph Myers References: <20161206105525.21117-1-ricaljasan@pacific.net> <20161206105525.21117-4-ricaljasan@pacific.net> <665e49d4-dfa0-e14d-a793-d4acdca8e617@pacific.net> <7dd6da88-601f-e6f2-1f16-c24d7fdf84e2@pacific.net> <8c01ffc4-fcee-d584-bfab-d74a0b552b77@pacific.net> <8e8b0d56-b001-1870-1b5c-9895a1301c07@pacific.net> <0d5758f3-52bb-31cb-21e2-d218ace98065@pacific.net> Cc: libc-alpha@sourceware.org, mtk.manpages@gmail.com, carlos@redhat.com From: Rical Jasan Message-ID: Date: Wed, 08 Feb 2017 08:50:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.5.1 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit X-Null-Tag: 4f0d270735557ae5d2f824fc0ceca81d X-SW-Source: 2017-02/txt/msg00150.txt.bz2 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