Proposal: Asynchronous review process for specification changes

Dear members of the WoT Working Group,

At the end of the WoT Architecture call last week Michael McCool and I had
a brief conversation about the approval process for landing pull requests
on W3C WoT specifications. I suggested that there might be an opportunity
to make the review process more efficient by using asynchronous tools,
rather than the current approach of only merging pull requests following a
resolution in a synchronous weekly conference call.

Currently:

   1. It is common to get to the end of a two hour meeting without having
   managed to review all of the open pull requests in a given repository
   2. If anyone is missing from the call who may have feedback, the
   discussion is often deferred for a week or more until they are available to
   join a call
   3. When pull requests are reviewed there isn't always a clear resolution
   about whether or not to merge and discussion can end up being paused until
   the following week
   4. Sometimes only small changes are needed to a pull request before
   landing it, but it has to wait another week for a chance for another review

Based on experience from other W3C Working Groups I'd therefore like to
propose using GitHub's in-built code review tools to formally review pull
requests without having to wait for the stars to align in a weekly call.

It seems to me that this form of asynchronous decision making would also be
more in line with the Working Group's existing Decision Policy
<https://www.w3.org/2019/10/wot-ig-2019.html#decisions>.

*Non-normative Changes*


   - For non-normative or editorial changes to the wording of a
   specification, I propose that a code review approval from a single Editor
   of the specification should be sufficient to merge a pull request.reating


*Normative Changes*

   - For normative or breaking changes to a specification, I propose that
   an approval be required by all active Editors of a specification. Editors
   should use GitHub's code review tool to either:
   - *Approve* the pull request (approval may be conditional on making some
      small changes like fixing typos before landing, noted in a comment)
      - *Request changes* to the pull request, explained in a comment
      - *Comment* to say that they have no strong opinion, deferring to the
      opinion of other editors
      - A pull request can be landed once all editors have either provided
   their approval or deferred to the other editors
   - Editors are expected to provide formal reviews, but all members (and
   non-members) may contribute to the public discussion on GitHub
   - If consensus can not be reached asynchronously, then a synchronous
   discussion in a web conference may be needed to arrive at a consensus. If a
   unanimous decision can not be reached then Chairs may call for a group vote
   to resolve a deadlock in line with the Working Group's existing Decision
   Policy <https://www.w3.org/2019/10/wot-ig-2019.html#decisions>
   - If there are Editors of a specification who are not currently
   regularly available for reviews and are not able to consistently review
   changes within a week or so, I propose that they should temporarily or
   permanently be moved to an "inactive" or "emeritus" editors list so that
   they don't block the review process

Note that the beauty of version control is that decisions need not be
final. It is easy to revert a change or modify it with a follow-up commit.
There are also plenty of opportunities to provide feedback on changes after
they have landed, through the various stages of W3C publication.

I further suggest this process could be aided by:

   1. Descriptive commit messages and pull request titles, ideally
   referencing an issue number that a patch relates to
   2. Configuring a simple template for pull requests where authors can
   select whether they consider the change to be normative/breaking or
   non-normative/editorial and therefore which level of review they are
   requesting

I would value your feedback on this proposal, which could potentially be
discussed in tomorrow's main WoT call.

It is also my hope that more efficient asynchronous working practices may
eventually allow for a drastic reduction in the number of W3C WoT meetings
conducted each week, which has in recent months ballooned out of control to
around twelve hours a week.

Best regards

Ben

-- 
Ben Francis
Founder
Krellian Ltd. <https://krellian.com>