Re: [Ietf-and-github] Alvaro Retana's Discuss on draft-ietf-git-using-github-05: (with DISCUSS and COMMENT)

[Martin Thomson <[e-mail]>]

Hi Alvaro,

Thanks for the feedback.  I think that we'll pursue the DISCUSS thing separately.  I want to (attempt to) discharge your comments.

I have prepared a pull request that you can review here: https://github.com/ietf-gitwg/using-github/pull/47
I appreciate that you didn't repeat comments from others, but in case you care, there is a collection of changes proposed as a result of other reviews: https://github.com/ietf-gitwg/using-github/pulls

On Thu, Mar 12, 2020, at 05:53, Alvaro Retana via Datatracker wrote:
> (2) It would be nice to have a short terminology section; I assume many people
> reading this document will not already be GitHub-savy, so push, pull, commits,
> may not be familiar to them.  Alternatively, an Informational pointer to a
> tutorial would also be ok.

I've added a reference to the GitHub glossary that covers both git and GitHub terminology in some detail.
 
> (3) Personally, I don't have an issue with the use of GitHub, but some of the
> statements in the Introduction sound like marketing blurbs, for example:
> 
> - "Use of this service has been found to reduce the time that Working Groups
>    need to produce documents and to improve the quality of the final result."
> 
> - "...encourage contributions from a larger set of contributors."
> 
> - "Using GitHub can also broaden the community of contributors for a
>    specification."

That's a fair observation, yes.

> (5) [major]  §5.3: "Working Group chairs SHOULD confirm that the Working Group
> has consensus to adopt any process."  When would the chairs not confirm
> consensus to adopt a process?  IOW, why is this not a MUST?
> 
> Note that §3 says this:
> 
>    Working Group Chairs are responsible for determining how to best
>    accomplish the charter objectives in an open and transparent fashion.
>    The Working Group Chairs are responsible for determining if there is
>    interest in using GitHub and making a consensus call to determine if
>    the proposed policy and use is acceptable.
> 
> Even though this text doesn't use rfc2119 keywords, my impression of the intent
> is that it is required for the chairs to make the consensus call.  IOW, I think
> that this text and the one above (from §5.3) are in conflict.

I'm going to remove the keywords here.  Because this is a specialization of language from RFC 2418 and while the specialization is useful, the use of 2119 keywords isn't consistent with the original:

  The Chair has the responsibility and the authority to make decisions,
   on behalf of the working group, regarding all matters of working
   group process and staffing, in conformance with the rules of the
   IETF.  

> (6) §5.3.2:
> 
>    Gaining Working Group consensus about the resolution of issues can be
>    done in the abstract, with editors being permitted to capture the
>    outcome of discussions as they see fit.
> 
> This sentence doesn't sound right to me: "consensus...can be done in the
> abstract, with editors being permitted to capture the outcome...as they see
> fit".  That last part doesn't sound right: Chairs call consensus.  Maybe I'm
> misinterpreting...

Others have had trouble with this.  Perhaps rephrasing is in order.  How does this sound?

> Chairs are able to declare Working Group consensus about the resolution of issues in the abstract, allowing editors discretion on how to capture the decisions in documents.

> (7) [major]. Why is draft-ietf-git-github-wg-configuration listed as a
> Normative Reference?  I don't think that dependency is needed.

I will adjust.  There is no normative dependency.  Thanks for noticing.