Subject: [Ietf-and-github] Tracking drafts

From: "Joel M. Halpern" <[email-masked]>
Date: Sat, 1 Feb 2020 16:32:12 -0500

One of the things I do in order to find out about work outside of WGs I 
am involved in is that I read the internet-draft announcements.

Mostly, I am happy to get updates there when new versions of drafts are 
sufficiently stable to be worth checking.  So intermediate minor updates 
only being made to the github is not a problem.

But it struck me that if early versions of drafts are only on github, 
and discussed on the WG list, this makes it much harder for me (and 
others who are trying to track work outside their center of attention) 
to know about the work.

I am not sure what the right answer is.  It seems that it would help if 
the guidelines encouraged people to post I-Ds as early as practical.

Yours,
Joel

---

From: Brian E Carpenter <[email-masked]>
Date: Sun, 2 Feb 2020 16:25:16 +1300

> the guidelines encouraged people to post I-Ds as early as practical.

I'd be shocked if that wasn't the case. Otherwise we will get people
posting pre-cooked drafts and blocking discussion by saying it's too late,
we decided that on github.

This is quite similar to the dilemma of when a design team should open
up its thinking to the WG. Too soon is boring for everybody, too late
damages the open process.

    Brian

---

From: "Joel M. Halpern" <[email-masked]>
Date: Sun, 2 Feb 2020 00:25:21 -0500

I do not see a note giving this advice in the draft that is currently up 
for publication.  I hope I am merely missing something.

Yours,
Joel

---

From: "Salz, Rich" <[email-masked]>
Date: Sun, 2 Feb 2020 16:06:27 +0000

Do we have written advice on when a design group should put its work up?

Why do you think this is different, other than being a more open design group?

---

From: "Joel M. Halpern" <[email-masked]>
Date: Sun, 2 Feb 2020 12:05:55 -0500

There is a similarity.  I wish there were an easy way to know what 
design teams are being spawned in working groups that I am not 
following.  But I do not know a sensible way to do that.

Currently, I can generally learn of new work because I-Ds are posted. 
In fact, we frequently tell people to post an I-D for their ideas. 
However, I am starting to see folks sending notices of I-Ds that are 
purely in github repositories.  This means that there is no I-D 
announcement.  I am not asking to prohibit that.  But I am asking for 
help so that those of us who are trying to look broadly have some 
assistance in doing so.

Yours,
Joel

---

From: "Joel M. Halpern" <[email-masked]>
Date: Sun, 2 Feb 2020 12:08:50 -0500

Thinking about how I would put the advice, something along the lines of 
"if you are willing to call WG attention to your draft, please post the 
first (then current) draft as an I-D so other folks will also know about 
it."

Yours,
Joel

---

From: "Salz, Rich" <[email-masked]>
Date: Sun, 2 Feb 2020 17:30:04 +0000

Consistent naming, such as ietf-wg-XXXXX as recommended by this WG, might help a bit.
  
    In fact, we frequently tell people to post an I-D for their ideas. 
    However, I am starting to see folks sending notices of I-Ds that are 
    purely in github repositories.

That's not an I-D.  It's a draft.  Ignore it until it becomes an I-D if you want.

---

From: Brian E Carpenter <[email-masked]>
Date: Mon, 3 Feb 2020 08:30:35 +1300

> Do we have written advice on when a design group should put its work up?

Good question. I don't think we do. https://tools.ietf.org/html/rfc2418#section-6.5
just says "The output of a design team is always subject to approval, rejection or
modification by the WG as a whole." And indeed, the question of when a design team
should expose its output to the WG has always been a bit unclear. Something like
"When you have something worth saying to the WG, say it as an I-D" perhaps. 
 
> Why do you think this is different, other than being a more open design group?

I don't think it is. On the contrary, I think github is an excellent tool for
design teams to use; much better than private email.

I think that Joel's point applies more generally, not just to github.

Regards
    Brian

---

From: Fred Baker <[email-masked]>
Date: Sun, 2 Feb 2020 11:48:31 -0800

> And indeed, the question of when a design team

I agree, but I think I might say it a little differently. The point isn’t “we’re done”; the point is “we need the comments of the working group, which might be that we’re done”.

So the time to file the draft is when all known viewpoints have been addressed, and the document is in readable form. The draft might contain “TBD” sections, or questions. It is, if you will, a request for comments, and a viewpoint that may evoke dispute or commentary, but is designed to bring the group a step closer to consensus on a problem.

---

From: "Joel M. Halpern" <[email-masked]>
Date: Sun, 2 Feb 2020 15:08:42 -0500

Actually, I would hope that folks post drafts well before they think 
they are "done".  The reason for my comment is that with folks pointing 
to github more often, I think it is important to emphasis the 
helpfulness of posting that initial draft.

Yours,
Joel

On 2/2/2020 2:48 PM, Fred Baker wrote:
> _______________________________________________
> Ietf-and-github mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-and-github
>

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 03 Feb 2020 08:20:16 +0100

> I think that Joel's point applies more generally, not just to github.

This is, I think, a key point.

https://ietf-gitwg.github.io/using-github/draft-ietf-git-using-github.html#name-internet-draft-publication might be expanded to recommend publication of drafts at other times, but I have two reasons - on top of the above - that we might not:

* This is a document about *working group* procedures.  If we get into individual draft management, that's scope creep.

* I have found that the "link to a Google doc or GitHub repo" pattern routinely results in a request for someone to post a draft.  To my mind, that has been sufficient thus far.

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 4 Feb 2020 11:09:23 +1300

> * This is a document about *working group* procedures.  If we get into individual draft management, that's scope creep.

Fair enough. However, I think it is worth making the point somewhere that there is an analogy between a subset of participants who use a repo and a subset of participants that work as a design team, so the RFC2418 provisions for design teams should apply.

The more general question (when should a design team or github clique post a draft) seems more like a topic for gendispatch.

    Brian

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Thu, 6 Feb 2020 11:38:17 -0600

FWIW,

On Mon, Feb 3, 2020 at 4:09 PM Brian E Carpenter <
[email-masked]> wrote:

> https://ietf-gitwg.github.io/using-github/draft-ietf-git-using-github.html#name-internet-draft-publication
> might be expanded to recommend publication of drafts at other times, but I
> have two reasons - on top of the above - that we might not:
> >
> > * This is a document about *working group* procedures.  If we get into
> individual draft management, that's scope creep.
>
> Fair enough. However, I think it is worth making the point somewhere that
> there is an analogy between a subset of participants who use a repo and a
> subset of participants that work as a design team, so the RFC2418
> provisions for design teams should apply.
>
> The more general question (when should a design team or github clique post
> a draft) seems more like a topic for gendispatch.
>

I agree with Martin that saying more than this is scope creep, even if it's
useful to chop off the creepy parts and take them to gendispatch.

I think it IS fair to say "people working on an early version of a draft in
Github is the equivalent of a design team working on an early version of a
draft using private e-mail, so the usual working group practices and
cautions for design teams apply to Github as well", or something like that.

Best,

Spencer

>     Brian
>
> >
> > * I have found that the "link to a Google doc or GitHub repo" pattern
> routinely results in a request for someone to post a draft.  To my mind,
> that has been sufficient thus far.
> >

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 11 Feb 2020 08:16:32 +1100

On Fri, Feb 7, 2020, at 04:38, Spencer Dawkins at IETF wrote:
> On Mon, Feb 3, 2020 at 4:09 PM Brian E Carpenter  <[email-masked]> wrote:
[...]
> I think it IS fair to say "people working on an early version of a 
> draft in Github is the equivalent of a design team working on an early 
> version of a draft using private e-mail, so the usual working group 
> practices and cautions for design teams apply to Github as well", or 
> something like that. 

https://github.com/ietf-gitwg/using-github/pull/42 is a somewhat minimalist take on this.  There was already a point made with respect to difficult issues, but it's worth pulling up to the lead-in material.

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 11 Feb 2020 11:20:37 +1300

> https://github.com/ietf-gitwg/using-github/pull/42 is a somewhat minimalist take on this.  There was already a point made with respect to difficult issues, but it's worth pulling up to the lead-in…

Looks good to me, thanks.

    Brian

---

From: Rob Sayre <[email-masked]>
Date: Wed, 12 Feb 2020 00:12:54 -0800

On Mon, Feb 10, 2020 at 1:17 PM Martin Thomson <[email-masked]> wrote:

>
> https://github.com/ietf-gitwg/using-github/pull/42 is a somewhat
> minimalist take on this.  There was already a point made with respect to
> difficult issues, but it's worth pulling up to the lead-in material.
>

This patch is well-meaning, but it does not meet the IESG guidelines for
design teams. For example, it enables completely closed groups that throw
their output over the fence into Github. The edit does say "open
participation", but that's not really defined. In particular, the IESG
design team recommendations require named members, and periodic reports.

thanks,
Rob

---

From: "Salz, Rich" <[email-masked]>
Date: Wed, 12 Feb 2020 15:37:11 +0000

*   This patch is well-meaning, but it does not meet the IESG guidelines for design teams. For example, it enables completely closed groups that throw their output over the fence into Github. The edit does say "open participation", but that's not really defined. In particular, the IESG design team recommendations require named members, and periodic reports.

Perhaps adding “(such as making the repo public)” fixes that.

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Wed, 12 Feb 2020 16:57:16 +0000

Since it costs money to make a GitHub repo private, and there is no suggestion that IETF spend money on official WG GitHub repos, I’m curious how such an addition to the text would make any difference.
If people want to set up a private and paid-for repo to stage changes before putting them in an IETF repo, I think it will be hard to stop them and I’m not convinced they would be doing something wrong.
Or am I an anomaly and misbehaving when I communicate with fellow draft authors off-list using direct email? Is *all* communication between draft authors and design team members required to be public? This is news to me.
I have to say I’m very much opposed to over-specifying and over-constraining how WGs use GitHub in order to prevent hypothetical problems. I’d prefer to get additional and more widespread experience to see what problems really occur and doing a bis or update to deal with those, rather than try to imagine and deal with all sorts of hypothetical problems now.
Barbara

---

From: Rob Sayre <[email-masked]>
Date: Wed, 12 Feb 2020 09:52:19 -0800

On Wed, Feb 12, 2020 at 8:57 AM STARK, BARBARA H <[email-masked]> wrote:

> 
>
>    - This patch is well-meaning, but it does not meet the IESG guidelines
>    for design teams. For example, it enables completely closed groups that
>    throw their output over the fence into Github. The edit does say "open
> Since it costs money to make a GitHub repo private, and there is no
> suggestion that IETF spend money on official WG GitHub repos, I’m curious
> how such an addition to the text would make any difference.
> If people want to set up a private and paid-for repo to stage changes
> before putting them in an IETF repo, I think it will be hard to stop them
> and I’m not convinced they would be doing something wrong.
> Or am I an anomaly and misbehaving when I communicate with fellow draft
> authors off-list using direct email? Is *all* communication between draft
> authors and design team members required to be public? This is news to me.
>

Of course that kind of stuff happens, and it's ok. But if it's long-term
and coordinated, it should be transparent. This means the participants
should be known, which is where this edit seems a bit off imho. In this
sense, a design team is more tightly defined than a mailing list or a
github repo, even if less open.

thanks,
Rob

---

From: "Martin Thomson" <[email-masked]>
Date: Thu, 13 Feb 2020 08:14:20 +1100

On Thu, Feb 13, 2020, at 03:57, STARK, BARBARA H wrote:
> Since it costs money to make a GitHub repo private [...]

GitHub recently made private repositories available to all users, albeit with restrictions that might make them awkward to use for design teams.  And a good number of people I work with pay GitHub for a "pro" account, so finding a sponsor likely wouldn't be that difficult.  So finding a private repositories might not be that hard.

So I'm inclined to take Rich's suggestion here, if only because it clarifies intent better.  I've updated the PR.

> before putting them in an IETF repo, I think it will be hard to stop 
> them and I’m not convinced they would be doing something wrong. 
> authors off-list using direct email? Is *all* communication between 
> draft authors and design team members required to be public? This is 
> news to me. 

This is fine.  But the purpose of the document is to address Working Group procedures.  We can't stop private communication and nor should we, but under the auspices of "official business", it is good to keep formal deliberations public.

This wouldn't stop a Working Group from forming a design team that uses a private repository.  But then it wouldn't be following the guidance in this document.  That too is fine by existing rules, even if I would personally prefer to retain the accountability conferred by keeping discussion public.

> I have to say I’m very much opposed to over-specifying and 
> over-constraining how WGs use GitHub in order to prevent hypothetical 
> problems. 

I don't see this as specifying anything, just explaining the perspective the draft adopts and how that fits into the existing formalisms.

---

From: Rob Sayre <[email-masked]>
Date: Thu, 13 Feb 2020 03:06:40 -0800

On Wed, Feb 12, 2020 at 1:14 PM Martin Thomson <[email-masked]> wrote:

>
> So I'm inclined to take Rich's suggestion here, if only because it
> clarifies intent better.  I've updated the PR.
>

Well, I think I've spied a problem here. I have nothing against open Github
repos, but they are not equivalent to design teams.

thanks,
Rob

---

From: "Salz, Rich" <[email-masked]>
Date: Thu, 13 Feb 2020 14:33:14 +0000

>Well, I think I've spied a problem here. I have nothing against open Github repos, but they are not equivalent to design teams.

Right, one is about people, the other is a repository.

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Thu, 13 Feb 2020 15:35:10 -0600

Hi, Rob,

On Thu, Feb 13, 2020 at 5:06 AM Rob Sayre <[email-masked]> wrote:

> Well, I think I've spied a problem here. I have nothing against open
> Github repos, but they are not equivalent to design teams.
>

I agree. I think the point is, from the point of view of an IETF working
group, a design team, and a bunch of people working in a Github repo (who
could, of course, ALSO be a design team), are treated pretty much the same
when they contribute their output to the working group (via e-mail, of
course). The output might be great, middle of the road, or horrible, but
neither's output is privileged among other people contributing to the
working group - it's fair game for the working group, with no
assumption that the working group is bound by decisions that were made in
Github, or in the design team.

At least, I think that's the point we're trying to make here.

Best,

Spencer

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 14 Feb 2020 08:45:16 +1100

On Fri, Feb 14, 2020, at 08:35, Spencer Dawkins at IETF wrote:
> I agree. I think the point is, from the point of view of an IETF 
> working group, a design team, and a bunch of people working in a Github 
> repo (who could, of course, ALSO be a design team), are treated pretty 
> much the same when they contribute their output to the working group 
> (via e-mail, of course). The output might be great, middle of the road, 
> or horrible, but neither's output is privileged among other people 
> contributing to the working group - it's fair game for the working 
> group, with no assumption that the working group is bound by decisions 
> that were made in Github, or in the design team. 

Thanks Spencer, I've added that as a note, copying from 2418:

+A choice to use GitHub is regarded as equivalent to the formation of a design
+team (see Section 6.5 of {{!RFC2418}}) provided that the work uses a public
+repository.  That is, the output of any activity using GitHub needs to be taken
+to the Working Group mailing list and subject to approval, rejection or
+modification by the Working Group as with any other input.

---

From: "Salz, Rich" <[email-masked]>
Date: Thu, 13 Feb 2020 21:47:04 +0000

Oxford comma after rejection.  Otherwise LGTM.

---

From: Rob Sayre <[email-masked]>
Date: Thu, 13 Feb 2020 13:50:00 -0800

+A choice to use GitHub is [similar] to the formation of a design...

Would prefer this small edit ^^, but I think the text is fine, and I don't
object to it as is.

thanks,
Rob

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 14 Feb 2020 09:02:50 +1100

On Fri, Feb 14, 2020, at 08:45, Martin Thomson wrote:
> +A choice to use GitHub is similar to the formation of a design
> +to the Working Group mailing list and subject to approval, rejection, or

Updated as per Rich and Rob.  Thanks for the prompt review.

---

From: Eric Rescorla <[email-masked]>
Date: Fri, 14 Feb 2020 05:31:51 -0800

I can understand the motivation for this, but I think it just confuses
things as-is.

In general, we've long had a tradition that editors have a lot of
discretion in how they prepare documents, with the assumption being that if
they make changes without WG consensus, then those changes need to be taken
to the WG. And of course the editor could have private conversations about
the document, or even public ones outside the WG. So in some respects GH is
like that. In any case, I think the Design Team analogy is confusing. I
would simply say:

Work done in GitHub -- even when there is extensive discussion -- has no
special status. That is, the output of any activity using GitHub needs to
be taken into the Working Group
and subject to approval, rejection or modification by the Working Group as
with any other input.

Note that I have removed the "mailing list" text as well, because 2418 is
actually somewhat vague on exactly how work done offline in drafts is to be
brought to the WG. The key point is that this is like any such input.

-Ekr

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Fri, 14 Feb 2020 13:36:17 +0000

+1
I agree with everything Eric said here.
Barbara

From: Ietf-and-github <[email-masked]> On Behalf Of Eric Rescorla

I can understand the motivation for this, but I think it just confuses things as-is.

In general, we've long had a tradition that editors have a lot of discretion in how they prepare documents, with the assumption being that if they make changes without WG consensus, then those changes need to be taken to the WG. And of course the editor could have private conversations about the document, or even public ones outside the WG. So in some respects GH is like that. In any case, I think the Design Team analogy is confusing. I would simply say:

Work done in GitHub -- even when there is extensive discussion -- has no special status. That is, the output of any activity using GitHub needs to be taken into the Working Group
and subject to approval, rejection or modification by the Working Group as with any other input.

Note that I have removed the "mailing list" text as well, because 2418 is actually somewhat vague on exactly how work done offline in drafts is to be brought to the WG. The key point is that this is like any such input.

-Ekr

On Thu, Feb 13, 2020 at 2:03 PM Martin Thomson <[email-masked]<mailto:[email-masked]>> wrote:

---

From: Rob Sayre <[email-masked]>
Date: Fri, 14 Feb 2020 15:02:15 -0800

On Fri, Feb 14, 2020 at 5:32 AM Eric Rescorla <[email-masked]> wrote:

> discretion in how they prepare documents,
>

For most documents, it probably doesn't matter. There's a spectrum from:

Editors discuss among themselves and others, then submit drafts.
Design Team with closed membership
Design Team with some open aspects, etc.
Mailing List / Github with active design discussion in public

When a WG document has several implementations, and has been long-running,
it seems that the WG should make this call. Otherwise, implementations both
public and private can fall behind or diverge if the editors aren't
transparent about their progress (or lack thereof). This is particularly
true if an early draft is widely deployed (there might be implementations
the editors are not aware of).

For example, I'd expect HTTP WG edits to be pretty open and regular for the
core documents, given the number of implementations.

Note also the IESG statement on this:
https://www.ietf.org/about/groups/iesg/statements/design-teams/

I prefer the text we have, but the edit below is also true.

thanks,
Rob

---

From: "Martin Thomson" <[email-masked]>
Date: Sat, 15 Feb 2020 20:32:14 +1100

This seems like a good way to say what I intended.  I will take this edit unless there are strong reasons not to.  That is, we concentrate on the end result (the WG considers input) and not whether this is a design team or editors exercising discretion.

PR updated.

On Sat, Feb 15, 2020, at 00:31, Eric Rescorla wrote:
> discretion in how they prepare documents, with the assumption being 
> that if they make changes without WG consensus, then those changes need 
> to be taken to the WG. And of course the editor could have private 
> conversations about the document, or even public ones outside the WG. 
> So in some respects GH is like that. In any case, I think the Design 
> Team analogy is confusing.

---

From: "Salz, Rich" <[email-masked]>
Date: Sat, 15 Feb 2020 15:25:25 +0000

I agree.

GitHub is a repo; a design team is people.  I'm fine with this text.

On 2/15/20, 4:32 AM, "Martin Thomson" <[email-masked]> wrote:

    PR updated.

---

From: "Christopher Wood" <[email-masked]>
Date: Mon, 17 Feb 2020 07:43:54 -0800

Thanks, all, for discussing this issue and landing some clarification text!

On Sat, Feb 15, 2020, at 7:25 AM, Salz, Rich wrote:
>     This seems like a good way to say what I intended.  I will take 
> this edit unless there are strong reasons not to.  That is, we 
> concentrate on the end result (the WG considers input) and not whether 
> this is a design team or editors exercising discretion.
>     
>     PR updated.
>