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

[Benjamin Kaduk <[e-mail]>]

Hi Martin,

On Fri, Mar 13, 2020 at 01:55:55PM +1100, Martin Thomson wrote:
> Hi Ben,
> 
> Thanks for the close reading and constructive feedback.

My pleasure!

> 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.
> 
> On Thu, Mar 12, 2020, at 18:00, Benjamin Kaduk via Datatracker wrote:
> > In the vein of other comments, are we providing "best practices"
> > (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

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

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

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

> 
> > We seem to have introduced the github concept of "team" in passing here;
> > a more prominent note might be helpful.
> 
> 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).

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

> >    that new contributors need.  The README SHOULD contain a link to the
> >    CONTRIBUTING file.
> > 
> > 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.

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.

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

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.

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

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

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

> > 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?
> 
> It's the existence of the issue.  I've tweaked that language (and some of the latter text) to better align with that view.
> 
> > 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.)
> 
> 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).

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.

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

> > 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.
> 
> 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.
>  
> >    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".
> 
> added "...within the WG".
>  
> > 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.
> 
> Added a stronger recommendation to backup.  That is happening anyway.
> 
> > We could perhaps mention the potential consequences due to
> > authentication breach at github (minimal, due to distributed backups and
> > the I-D archive).
> 
> I will mention that.  Thanks.

Thanks!

-Ben