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

From: Warren Kumari via Datatracker <[email-masked]>
Date: Tue, 10 Mar 2020 10:45:14 -0700

Warren Kumari 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 originally balloted Abstain, but this is (and has been) bothering me enough
that I'm changing it to a discuss.

This feels like additional centralization / control / process, without good
justification. I happen to use GitHub for my documents (along with discussion /
agreement with co-authors), but in personal repos. Our documents include
something like: "[ This document is being collaborated on in Github at
https://github.com/wkumari/<draft-name>.  The most recent  version of the
document, open issues, and so on should all be available there.  The authors
gratefully accept pull requests. ]"

This document contains a lot of text about setting up, administering, etc a WG
organization / repos -- but there is no good justification (that I could find)
on what advantages this has over simply encouraging people use GitHub (because
it is easy, and well known), and keeping things in their own repos. If WG
documents include a pointer (like above) to the repo, everyone can find it, and
we don't need all this. This smacks of scope-creep / chairs having control and
process where it a: isn't needed and b: isn't helpful.

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

I spent a while trying to decide between Abstain and DISCUSS.

I'm uncomfortable with much of this document:
1: This a BCP, and strongly implies that this is the "right" way for working
groups to manage themselves and documents streams. The charter says: "Whether
working groups choose to use GitHub or the documented policies to support their
work will remain entirely at their discretion." - while the document does let
WGs choose, the BCP track strongly implies that this is the "best" way. I
happen to put documents that I author in git (hosted on GitHub), and use that
to collaborate with my co-authors, but this is *our* choice, imposing our
working process on others is a mistake - we have used the "as long at it can be
turned into the canonical format we don't care how you make it" paradigm for a
reason. If people create the XML in vim or emacs is, and should be entirely
their decision - telling people that the "right" editor is vi is wrong - and a
BCP does that...

The charter also says: "The documents produced by this group will not alter the
Internet Standards Process (BCP 9). They will describe how to work within it."
but the document sails very close to the wind in many places - e.g: "Working
Group chairs MAY request a revision of an Internet-Draft being managed on
Github at any time, in consultation with document editors." It has always been
clear that chairs can request revisions to WG documents; this doesn't change
it, but mentioning things like this simply muddies the water / makes more
places for people to have to check. Section 7 is an example place where is is
really dangerous - and I think comes close to trying to change BCP9.

2: The focus on GitHub makes my deeply uncomfortable -- I get the argument that
it is the standard / best known hosted git provider (and, in my *opinion* the
right one for us to use), but there are many places where term "GitHub" applies
to "self hosted" solutions like GitLab / Gitea / etc. This feels very close to
the IETF recommending that WG participants sign the blue-sheets with a Bic pen
when all we need is some sort of writing implement. Just as one example:
"GitHub facilitates more involved interactions,..." this is true of gitea,
gitlab, bitbucket and many other tools -- calling out GitHub gives one tool
prominence and is not appropriate for the IETF to do.

3: We require that all decisions be made on mailing lists - when people happen
to use GitHub to collaborate on documents and happen to use the issue tracker
to track issues, it is clear that this is just for their personal convenience
-- having WG "owned" repos *will* lead to instances where decisions get made in
the issue tracker, and not communicated tp the mailing list - this will end up
with two classes of users: those that keep checking the issue tracker, and
those that follow the mailing list and are surprised by the decisions made.

4: git (and GitHub) has a really steep learning curve - if a WG decides to
fully jump in and start using GitHub, this (either explicitly or implicitly)
disenfranchises people who don't use or want to use git.

5: Moving state (primarily issues) from a personal repo to a WG one when a
document is adopted is non-trivial -- "You can only transfer issues between
repositories owned by the same user or organization account. You can't transfer
an issue from a private repository to a public repository." and they have to be
(AFAIK), moved individually - this will likely lead to loss of state (I may
also have missed it, but I don't see anywhere in the document that talks about
migrating a document / repo from an individual to a WG hosted version, and what
should happen). I have a document which moved from hosted at
www.github.com/wkumari/<document name> to
www.github.com/capport-wg/<document-name> - this involved administrative
annoyance, loss of state, and annoyance - for no benefit that I could see. I
think a much much better approach would be have people simple keep the
documents in their personal repos and not have the disruption that moving the
repo entails.

Don't get me wrong - I like git, and a: host my own gitea instance, b: maintain
a few gitlabs and gogs instances, and c: put all of my drafts in GitHub - but I
really don't think that the IETF should be implying that this is the "one true
way" (BCP) (nor do I like the WG hosted model).

---

From: Eric Rescorla <[email-masked]>
Date: Tue, 10 Mar 2020 11:01:10 -0700

Hi Warren,

I've got some thoughts about the merits of this DISCUSS comment, but before
I do that, which of the DISCUSS criteria [0] do you think applies to this
DISCUSS?

-Ekr

[0] https://ietf.org/about/groups/iesg/statements/iesg-discuss-criteria/

On Tue, Mar 10, 2020 at 10:45 AM Warren Kumari via Datatracker <
[email-masked]> wrote:

> _______________________________________________
> Ietf-and-github mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-and-github
>

---

From: "Joel M. Halpern" <[email-masked]>
Date: Tue, 10 Mar 2020 14:17:34 -0400

While I personally think this document should be approved (even though I 
have 0 desire to use github), I think we should be careful about what 
lens we use in looking at concerns.
In particular, the discuss-criteria document does not deal with process 
documents.  As written, if one were being a literalist, one would 
probably conclude that no AD could put a DISCUSS on any clear process 
document that made it thought IEtF last call.

While one might argue that would be good, I am quite certain that was 
not the intent when the IESG adopted those rules.  Personally, I would 
like the ADs to be able to use judgment when reviewing process 
documents, just as they do with technical documents.

Yours,
Joel

On 3/10/2020 2:01 PM, Eric Rescorla wrote:
> Hi Warren,
> 
> I've got some thoughts about the merits of this DISCUSS comment, but 
> before I do that, which of the DISCUSS criteria [0] do you think applies 
> to this DISCUSS?
> 
> -Ekr
> 
> 
> On Tue, Mar 10, 2020 at 10:45 AM Warren Kumari via Datatracker 
> <[email-masked] <mailto:[email-masked]>> wrote:
> 
>     Please refer to
>     https://www.ietf.org/iesg/statement/discuss-criteria.html
>     www.github.com/wkumari/ <http://www.github.com/wkumari/><document
>     name> to
>     www.github.com/capport-wg/
>     <http://www.github.com/capport-wg/><document-name> - this involved
>     administrative
>     [email-masked] <mailto:[email-masked]>

---

From: Eric Rescorla <[email-masked]>
Date: Tue, 10 Mar 2020 11:27:36 -0700

On Tue, Mar 10, 2020 at 11:17 AM Joel M. Halpern <[email-masked]>
wrote:

> documents.

This seems like a legitimate perspective, but when I read the DISCUSS
criteria, it seems to say that they apply to "Protocol Actions"  and this
document is listed in the Protocol Action section of the IESG Agenda (this
is confirmed by the draft announcement) [0]. So, if the IESG (or Warren)
wants to say that they don't think that the DISCUSS Criteria apply to
process BCPs, that seems like the place to start.

As written, if one were being a literalist, one would
> document that made it thought IEtF last call.

I actually read this differently, which is that the DISCUSS criteria don't
apply at all to !Protocol actions and so ADs are free to DISCUSS for any
reason. However, for the reason above, I think that the DISCUSS Criteria do
apply here.

-Ekr

[0] https://datatracker.ietf.org/doc/draft-ietf-git-using-github/writeup/

---

From: Warren Kumari <[email-masked]>
Date: Tue, 10 Mar 2020 14:36:48 -0400

I'm going to take option C: "This cannot be an exhaustive list, but
this set should be taken as exemplary of the common causes for
DISCUSSes seen by the IESG in the past.".

W

On Tue, Mar 10, 2020 at 2:01 PM Eric Rescorla <[email-masked]> wrote:
>
> Hi Warren,
>
> I've got some thoughts about the merits of this DISCUSS comment, but before I do that, which of the DISCUSS criteria [0] do you think applies to this DISCUSS?
>
> -Ekr
>
>
> On Tue, Mar 10, 2020 at 10:45 AM Warren Kumari via Datatracker <[email-masked]> wrote:
>>

-- 
I don't think the execution is relevant when it was obviously a bad
idea in the first place.
This is like putting rabid weasels in your pants, and later expressing
regret at having chosen those particular rabid weasels and that pair
of pants.
   ---maf

---

From: Alissa Cooper <[email-masked]>
Date: Tue, 10 Mar 2020 14:39:09 -0400

Isn’t this really an objection to the entire WG and its charter, and not to this document specifically?

Alissa

> On Mar 10, 2020, at 2:36 PM, Warren Kumari <[email-masked]> wrote:
>

---

From: Eric Rescorla <[email-masked]>
Date: Tue, 10 Mar 2020 11:47:16 -0700

Warren,

Thanks for your response. While it's true that the list cannot be
exhaustive, it seems to me that your DISCUSS comments pretty clearly fall
within the "non-criteria" bucket, specifically

"Disagreement with informed WG decisions that do not exhibit problems
outlined in Section 3.1 (DISCUSS Criteria)
<https://ietf.org/about/groups/iesg/statements/iesg-discuss-criteria/#stand-disc>.
In other words, disagreement in preferences among technically sound
approaches."

and potentially

"Reiteration of the issues that have been raised and discussed as part of
WG or IETF Last Call, unless the AD believes they have not been properly
addressed."

I note that the non-criteria do not contain the escape hatch you cite here,
but rather say clearly:
"None of the following are criteria for which the IESG should DISCUSS a
document; though they might reasonably form the basis of a non-blocking
comment on a document."

-Ekr

On Tue, Mar 10, 2020 at 11:37 AM Warren Kumari <[email-masked]> wrote:

> before I do that, which of the DISCUSS criteria [0] do you think applies to
> this DISCUSS?
> >
> > -Ekr
> >
> >

---

From: Warren Kumari <[email-masked]>
Date: Tue, 10 Mar 2020 14:51:46 -0400

> Isn’t this really an objection to the entire WG and its charter, and not to this document specifically?

Not really, but I will grant you that it is close...

A document which explained how to manage discussion between working
group mailing lists and GitHub issues and pull requests; how text
contributions are expected to be made; labeling and naming
conventions; maintaining readable draft snapshots; using tooling and
automation; informing participants about IETF policies; and other
information would be useful -- but this does more than that - it
pushes a (fairly) complex solution, and implies that it is the best
practice.  All of the above could still happen with documents at
www.github.com/billy-joe-bob, not www.github.com/ietf-important-wg,
with much less faff, and putting chairs in a "special" position.

W

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 11 Mar 2020 08:49:44 +1300

Hmm Warren. This seems to match https://www.ietf.org/about/groups/iesg/statements/iesg-discuss-criteria/#stand-undisc much better than https://www.ietf.org/about/groups/iesg/statements/iesg-discuss-criteria/#stand-disc

Regards
   Brian Carpenter

---

From: Barry Leiba <[email-masked]>
Date: Tue, 10 Mar 2020 16:37:58 -0400

In the spirit of what Warren says below (and an offlist conversation
I've had with him), may I suggest that -- for the moment, at least --
we avoid out-of-hand rejection of his DISCUSS as inadmissible, and
instead have at least some of the discussion, with the goal of finding
whether there's something we can say more or differently in the
document that would allay his concerns?

Warren can always go back to "abstain" after that discussion... or
even "no objection" if the discussion bears fruit.

Barry

---

From: "Martin Thomson" <[email-masked]>
Date: Wed, 11 Mar 2020 15:52:33 +1100

I will try to address Warren's questions here.  Apologies for the length; I promise this is not an amplification attack, I just have limited time to process this.

On the ideological questions, I have no answer.  I value pragmatism too highly.  (Separately, someone also pointed out that GitHub doesn't do DNSSEC, but neither does tools.ietf.org, so maybe that's not a principle we can stand our ground on :)

On Wed, Mar 11, 2020, at 04:45, Warren Kumari via Datatracker wrote:
> This smacks of scope-creep / chairs having control and

I get that this goes a long way into examining the details of the process, likely far more so than our previous documents.  But I hope that the document is clear how that should be consensual: a WG for which the detailed process is not suitable can operate as before.  Indeed, in working groups that follow the more involved processes described here there are a few participants who pay none of the GitHub stuff any mind and that doesn't disadvantage them at all.  It's document editors and chairs who sometimes need to manage any impedance mismatch in that case.

Frankly there are places where I personally have felt the creep as a negative thing.  Part of that is a consequence of finer-grained visibility into what is going on and part of that is in feeling out the process.  I don't always agree with the QUIC chairs about the direction they take on minor issues.  But I don't see that sort of tension as a product of *this* process, but just a natural tension between participants and chairs.

> 1a: [On the implication that GitHub is better]

I see what you mean here, but I don't see how to address that.  If your concern is about the publication of this document being used to bludgeon people into accepting these work practices against their will, I don't know how to further hedge against that (if you have specific suggestions, I'm happy to take those to the working group).  If your concern is that this doesn't fully acknowledge some costs that might be incurred by adopting this path, sure.

> 1b: [On dicing with updates to BCP 9]

I understand the reaction, but I don't agree with the implication regarding BCP 9.

You cited a case that I believe to be benign, in the sense that I believe it to be a restatement.  Would it help to avoid 2119 language in that case?  Do you believe that there are other such cases?

> 2: The focus on GitHub makes my deeply uncomfortable

The reasons for this have been litigated at length and a short synopsis of the conclusions are captured in the draft.  Discomfort is an expected side effect of the consensus process; see your doctor if symptoms persist.

> 3: 
> the issue tracker, and not communicated tp the mailing list

Given how much of the document is dedicated to addressing this risk, I don't know that anything more can be said here.

It is also true that hallway conversations, private chats and email threads, and conference calls are used to reach conclusions.  That is how we make progress on the most difficult issues often.  It might be oft-lamented, but it is effective.

Today, we rely on people catching the worst of that behaviour by reviewing documents, especially at WGLC or IETF LC.  None of that changes.  I'd argue that this approach improves the situation by giving a public venue to those side discussions, both by allowing others to jump in and by recording a transcript of events.

Finally, some of this has to be cultural.  We teach others to respect those not present by asking to take discussions to the mailing list in those cases that might benefit from wider discussion and by proactively doing so ourselves when we recognize the need.

> disenfranchises people who don't use or want to use git.

I should let those people who don't use GitHub speak here about the disenfranchisement point.

I agree with the learning curve thing.  git is truly abominable, but it's easier than learning a new language and it has fairly broad applicability in the industry.

> document is adopted is non-trivial

That's interesting.  Yes, moving is not free, but I have never had serious problems.  I did have a chair decide that a fork was a good plan and that took some unraveling, though the deletion of the repo was probably the biggest problem.  On the other hand, moving has always worked for me, I usually only have to fix a couple of broken links to the old repo (for which I usually am able to use the same script I use to setup the repo in the first place).

> I think a much much better approach would be have people simple keep the

For models that have a lighter touch, that might be OK. There are some issues around ensuring that chairs control who edits documents and so forth though.

> way" (BCP) (nor do I like the WG hosted model).

This last view (in parentheses) was expressed during early working group sessions and the view of the group was that a single org would be too unwieldy.  Even organizations who adopted that model early on, like the W3C, have moved more to independent GitHub orgs.

Thanks for your input.

---

From: "Salz, Rich" <[email-masked]>
Date: Wed, 11 Mar 2020 14:31:28 +0000

>    Today, we rely on people catching the worst of that behaviour by reviewing documents, especially at WGLC or IETF LC.  None of that changes.  I'd argue that this approach improves the situation b…
  
This is a very important point.  The discussion transcript is recorded in the issue thread, they are often relayed/summarized to mailing lists, and often copied into individual git repositories.  I strongly believe that we're more likely to see increased transparency. (I have one datapoint to back that up, when OpenSSL moved from private servers to doing "github first", the change was huge.  Yes, code isn't I-D's, but still...)

    > document is adopted is non-trivial

It's a simple matter of coding as the saying goes. :) The API's are there to make it trivial, it just hasn't been done yet.

    > but I
    
Are we doing that?  I think it's "if you want to do this kind of thing (use github) here's the best way to do it in our experience."

We often say we're not the protocol police.  Nor are we the git cops.

---

From: Alissa Cooper <[email-masked]>
Date: Wed, 11 Mar 2020 15:08:24 -0400

Personally I would rather see this document switch to informational and move forward with publication. I don’t think the label “BCP” makes much of a difference, the point is just to document practices to make it easier for IETF WGs to get their work done. I would be curious what the WG thinks. 

Thanks,
Alissa

> On Mar 10, 2020, at 4:37 PM, Barry Leiba <[email-masked]> wrote:
>

---

From: Warren Kumari <[email-masked]>
Date: Wed, 11 Mar 2020 15:33:27 -0400

On Wed, Mar 11, 2020 at 3:08 PM Alissa Cooper <[email-masked]> wrote:
>
> Personally I would rather see this document switch to informational and move forward with publication.

If this changes from BCP to Informational, I will happily change my
DISCUSS to Abstain (a non-blocking position).

I'd also like to thank Martin and Rich for trying to constructively
address my concerns - I'm sure they dislike trying to address my
DISCUSS at least as much as I dislike holding it...

W

> I don’t think the label “BCP” makes much of a difference, the point is just to document practices to make it easier for IETF WGs to get their work done. I would be curious what the WG thinks.
>
> Thanks,
> Alissa
>
>

---

From: "Salz, Rich" <[email-masked]>
Date: Wed, 11 Mar 2020 19:41:24 +0000

>    Personally I would rather see this document switch to informational and move forward with publication. I don’t think the label “BCP” makes much of a difference, the point is just to document pra…
  
We do think this is the best ways to do things, but if the BCP label has people tied up in knots, it's better to publish than delay and be right.  I can live with informational.

---

From: "Christopher Wood" <[email-masked]>
Date: Wed, 11 Mar 2020 12:52:02 -0700

> DISCUSS to Abstain (a non-blocking position).

This seems like a fine path forward!

> DISCUSS at least as much as I dislike holding it...

Heavy +1 -- thank you both for moving the conversation forward.

Best,
Chris

---

From: Warren Kumari <[email-masked]>
Date: Wed, 11 Mar 2020 15:58:15 -0400

> We do think this is the best ways to do things, but if the BCP label has people tied up in knots, it's better to publish than delay and be right.  I can live with informational.

Thank you -- I would even be OK with just changing to Abstract to be:
"This document describes best practices for Working Groups that choose
to use GitHub for their work."
and leave it as BCP.

Would that work better for everyone? It would be enough for me to no
longer feel that this is saying that WGs using GitHub is a BCP, but
rather that if a WG decided to use GitHub, this is the best way to do
so (I'm still not sure that this really is the best way, but that's
just my opinion, and I'm OK being in the rough)

W

---

From: Joseph Lorenzo Hall <[email-masked]>
Date: Wed, 11 Mar 2020 20:18:13 +0000

I like this solution
________________________________
From: Ietf-and-github <[email-masked]> on behalf of Warren Kumari <[email-masked]>
Sent: Wednesday, March 11, 2020 15:58
To: Salz, Rich <rsalz=[email-masked]>
Cc: [email-masked] <[email-masked]>; Alissa Cooper <[email-masked]>; IESG <[email-masked]>
Subject: Re: [Ietf-and-github] Warren Kumari's Discuss on draft-ietf-git-using-github-05: (with DISCUSS and COMMENT)

W

---

From: Eric Rescorla <[email-masked]>
Date: Wed, 11 Mar 2020 14:28:40 -0700

On Wed, Mar 11, 2020 at 12:59 PM Warren Kumari <[email-masked]> wrote:

> > >    Personally I would rather see this document switch to informational
> and move forward with publication. I don’t think the label “BCP” makes much
> of a difference, the point is just to document practices to make it easier
> for IETF WGs to get their work done. I would be curious what the WG thinks.
> >
> > We do think this is the best ways to do things, but if the BCP label has
> people tied up in knots, it's better to publish than delay and be right.  I
> can live with informational.
>

I don't see a material difference here, so if this resolves your DISCUSS,
let's do it.

-Ekr

---

From: "Martin Thomson" <[email-masked]>
Date: Thu, 12 Mar 2020 10:03:05 +1100

On Thu, Mar 12, 2020, at 06:41, Salz, Rich wrote:
> We do think this is the best ways to do things, but if the BCP label 
> has people tied up in knots, it's better to publish than delay and be 
> right.  I can live with informational.

What I value is getting consensus on some best practices, that I hope will eventually become common.  An informational document achieves that goal as effectively as a BCP.

Hell, if it weren't for the fact that publication as RFC is a codification of community consensus, this entire process would have been unnecessary.  I could have just done more presentations to WG chairs.  But I value that consensus.  Which is why I'm taking the time to deal with objections of the sort that Warren raises.

---

From: "Martin Thomson" <[email-masked]>
Date: Thu, 12 Mar 2020 10:05:56 +1100

> to use GitHub for their work."

I should read all the thread before replying...

https://github.com/ietf-gitwg/using-github/pull/46 makes this change.

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 12 Mar 2020 11:23:05 +1100

> On 12 Mar 2020, at 10:05 am, Martin Thomson <[email-masked]> wrote:
> 

I have some sympathy for Warren's concerns (regardless of the process intricacies).

I didn't review this document closely in LC because my recollection when we started the group, there were numerous reassurances that it was advisory only, not requiring things from groups that didn't want to opt into these processes. The charter seems to support this view (note "that choose to adopt the *practices*", not "Github"):

"""
The GitHub Integration and Tooling (GIT) working group will select a set of such practices and document policies that support those practices. The policies will each detail how work is conducted by working groups that opt to follow the work practice. The goal is to provide both process and tooling support for working groups that choose to adopt the practices.

...

Whether working groups choose to use GitHub or the documented policies to support their work will remain entirely at their discretion.
"""

So this change doesn't go far enough; it needs to say something like:

>  This document describes a set of practices that Working Groups using GitHub can choose to adopt.

Changing the document to Informational would also make me feel _much_ better about it.

With apologies for the late feedback, a few more notes FWIW:

* "Chairs MUST involve Area Directors in any decision to use GitHub for anything more than managing drafts."  This seems onerous; does it mean that I need to consult with the AD to host some tests (e.g., <https://github.com/httpwg/structured-header-tests>), a repository for a wiki (e.g., <https://github.com/httpwg/wiki/wiki>), working group administrivia (<https://github.com/quicwg/wg-materials>), or a translation (<https://github.com/quicwg/zh-translations>)?

* "Maintaining multiple documents in the same repository can add overhead that negatively affects individual documents.  For instance, issues might require additional markings to identify the document that they affect.  Also, because editors all have write access to the repository, managing the set of people with write access to a larger repository is more difficult (Section 3.3)."  This is well-worn territory, but there are also costs associated with having many repositories -- both in terms of WG chair load, and in terms of potential errors (as we're discovering in QUIC).

* "Issues that have reached a resolution that has Working Group consensus MUST NOT be reopened unless new information is presented."  This seems to be pre-emptively establishing both the status of Github issues in the IETF process, and the semantics of their state. 

* "Editors SHOULD create a new Internet-Draft submission two weeks prior to every session..."  How is this requirement specific to Github?

* Generally, there are a lot of RFC2119 terms that seem advisory, not normative. Are they all well-considered? To give one example: "Editors SHOULD make pull requests for all substantial changes rather than committing directly to the "master" branch of the repository." What does it mean to violate that SHOULD?

Cheers,

--
Mark Nottingham   https://www.mnot.net/

---

From: Eric Rescorla <[email-masked]>
Date: Wed, 11 Mar 2020 17:27:33 -0700

On Wed, Mar 11, 2020 at 5:23 PM Mark Nottingham <[email-masked]> wrote:

> I didn't review this document closely in LC because my recollection when
> we started the group, there were numerous reassurances that it was advisory
> only, not requiring things from groups that didn't want to opt into these
> processes. The charter seems to support this view (note "that choose to
> adopt the *practices*", not "Github"):
>
> """
> The GitHub Integration and Tooling (GIT) working group will select a set
> of such practices and document policies that support those practices. The
> policies will each detail how work is conducted by working groups that opt
> to follow the work practice. The goal is to provide both process and
> tooling support for working groups that choose to adopt the practices.
>
> ....
>
> Whether working groups choose to use GitHub or the documented policies to
> support their work will remain entirely at their discretion.
> """
>

I agree with Martin here: the point of having this go through a WG and
consensus is that we think that if you are using Github this is a good set
of practices and that we recommend them in that case. So while it's at
their discretion that doesn't mean we don't have an opinion.

-Ekr

> * "Chairs MUST involve Area Directors in any decision to use GitHub for
> anything more than managing drafts."  This seems onerous; does it mean that
> I need to consult with the AD to host some tests (e.g., <
> https://github.com/httpwg/structured-header-tests>), a repository for a
> wiki (e.g., <https://github.com/httpwg/wiki/wiki>), working group
> administrivia (<https://github.com/quicwg/wg-materials>), or a
> translation (<https://github.com/quicwg/zh-translations>)?
>
> * "Maintaining multiple documents in the same repository can add overhead
> that negatively affects individual documents.  For instance, issues might
> require additional markings to identify the document that they affect.
> Also, because editors all have write access to the repository, managing the
> set of people with write access to a larger repository is more difficult
> (Section 3.3)."  This is well-worn territory, but there are also costs
> associated with having many repositories -- both in terms of WG chair load,
> and in terms of potential errors (as we're discovering in QUIC).
>
> * "Issues that have reached a resolution that has Working Group consensus
> MUST NOT be reopened unless new information is presented."  This seems to
> be pre-emptively establishing both the status of Github issues in the IETF
> process, and the semantics of their state.
>
> * "Editors SHOULD create a new Internet-Draft submission two weeks prior
> to every session..."  How is this requirement specific to Github?
>
> * Generally, there are a lot of RFC2119 terms that seem advisory, not
> normative. Are they all well-considered? To give one example: "Editors
> SHOULD make pull requests for all substantial changes rather than
> committing directly to the "master" branch of the repository." What does it
> mean to violate that SHOULD?
>
> Cheers,
>
>
> >
> >

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 12 Mar 2020 11:39:42 +1100

> On 12 Mar 2020, at 11:27 am, Eric Rescorla <[email-masked]> wrote:
> 
> I agree with Martin here: the point of having this go through a WG and consensus is that we think that if you are using Github this is a good set of practices and that we recommend them in that case. So while it's at their discretion that doesn't mean we don't have an opinion.

Sure. But the document doesn't say it's at their discretion; it says that it's Best Current Practice for any WG that uses GitHub, and asserts a lot of MUSTs about them. The charter language is very specific for a reason; this was discussed in depth, and there were multiple assurances that WGs would "opt in" to this document.

---

From: "Martin Thomson" <[email-masked]>
Date: Thu, 12 Mar 2020 11:44:19 +1100

Hi Mark,

Any input, even late input, is better than nothing.  I appreciate you spending the time.

On Thu, Mar 12, 2020, at 11:23, Mark Nottingham wrote:
> anything more than managing drafts."  This seems onerous; does it mean 
> that I need to consult with the AD to host some tests (e.g., 
> <https://github.com/httpwg/structured-header-tests>), a repository for 
> a wiki (e.g., <https://github.com/httpwg/wiki/wiki>), working group 

Yes, this was not considered in the original drafting.  There is a proposed revision in https://github.com/ietf-gitwg/using-github/commit/e74ba457de2f0843a42c1214bec0033f559f187a

> * "Maintaining multiple documents in the same repository can add 
> overhead that negatively affects individual documents.  For instance, 
> issues might require additional markings to identify the document that 
> they affect.  Also, because editors all have write access to the 
> repository, managing the set of people with write access to a larger 
> repository is more difficult (Section 3.3)."  This is well-worn 
> territory, but there are also costs associated with having many 
> repositories -- both in terms of WG chair load, and in terms of 
> potential errors (as we're discovering in QUIC).

I believe that encouraging the use of separate repos is the consensus outcome of working group discussions.  You were involved.  Suggestions for different wordings are always welcome, of course.

> * "Issues that have reached a resolution that has Working Group 
> consensus MUST NOT be reopened unless new information is presented."  
> This seems to be pre-emptively establishing both the status of Github 
> issues in the IETF process, and the semantics of their state. 

There is a proposed revision in https://github.com/ietf-gitwg/using-github/commit/b872e534db4c885cd3cbfaac64fff7d06d41c5d4 (though Chris later improved the text further, see the PR: https://github.com/ietf-gitwg/using-github/pull/43 for more)

> * "Editors SHOULD create a new Internet-Draft submission two weeks 
> prior to every session..."  How is this requirement specific to Github?

It's a poor restatement of the (lowercase) recommendation that was cited.  I have reworded here: https://github.com/ietf-gitwg/using-github/pull/48

> committing directly to the "master" branch of the repository." What 
> does it mean to violate that SHOULD?

A lot of these have been removed in response to reviews.  Including that example in response to Mirja's review: https://github.com/ietf-gitwg/using-github/pull/45

---

From: Eric Rescorla <[email-masked]>
Date: Wed, 11 Mar 2020 17:48:03 -0700

On Wed, Mar 11, 2020 at 5:39 PM Mark Nottingham <[email-masked]> wrote:

> Sure. But the document doesn't say it's at their discretion; it says that
> it's Best Current Practice for any WG that uses GitHub, and asserts a lot
> of MUSTs about them. The charter language is very specific for a reason;
> this was discussed in depth, and there were multiple assurances that WGs
> would "opt in" to this document.
>

You seem to be complaining about two separate things:

1. That it says it's Best Current Practice
2. That it's not sufficiently clear it's optional.

I think that (2) is implicit in the following text:

   The main purpose of this document is providing guidelines for how
   Working Groups might integrate the capabilities provided by GitHub
   into their processes for developing Internet-Drafts.

However, I wouldn't object to making it clearer. Perhaps: "The choice
of whether to use Github or whether to adopt these practices if they
do is at the discretion of the WG". However, I would be sad to see us
back off the claim that it's best current practice, because, as I
said, that's the point of having a WG.

-Ekr

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 12 Mar 2020 11:52:23 +1100

> On 12 Mar 2020, at 11:48 am, Eric Rescorla <[email-masked]> wrote:
> 
> However, I wouldn't object to making it clearer. Perhaps: "The choice of whether to use Github or whether to adopt these practices if they do is at the discretion of the WG".

That would help a lot, as would further clarification in the abstract (as discussed). 

> However, I would be sad to see us back off the claim that it's best current practice, because, as I said, that's the point of having a WG.

I'm not against it being a BCP with those clarifications -- although it seems like there are continuing questions about what the normative force of a BCP is. Happy to punt those to a later day, however. And I'd hate to make you sad.

Cheers,

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 12 Mar 2020 11:54:02 +1100

All of those changes look much better, thanks.

Regarding the multiple documents issue -- yes, it was indeed discussed. I don't feel strongly about changing the language, unless this document is seen as binding on all WGs that use Github (see rest of discussion).

Cheers,

> On 12 Mar 2020, at 11:44 am, Martin Thomson <[email-masked]> wrote:
> 
> Hi Mark,
>

---

From: Eric Rescorla <[email-masked]>
Date: Wed, 11 Mar 2020 17:56:31 -0700

On Wed, Mar 11, 2020 at 5:52 PM Mark Nottingham <[email-masked]> wrote:

> > However, I wouldn't object to making it clearer. Perhaps: "The choice of
> whether to use Github or whether to adopt these practices if they do is at
> the discretion of the WG".
>
> > However, I would be sad to see us back off the claim that it's best
> current practice, because, as I said, that's the point of having a WG.
>
> I'm not against it being a BCP with those clarifications -- although it
> seems like there are continuing questions about what the normative force of
> a BCP is. Happy to punt those to a later day, however. And I'd hate to make
> you sad.
>

I appreciate that

To be clear, I actually don't care that much about document status: I do
care about the statement that we think they are good.

-Ekr

---

From: "Martin Thomson" <[email-masked]>
Date: Thu, 12 Mar 2020 11:57:05 +1100

> That would help a lot, as would further clarification in the abstract 

I've added that to the corresponding PR: https://github.com/ietf-gitwg/using-github/pull/46

Thanks

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 12 Mar 2020 12:09:32 +1100

That's better, thanks. I'd prefer that the Abstract also be adjusted as discussed, as it can be read to mislead, but can live with just the change below.

Cheers,

> On 12 Mar 2020, at 11:57 am, Martin Thomson <[email-masked]> wrote:
>

---

From: "Salz, Rich" <[email-masked]>
Date: Thu, 12 Mar 2020 12:40:53 +0000

*   I agree with Martin here: the point of having this go through a WG and consensus is that we think that if you are using Github this is a good set of practices and that we recommend them in that case. So while it's at their discretion that doesn't mean we don't have an opinion.

There were also real concrete improvements that came about because of the WG process.  The most notable example is the “light weight” mode, that culminated in Barbara being added as co-author.  No amount of presentations at the wgchairs lunch could have achieved that.

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Thu, 12 Mar 2020 19:40:48 +0000

> There were also real concrete improvements that came about because of the WG process.  The most notable example is the “light weight” mode, that culminated in Barbara being added as co-author.  No…

I just now managed to get through all my emails from yesterday and today and would like to post something quickly before it gets overtaken by others' comments.
First of all, I think Martin is doing a fabulous job and fully support all the changes he's made. If he ever does something I *don't* support, I'll make it known. 
As someone with strong tendencies to pragmatism, I think the most important thing is to get these recommendations out. WGs are using GitHub. Independent of the existence of other git mechanisms (I really like the Atlassian suite of tools, with Jira and Bamboo integration -- but they totally require someone to administer them), GitHub is what many WGs are using (to various degree). Independent of the fact that GitHub only runs on IPv4, WGs are using GitHub. A dogmatic stance of "because GitHub is IPv4-only IETF MUST NOT provide guidance or tools to the WGs that are using it" would be beyond my comprehension. Any suggestion that IETF forbid use of GitHub is untenable, IMO.

Therefore, guidance *for those WGs making use of GitHub* is needed. And that's what this draft provides. I'm not sure how many different ways this draft can say that it isn't requiring or forcing any WG to use GH. And it isn't requiring or forcing those who do use GH in simplistic ways (e.g., just draft authors make use of it and other list participants don't) to institute heavy-handed policies. I use GH with a co-author without WG-chair-blessing in one WG. In a WG I chair, one set of draft authors is using a repository in an account I set up for the WG; no-one else is participating there, and the other draft author chose not to use GH. This is all perfectly ok under the provided guidance.

BTW, I don't (competently) write code. When I was first forced to start using git (for document management, in Broadband Forum), it evoked significantly more terror in me than, say crawling through a cave or rappelling off a 30 m cliff. But it's where things are headed. The more advice and useful info we can provide, the better off everyone will be.

I honestly don't care what label is attached to it. The advice is useful for those using GH. Therefore, I'm confident it will be used.
Barbara