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

From: Benjamin Kaduk via Datatracker <[email-masked]>
Date: Thu, 12 Mar 2020 00:00:06 -0700

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).

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 13 Mar 2020 13:55:55 +1100

Hi Ben,

Thanks for the close reading and constructive feedback.

I've opened a PR based on your comments: https://github.com/ietf-gitwg/using-github/pull/52

I have snipped out those comments that appear to be editorial in nature to concentrate on the substantive matters.

> (Abstract) or "guidelines" (Introduction")?

In the abstract (not the Abstract), this was always written with the intent of being a set of guidelines.  Following those guidelines would be a best practice (though perhaps not a Best Practice that is also Current).

What I'm saying is that I realize that the distinction between these is important and I think that the determination about whether this is a BCP or Informational (we're headed toward the latter, I believe) shapes that.  I will propose a change to the abstract and intended status to that effect.

https://github.com/ietf-gitwg/using-github/pull/51

> given in the Informational document as opposed to the BCP.

I think that is because that's a tactical concern and not one that bears on the general guidance.  I am OK with the current location of that text.

(BTW, this threw me because I couldn't find this text where I was looking.)

> Is this a membership list or membership that's synchronized with

I've just cut that clause.  It was just odd.

I did that, but in checking on this, I found that this has changed quite a bit since this text was originally written.  So for the sake of transparency (and I'm hoping that it doesn't change too much more in the future), this is what I have now:

> Within an organization, members can be grouped into teams that are collectively given privileges with respect to repositories.  A team with "Admin" access to repositories SHOULD be created for the Working Group Chairs and any Working Group Secretary.

Note that the note about not being able to push no longer applies (this was a feature of the previous, now non-existent system, I think).

> Should/can the README contain anything else?

Not formally, no.  Though it routinely might include other things, like explain what the document is for, or link to the document.

> tracker" type things than "slides for WG sessions", so clarification is

Yes, that text was updated in response to Barry.  The consultation recommendation is now limited to when it comes to moving issue discussion to GitHub.  See https://github.com/ietf-gitwg/using-github/commit/e74ba457de2f0843a42c1214bec0033f559f187a
 
> the protocol being documented" not matter?)

I don't know whether you think that this needs text, but my view is that what we've seen in some of these efforts is greater alignment on the specific phrasing of text.  That doesn't necessarily mean that text is good (or right).  That is not something that is receptive to an objective analysis.  But the fact that you can litigate every apostrophe has improved the quantity of consensus, and the quality of it too.

OK, that was perhaps a little cynical.  I think that this can improve the quality of the underlying product as well, but it is not clear that the process actually cares about that.

Dammit, that was cynical too.  I think you are right, quality of documents is probably enough (as this is not limited to protocol specifications, I will avoid mentioning those specifically, but leave it as implicit).
 
> the exact XML vocabulary used for the canonical RFC output...]

Hm.  Julian is of course correct, but it's a technical kind of correctness that tends not to leave room for making statements that depend on the intent of the document, which this is.

> the topic being discussed?

It's the existence of the issue.  I've tweaked that language (and some of the latter text) to better align with that view.

> following paragraph perhaps the best approach is to change the name used

In response to Mirja, most of the following text was moved; see https://github.com/ietf-gitwg/using-github/pull/45 .  I haven't read her followup yet, but more might come.  However, as this is in response to a particular issue that only really arises from the interaction style under discussion, I don't see an easy way to resolve this without more restructuring and I'm disinclined to do that now as that could be too disruptive (I don't want this to be the reason, but there are also 10 PRs open with known conflicts to resolve).

> process significance"?  I'm not really sure I understand what this is

No conflict.  I was hoping that is was clear that semantics might be assigned to a set labels (editorial/design for instance), but that other labels should remain usable for other purposes.

> to have much confidence in a claim that one has a "wider audience" than

Yes.  It is recognizing that there are some people who prefer to consume things in a particular format and that those people might not be considered part of the audience who consume the GitHub versions.  I always use the editor's copy of drafts on GitHub where possible, but I have heard that others, particularly those who track things less closely, might prefer not to have to deal with a moving target.

In terms of the claim, I think that it's accurate, as long as the audience for an I-D is not a strict subset of the audience for the content provided on GitHub, then A∪B > A.
 
> I'm not sure I understand what is meant by "review".

added "...within the WG".
 
> backing up "other information" exist but not make any recommendation for

Added a stronger recommendation to backup.  That is happening anyway.

> authentication breach at github (minimal, due to distributed backups and

I will mention that.  Thanks.

---

From: Benjamin Kaduk <[email-masked]>
Date: Thu, 12 Mar 2020 21:20:13 -0700

Hi Martin,

> Thanks for the close reading and constructive feedback.

My pleasure!

> https://github.com/ietf-gitwg/using-github/pull/51

(I think I need to catch up on the other threads before I have anything
useful to add here.  Thanks for staying on top of it.)

> I think that is because that's a tactical concern and not one that bears on the general guidance.  I am OK with the current location of that text.

I'm happy to defer to your judgment.

> (BTW, this threw me because I couldn't find this text where I was looking.)

It does come off a bit obtuse, yes; sorry about that.  (I could have said
"why do we mention the string ietf-wg-<wgname> here when we defer to some
other document to actually recommend that string" instead.)

> I've just cut that clause.  It was just odd.

The best I could come up with was that it indicated the need for an ongoing
curation activity as opposed to an initial static configuration.

> Note that the note about not being able to push no longer applies (this was a feature of the previous, now non-existent system, I think).

I am not entirely sure; I think part of why github added Admin as distinct
from Owner was to avoid granting implicit write.

> Not formally, no.  Though it routinely might include other things, like explain what the document is for, or link to the document.

Okay.  If we wanted to say "the README is just a pointer to CONTRIBUTING"
we could do that, but it sounds like we don't.

> Yes, that text was updated in response to Barry.  The consultation recommendation is now limited to when it comes to moving issue discussion to GitHub.  See https://github.com/ietf-gitwg/using-gith…

That helps a lot.  I am not sure whether it says something one way or the
other about "any decision to use GitHub" being a one-time thing vs.
re-consulting for incremental changes in usage.

> Dammit, that was cynical too.  I think you are right, quality of documents is probably enough (as this is not limited to protocol specifications, I will avoid mentioning those specifically, but lea…

[I appreciate following your inner monologue, and like where the text ended
up.]

> Hm.  Julian is of course correct, but it's a technical kind of correctness that tends not to leave room for making statements that depend on the intent of the document, which this is.

Depending on what you bind "canonical" to this sentence is more or less
correct.  But I agree that we should not change the text...

> In response to Mirja, most of the following text was moved; see https://github.com/ietf-gitwg/using-github/pull/45 .  I haven't read her followup yet, but more might come.  However, as this is in r…

I doubt that my remark here had any key insight and am happy to let the
other PRs settle and take a look at that result.

> No conflict.  I was hoping that is was clear that semantics might be assigned to a set labels (editorial/design for instance), but that other labels should remain usable for other purposes.

Oh, it's the *labels* that lack formal process significance, not the use of
them.  Sure, that makes sense.

> I will mention that.  Thanks.

Thanks!

-Ben