Subject: [Ietf-and-github] Comments on draft-thomson-github-bcp-00

From: Brian E Carpenter <[email-masked]>
Date: Mon, 27 Feb 2017 16:07:44 +1300

Hi,

First, thanks for starting this.

I really think it's a mistake to aim immediately at BCP. We're learning.
Time enough later for firm rules, beyond the IPR text we already got from
the IESG.

>    The words "MUST", "MUST NOT", "SHOULD", and "MAY" are used in this
>    document.  It's not shouting; 

Yes it is, IMHO, while we are learning.

> 4.1.  Issues
...
>    Working group chairs MUST decide how the GitHub issue tracker are
>    used.  Use of the issue tracker could be limited to recording the
>    existence of issues, or it might be used as the venue for substantial
>    technical discussion between contributors.

No it might not; that would be a direct violation of IETF process
since it isn't on the WG mailing list. (Unless you want all issues to
be automatically cc'ed to the list, but we know how painful that can be.)
So if issues are discussed on the GitHub tracker, they have exactly the
same status as design team discussions: the result must be referred back
to the WG as a whole, i.e. the mailing list.

> 4.2.  Pull Requests
> 
>    Pull requests are the GitHub feature that allow users to request
>    changes to a repository.  A user does not need to have write access
>    to a repository to create a pull request.  A user can create a
>    "fork", or copy, of any public repository.

Forks in IETF documents are evil, and when they happen, they can lead
to significant annoyance, including lawyers in at least one case some
years ago. So while there might be some utility in this approach
between cooperating editors, the idea of having arbitrary WG participants
making their own forks and pull requests seems terrible to me.

>    Editors SHOULD make pull requests for all substantial changes rather
>    than commiting directly to the "master" branch of the repository.

It baffles me why that could ever be a good idea. There's no analogy
with why you might need this approach for open-source software. If they
are the document editors, they should just edit the document.

> Critically, using
> pull requests creates a record of actions taken.

So does an ordinary commit.

>    For significant changes, leaving a pull request open until discussion
>    of the issue within the working group concludes allows the pull
>    request to track the discussion and properly capture the outcome of
>    discussions.

Still makes no sense to me. The WG should debate the issue before the text
gets updated. And the proper venue for that discussion is the WG mailing
list. Forking the document would make the WG discussion confusing.

> 4.2.2.  Merging Pull Requests
> 
>    Working groups MUST determine who is permitted to merge pull
>    requests.  

They do that by apointing document editors.

>    Document editors SHOULD be permitted to merge pull
>    requests at their discretion. 

There's no "should" about it - it's their job.

Bottom line: IMNSHO, using pull requests at all is probably a mistake.

> 6.  Internet-Drafts
> 
>    During the development of a document, individual revisions of a
>    document can be built and formally submitted as an Internet-Draft.

To be clear, state that this is with version number += 1. Since it's
bog standard IETF process, I'm not sure why it's even mentioned.

>    This creates a stable snapshot and makes the content of the in-
>    progress document available to a wider audience.
> 
>    Editors SHOULD endeavour to create a new Internet-Draft submission
>    two weeks prior to every session 

s/endeavour to//

This is the editors' main duty, after all.

Don't legislate the deadline; WG Chairs often set a specific deadline.
So s/two weeks prior to/in good time for/

Regards
    Brian

---

From: Eric Rescorla <[email-masked]>
Date: Sun, 26 Feb 2017 19:56:39 -0800

Hi Brian,

I think a number of your comments reflect a misunderstanding of how people
in practice work with Git.

> making their own forks and pull requests seems terrible to me.

Because Git is a DVCS, the basic idiom for submitting a proposed change
to a repo is:

- Fork the repo
- Make a branch for your change
- Submit a PR that asks to merge your branch into the main repo's master.

While this is formally a fork, it's not a fork in the conventional sense of
an alternative document that has its own lifecycle, it's just the version
control mechanic you use to propose changes. One of the main virtues
of working with Github is that it allows people to submit the precise
change they are requesting and the editor can just merge it in. Forks
and PRs are the way that Github does that. The alternative is either
abandoning precise changes or making everyone able to write to
the repo. Neither is desirable.

> are the document editors, they should just edit the document.

There actually is a very concrete analogy to Open Source software,
which is that in many projects even committers are required to have
their changes reviewed, so they create PRs for other committers to
review and merge.

> So does an ordinary commit.

I would urge you to take a look at the way we have used PRs in the WGs
that use Github already. In general, even when the editor proposes
something, they do a PR and then there are comments on the PR
which eventually contains several commits. The PR is the construct
which ties them together.

> list. Forking the document would make the WG discussion confusing.

Again, I think you're misunderstanding the role of the PR here, which is
that it's a specific proposal for how the text ought to be updated. And in
practice, we haven't found that it makes the WG discussion confusing.

You are of course free to believe this, but given that PRs are one of the
primary benefits of Github, and this is the workflow the rest of the world
is used to, this seems an awful lot like saying you don't think we should
use Github. You are of course, also free to believe this, but given that
this document is targeted at WGs which have decided to use Github,
that doesn't seem like a very useful piece of comment.

-Ekr

---

From: Brian E Carpenter <[email-masked]>
Date: Mon, 27 Feb 2017 17:14:01 +1300

Eric,

I'm not arguing about the technical description below. My concern is
that it doesn't merge seamlessly with current WG process; in fact it
creates a two-speed process where people using git are doing things
on the fly and the other WG members will see stop-motion video.

So it works for a design team. I just don't think it works for
a complete WG. If it was described as a design team tool, I'd be
much happier.

I must admit that none of the repos I've used for drafts have
used pull requests, to my knowledge. So far we've used conventional
methods for proposed changes.

Regards
   Brian

---

From: Eric Rescorla <[email-masked]>
Date: Sun, 26 Feb 2017 20:26:54 -0800

On Sun, Feb 26, 2017 at 8:14 PM, Brian E Carpenter <
[email-masked]> wrote:

> that it doesn't merge seamlessly with current WG process;

Yes. Part of the point of using Github is to have a process which is faster
and more efficient, as well as to bring in people who already have
experience with this model. To be clear, I believe that the use of Github
in this way is entirely consistent with RFC 2418, it's simply not what the
conventional practice pre-Github was.

> a complete WG.

I'm not sure what to tell you here. We've got a lot of experience with using
Github in WGs now (HTTP, TLS, ACME, RTCWEB), so we don't really need
to theorize about what the impact of these practices is. In my opinion
(and I suspect that of most of the active participants of these WGs),
it's a pretty big improvement. As I said, you're free to think otherwise,
but the target of this effort is -- or at least should be -- those who want
to use these practices for their WG, and primaily need a template to start
from.

If it was described as a design team tool, I'd be
> much happier.

That's not how we use it.

-Ekr

---

From: Martin J. Dürst <[email-masked]>
Date: Mon, 27 Feb 2017 13:59:24 +0900

Hello Brian, Eric,

>> years ago.

> control mechanic you use to propose changes.

For people with experience with github, that's well understood. But 
because this document will be read by a wide range of people, it should 
make clear that this is only 'technically' a fork, not intended to be an 
actual forking in the process.

[This is doubly important because github makes the first 
fork-branch-PullRequest cycle very easy, but any subsequent 
synchronization of the personal fork with the upstream master (of the 
WG) is extremely non-obvious. Even employees of github have admitted 
that to me; they have even told me that internally, they have something 
like a "catch up" button, and they have plans to make that available in 
the public version. Alas, that was last September, but I have yet to see 
such a button.]

> One of the main virtues
> change they are requesting and the editor can just merge it in.

Yes indeed. That's a great improvement over the old "OLD" / "NEW" style 
of change requests or any other way of trying to express changes in 
words. In most cases, it's easier for the proposer (because there's no 
need to talk about an edit, you just do it) and for the recipient (if 
things look good, you just push a button. It also matches the "please 
send actual text" maxim used in the IETF.

Regards,   Martin.

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 27 Feb 2017 06:55:07 +0100

> That's not how we use it.

Interesting discussion.

To me, the fact that there are different points of view is an expression of the fact that IETF WGs do differ.  A lot.

Some WGs use the github process to coordinate work across the entire WG.  Some might want to use it mainly to coordinate work among the authors of a document, with good transparency to the WG (and possibly the occasional PR coming from outside the group of authors).

It is probably a good idea to find names for these different approaches, this simplification of the discourse on how a specific WG wants to work could be an important purpose of the present document.

(The choice between one of these approaches may be to a per-document granularity, not homogeneous per-WG.  For WGs that have a single deliverable, that may not make a difference.)

Grüße, Carsten

---

From: Melinda Shore <[email-masked]>
Date: Mon, 27 Feb 2017 09:59:41 -0900

I think this is a somewhat weird discussion, because as
I read it the draft is not prescriptive.  That is to say,
it's not telling working groups to use github but rather
to give them some guidance for when they do.  I personally
feel rather strongly about working groups and other IETF
teams using the tools that work best for them as long as
they're free, open, and available to all participants, and
(in some sense) auditable.

Guidance for those who choose github seems reasonable to me.

Melinda

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 28 Feb 2017 08:17:50 +1300

> (The choice between one of these approaches may be to a per-document granularity, not homogeneous per-WG.  For WGs that have a single deliverable, that may not make a difference.)

I fully agree with Carsten. Different teams may have different preferences on how
to use the toolset.

On 28/02/2017 07:59, Melinda Shore wrote:> I think this is a somewhat weird discussion, because as
> to give them some guidance for when they do. 

That's really the problem with it being phrased as a draft BCP.
I really think it should be phrased as suggestions and advice. 

> I personally

Absolutely. And there are at least two models: lightweight,
where GitHub is simply used as a basic repository, and the all-in
model that Eric has described.

My concern about the all-in model is that it makes the WG almost
inaccessible to people who are not accomplished GitHub users.
I assume that means most people.

    Brian

---

From: Alia Atlas <[email-masked]>
Date: Mon, 27 Feb 2017 14:27:13 -0500

Brian,

On Mon, Feb 27, 2017 at 2:17 PM, Brian E Carpenter <
[email-masked]> wrote:

> > To me, the fact that there are different points of view is an expression
> of the fact that IETF WGs do differ.  A lot.
> >
> > Some WGs use the github process to coordinate work across the entire
> WG.  Some might want to use it mainly to coordinate work among the authors
> of a document, with good transparency to the WG (and possibly the
> occasional PR coming from outside the group of authors).
> >
> > It is probably a good idea to find names for these different approaches,
> this simplification of the discourse on how a specific WG wants to work
> could be an important purpose of the present document.
> >
> > (The choice between one of these approaches may be to a per-document
> granularity, not homogeneous per-WG.  For WGs that have a single
> deliverable, that may not make a difference.)
>

 I believe there are aspects that need to be BCP - such as how to tell
others
that the WG is using GitHub or GitLab and where, how the GitHub
notifications
can be transparently sent to the mailing list, and so on.

Other parts are advice, obviously.

> I assume that means most people.

I have poked a little at GitHub; it is not necessary to be very
accomplished to
see what is going on and participate.  I am concerned about transparency
and fate-sharing.

Regards,
Alia

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

---

From: Eric Rescorla <[email-masked]>
Date: Mon, 27 Feb 2017 12:34:07 -0800

> I assume that means most people.
I don't believe that this is true. Do you have some evidence for this from
WGs which have used this model, or is this just a theoretical concern?

-Ekr

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 28 Feb 2017 12:42:02 +1300

> WGs which have used this model, or is this just a theoretical concern?

No, it's a thought experiment. I thought about running the
current discussions on rfc2460bis and rfc4291bis this way
and concluded that it would be virtually impossible.

You've persuaded me that a tight-knit WG can certainly work
this way.

    Brian