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

[Barry Leiba via Datatracker <[e-mail]>]

Barry Leiba has entered the following ballot position for
draft-ietf-git-using-github-05: Discuss

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)


Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.


The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-git-using-github/



----------------------------------------------------------------------
DISCUSS:
----------------------------------------------------------------------

I have a really simple thing to discuss before I move to a “yes” ballot:

— Section 4.1.3 —

   Chairs need to assess whether the
   arguments offered represent new information or not.  This can require
  some discussion to determine accurately.  Resolved issues MUST remain
   closed unless there is consensus to reopen an issue.

There seems to be an inconsistency here: WGCs decide whether new information
has been given, so it would seem that it’s the WGCs who decide that an issue
should be reopened.  But then we say there has to be consensus for it.  In
addition to that appearing inconsistent, I’m not clear how one would determine
whether there’s rough consensus to reopen an issue, if doing so were
controversial.


----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

Idle question: Would it make sense for this document to formally update 2418?

— Section 1.2 —

   GitHub is freely accessible on the open Internet,
   albeit currently only via IPv4.

Why mention v4 only?  Does such mention have archival value once github
supports v6?

   GitHub provides a simplified and integrated interface to not only
   git, but also provides basic user management, an issue tracker,

This doesn’t really work as written; I suggest this:

NEW
   GitHub provides a simplified and integrated interface to
   git, and also provides basic user management, an issue tracker,
END

   along with other improvements that come from broader
   participation by facilitating those in the community to participate.

Participation/participate feels odd.  Maybe, “along with other improvements
that come from facilitating participation by a broader community.” ?

— Section 1.5 —
Please use the boilerplate directly from 8174: it was debated and worded as it
is intentionally.  (That said, this is not a blocking comment.)

— Section 3 —

   Chairs MUST involve Area Directors in any decision to use GitHub for
   anything more than managing drafts.

I’m not objecting to this, but... why?  If the WGCs may decide to use github
for drafts without involving the ADs, why can’t they also decide to use it for
charter revisions, agendas, and minutes without involving the ADs?

— Section 4.2 —

   Pull requests are the GitHub feature that allow users to request
   changes to a repository.

There’s a number agreement issue here (“feature” and “allow”).  I would fix
this by making it all singular, so the sentence doesn’t sound strange:

NEW
   A pull request is a GitHub feature that allows a user to request
   a change to a repository.
END

— Section 4.2.1 —

   In addition to the features that pull requests share with issues,
   users can also review the changes in a pull request.  This is a
   valuable feature, but it has some issues.

You use “issues” here in two different senses; I suggest reserving the word for
referring to github “issues”, and using a different word for “but it has some
issues.”  Maybe, “but it presents some challenges.”

— Section 5.3.1 —

   Finally, process checkpoints like Working Group Last Call
   (WGLC; Section 7.4 of [RFC2418]) provides additional safeguards

Number agreement: “Finally, process checkpoints, such as Working Group Last
Call (WGLC; Section 7.4 of [RFC2418]), provide additional safeguards”.

— Section 6 —

   During the development of a document, individual revisions of a
   document can be built and formally submitted as an Internet-Draft.

Nit: two indefinite articles feels odd; I would make it, “individual revisions
of the document”.