[Ietf-and-github] Benjamin Kaduk's No Objection on draft-ietf-git-using-github-05: (with COMMENT)

[Benjamin Kaduk via Datatracker <[e-mail]>]

Benjamin Kaduk has entered the following ballot position for
draft-ietf-git-using-github-05: No Objection

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/



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

I support Alvaro's Discuss.

In the vein of other comments, are we providing "best practices"
(Abstract) or "guidelines" (Introduction")?

Section 1

   Although similar, guidance for IRTF Research Groups is out of scope
   for this document.  However, such groups may draw inspiration for
   GitHub use from the contents herein.

The guidance is similar or the groups are similar?

Section 1.2

   There are a large number of projects at GitHub and a very large
   community of contributors.  One way in which some IETF Working Groups
   have benefited is through increased numbers of reviews and associated
   issues, along with other improvements that come from broader

Benefited, I presume, from their use of github?

Section 2.1

   Organizations are a way of forming groups of contributors on GitHub.
   Each Working Group SHOULD create a new organization for the Working
   Group.  A Working Group organization SHOULD be named consistently so
   that it can be found.  For instance, the name could be ietf-
   wg-<wgname>, as recommended in [GH-CONFIG].

I'm not sure I understand why the recommended value for consistency is
given in the Informational document as opposed to the BCP.

   A single organization SHOULD NOT be used for all IETF activity, or
   all activity within an area.  Large organizations create too much
   overhead for general management tasks, particularly when there is a
   need to maintain membership.

Is this a membership list or membership that's synchronized with
something else, or ...?

   Each organization requires owners.  The owner team for a Working

nit(?): maybe "github's procedures require that each organization has
owners"?

   Each organization requires owners.  The owner team for a Working
   Group repository MUST include responsible Area Directors.  Area
   Directors MAY also designate a delegate that becomes an owner and
   Working Group chairs MAY also be owners.

   A team with administrator access SHOULD be created for the Working

We seem to have introduced the github concept of "team" in passing here;
a more prominent note might be helpful.

Section 2.2

   A simple example of how to do this is to include a link to the GitHub
   organization on the WG Charter page in the datatracker.  Similarly,
   if there are multiple mailing list options, links to those mailing
   lists should be given.

Multiple mailing lists would be, e.g., to get different volume of
notifications from github?  I don't think we've introduced any mention
of "there are mailing lists other than the main WG list" yet.

   Repositories MUST include a copy or reference to the policy that

nit: "copy of"

   applies to managing any documents they contain.  Updating the README
   or CONTRIBUTING file in the repository with details of the process

It's slightly surprising to see the non-.md version of these files
mentioned, but I don't have any reason why it specifically matters.

   that new contributors need.  The README SHOULD contain a link to the
   CONTRIBUTING file.

Should/can the README contain anything else?

Section 3

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

I think I saw another comment about this bit (but probably not all the
replies); it seems like the intent is more along the lines of "issue
tracker" type things than "slides for WG sessions", so clarification is
in order.

Section 3.1

   Working Group policies need to be set with the goal of improving
   transparency, participation, and ultimately the quality of the
   consensus behind documents.  At times, it might be appropriate to

Is there an example of how the policies might affect quality of
consensus.  (Also, does "quality of the documents" or even "quality of
the protocol being documented" not matter?)

Section 3.4

   In addition to the canonical XML format [RFC7991], document editors

[I'll channel Julian Reschke and note that RFC 7991 does not describe
the exact XML vocabulary used for the canonical RFC output...]

Section 4.1.1

   If labels are a core part of Working Group process, chairs MUST
   communicate any process to the Working Group.  This includes the

(We already said that chairs have to communicate the process to the WG,
regardless of whether issues are a core part of it or not.)

Section 5.2

   In addition to managing documents, the Working Group might choose to
   use GitHub for tracking outstanding issues.  In this mode of
   interaction, all substantive technical discussions are tracked as
   issues in the issue tracker.  However, discussion of any substantial

Is it the discussions themselves that are tracked, or the existence of
the topic being discussed?

Section 5.3

   Decisions about Working Group consensus MUST always be confirmed
   using the Working Group mailing list.  However, depending on the
   maturity of documents, this might be a more lightweight interaction,
   such as sending an email confirmation for a set of resolutions made
   using GitHub.

Perhaps "an initial set of resolutions arrived at by the GitHub
participants"?

Section 5.3.1

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

This section is "Early Design Phases"; would a document move directly
from "early design phase" to WGLC without some other intermediate step
which would allow for detection of such abuse?  (In light of the
following paragraph perhaps the best approach is to change the name used
to describe this phase.)

Section 5.4

   Working Groups or editors might use additional labels as they choose.
   Any label that is used as part of a process requires that the process
   be documented and announced by Working Group chairs.  Editors SHOULD
   be permitted to use labels to manage issues without any formal
   process significance being attached to those issues.

Is there some conflict between "WG chairs must document and announce
process" and "editors are permitted to use labels without any formal
process significance"?  I'm not really sure I understand what this is
trying to say.

Section 6

   This creates a stable snapshot and makes the content of the in-
   progress document available to a wider audience.  Documents submitted

Is "wider audience" code for "the traditional IETF mode of work"?  Stuff
on github seems ... pretty available, as does the I-D archive; it's hard
to have much confidence in a claim that one has a "wider audience" than
the other.

Section 7

   If permitted, GitHub will be used for technical discussion and
   decisions, especially during early stages of development of a
   document.  Any decisions are ultimately confirmed through review, and
   ultimately, through Working Group Last Call (see Section 7.4 of
   [RFC2418]).

I'm not sure I understand what is meant by "review".

Section 10

I agree with Roman that it's surprising to mention that tools for
backing up "other information" exist but not make any recommendation for
their usage.

We could perhaps mention the potential consequences due to
authentication breach at github (minimal, due to distributed backups and
the I-D archive).