Subject: [Ietf-and-github] Roll call for WGs using GitHub

From: "Paul Hoffman" <[email-masked]>
Date: Wed, 15 Mar 2017 10:41:29 -0700

In preparation for the BoF, I'd like to get a list of WGs using GitHub. 
I'll put these in the BoF slides for future reference. Can at least one 
person from each WG what is the style of GitHub use in the WG? Some 
reasonable responses are:

- GitHub is used for a few docs, based on author preferences
- GitHub is used for most or all docs
- issue tracking only, pull requests are rare
- issue tracking and pull requests are common
- all significant doc changes happen by pull request
- issues from the mailing list are turned into GitHub issues
- some issues are tracked on the mailing list, others on GitHub

Prose is welcome.

--Paul Hoffman

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 16 Mar 2017 07:47:14 +1300

> - GitHub is used for a few docs, based on author preferences

afaik, neither issue tracking nor pull requests are used; I think
all the usage is as a simple depository. And the WG Chairs have not
taken up the idea of a GitHub organiztion for the WG.

    Brian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 15 Mar 2017 20:12:31 +0100

Most of the WGs in the constrained node/network (“IoT”) cluster are somewhere between

> - GitHub is used for a few docs, based on author preferences

and

> - GitHub is used for most or all docs

To wit:

https://github.com/lwig-wg
https://github.com/6lo
https://github.com/core-wg
https://github.com/cbor-wg *)?
https://github.com/cose-wg *)
https://github.com/lp-wan *)

But in most of these WGs the styles are different from document to document; only the ones marked with a star are more consistent (some of these WGs are very new).
(We also used to have some documents that lived in the personal repos of authors.)

> - issue tracking only, pull requests are rare

but some are

> - all significant doc changes happen by pull request

by now.

But apart from those most religiously handled drafts, we still have a bit of a mishmash between

> - issues from the mailing list are turned into GitHub issues

and

> - some issues are tracked on the mailing list, others on GitHub

Grüße, Carsten

---

From: "Eggert, Lars" <[email-masked]>
Date: Wed, 15 Mar 2017 19:23:50 +0000

QUIC: everything happens on GitHub, and if it didn't originate their, it's being moved and tracked there

> On 2017-3-15, at 18:41, Paul Hoffman <[email-masked]> wrote:
> 
> In preparation for the BoF, I'd like to get a list of WGs using GitHub. I'll put these in the BoF slides for future reference. Can at least one person from each WG what is the style of GitHub use in the WG? Some reasonable responses are:
> 
> _______________________________________________
> Ietf-and-github mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-and-github

---

From: Martin Thomson <[email-masked]>
Date: Thu, 16 Mar 2017 16:25:09 +1100

Based on participation only, others may correct these.

HTTPBIS - all working group drafts are in a single repo (this is not
working out great) and all issues are tracked there; discussion is on
github; materials like agendas and meeting arrangements are on github
too

TLS - some, but not all drafts are there.  TLS 1.3 uses issues and PRs
extensively, other drafts less so.

RTCWEB - it varies, but most docs are on github

WEBPUSH - drafts and issues on github, discussion on the list

ACME - drafts and issues on github, discussion on the list

TRANS - appear to have a draft on github and issues in trac (shudder)

ICE - I'm not paying much attention there, but they seem to use github a little

MMUSIC - some individuals are using github, but the working group doesn't

On 16 March 2017 at 04:41, Paul Hoffman <[email-masked]> wrote:
> In preparation for the BoF, I'd like to get a list of WGs using GitHub. I'll
> put these in the BoF slides for future reference. Can at least one person
> from each WG what is the style of GitHub use in the WG? Some reasonable
> responses are:
>

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 16 Mar 2017 16:49:35 +1100

> On 16 Mar 2017, at 4:25 pm, Martin Thomson <[email-masked]> wrote:
> 
> working out great

yes, we know you have an axe to grind...

> ) and all issues are tracked there; discussion is on

Also WG home page -- <https://httpwg.github.io/>.

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

---

From: Martin Thomson <[email-masked]>
Date: Thu, 16 Mar 2017 16:56:18 +1100

> yes, we know you have an axe to grind...

I have many axes.

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 16 Mar 2017 07:30:02 +0100

Not an answer to the question, but Mark’s mention of the HTTPBIS home page makes me think of what may be another interesting data point:

Friday last week, we had another joint meeting between T2TRG and OCF, a prominent IoT standards organization that has been rather good in picking up and making good use of IETF standards.  A perennial issue is how we can make sure that information flows freely between IETF/IRTF and OCF.  

One observation in the room was that github repositories and their issue tracking are perceived as quite accessible by OCF people.  So we took it as an item for potential improvement to make sure these are documented and structured in such a way that they indeed can be used well by organizations outside the IETF/IRTF.

(In keeping with the original question: T2TRG uses github extensively, not just for drafts, but also for meeting materials.)

Grüße, Carsten

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 17 Mar 2017 03:20:08 +1300

So could somebody with experience set out the pros and cons of
(a single repo per WG) vs (an 'organization' with a repo per draft)?

Regards
   Brian

On 16/03/2017 18:49, Mark Nottingham wrote:
> .

---

From: Niels ten Oever <[email-masked]>
Date: Thu, 16 Mar 2017 18:08:33 +0100

HRPC - all documents (incl agendas, presentations, etc) on Github in repo of one of the co-chairs. Discussion on the list, no single place where issues are being tracked.
https://github.com/nllz/IRTF-HRPC/

-- 

Niels ten Oever
Head of Digital

Article 19
www.article19.org

PGP fingerprint	   2458 0B70 5C4A FD8A 9488  
                   643A 0ED8 3F3A 468A C8B3

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 17 Mar 2017 09:11:01 +1100

From an end user perspective, having a single-repo-per-draft is preferable; it means you can easily subscribe to updates for just that draft, and don't have extraneous notifications, etc. The repo itself has less information it in as well (naturally), meaning there's less overhead for clones, etc.

However, creating a repo-per-draft has more administrative overhead. Martin's template repo takes a fair amount of pain out of it, but making sure that things like README, CONTRIBUTING, e-mail notifications to a list, permissions, etc. etc. are set up correctly is not trivial. 

Personally, I'm less concerned about the amount of work than I am about the risk of getting something wrong on some repo and not noticing.

Having said that, I think if we were starting HTTPbis from scratch right now, we'd do a repo-per-draft.

One caveat -- I think there's agreement that in at least one situation, more than one repo-per-draft is preferable. That's when there is a set of highly interrelated drafts that are likely to share issues, and possibly have text migrate between them. We consciously made this decision for the QUIC drafts.

Cheers,

> On 17 Mar 2017, at 1:20 am, Brian E Carpenter <[email-masked]> wrote:
>

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 17 Mar 2017 09:18:59 +1100

> On 17 Mar 2017, at 9:11 am, Mark Nottingham <[email-masked]> wrote:
> 
> more than one repo-per-draft is preferable

... draft-per-repo. More coffee.

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 16 Mar 2017 23:35:32 +0100

+1 for all of the below.

One repo per draft, all of which are in a per-WG organization, is the default model for the groups I’m chairing/advising on this.  (Yes, Martin’s template helps, but I get at least one detail wrong each time I set one up.  Takes about 30 min per repo; could be much faster with some more tooling.)

We tried multiple drafts per repo for CoRE's COMI cluster (interrelated drafts again).  Kind of worked, but maybe our drafts weren’t that much interrelated.
A multi-draft repo may also have a very large team so it becomes harder to know who should be doing what.

One repo per draft probably also is more accessible for external observers.

My most recent PR for Lars’ original draft about github said:

+For most repos, a CI (continuous integration) process is set up that
+generates a readable editor's copy (in HTML form) as well as a diff
+from the most recent submitted version (tools TXT diff), linked from
+the README; both have turned out to be very valuable.  (Unfortunately, the
+travis-based CI process is somewhat brittle, so there is an
+appreciable failure rate.)

The github.io page resulting from the CI is less confusing for a single-draft repo.

(As discussed, github-savvy authors sometimes get lazy pushing drafts into I-Ds again.  This may lead to extended work happening on github only.  Not good.  The tools TXT diff is really useful as long as it does not have to explain multiple reorganizations of the document.)

We also have a few drafts in individual’s github accounts.  This is much less accessible.
I generally favor moving drafts into the WG organization even *before* they become adopted WG drafts.  That may be slightly confusing for outsiders (might get the idea something is adopted that isn’t), but gets people primed on the issues/PR process even before adoption.

Grüße, Carsten

> On 16 Mar 2017, at 23:11, Mark Nottingham <[email-masked]> wrote:
>

---

From: Patrick McManus <[email-masked]>
Date: Fri, 17 Mar 2017 09:42:16 -0400

> The github.io page resulting from the CI is less confusing for a

In my opinion that's more of a mixed bag than anything else. It hasn't been
mentioned here that having a single source to look at for all the current
work is very valuable for someone getting up to speed and those that don't
want to miss something. this is just an indirection problem of course and
with enough tooling you can have both (separate repos and an automated wg
wide dashboard)- but I haven't seen that done..

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 17 Mar 2017 16:09:22 +0100

> It hasn't been mentioned here that having a single source to look at for all the current work is very valuable for someone getting up to speed and those that don't want to miss something. this is just an indirection problem of course and with enough tooling you can have both (separate repos and an automated wg wide dashboard)- but I haven't seen that done.. 

For me, tools.ietf.org/wg/core has been a very useful dashboard.

It would be nice if we could rid this of replaced drafts.

It would also be nice if the chairs could annotate drafts with their github existence.

Grüße, Carsten

---

From: "Eggert, Lars" <[email-masked]>
Date: Sun, 19 Mar 2017 12:29:51 +0000

> It would also be nice if the chairs could annotate drafts with their github existence.

This sounds like a nice codesprint project.

Lars

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 19 Mar 2017 14:23:57 +0100

> On 19 Mar 2017, at 13:29, Eggert, Lars <[email-masked]> wrote:
> 

Can we codesprint on tools.ietf.org?
So far, code sprints have focused on datatracker, I believe.

Grüße, Carsten

---

From: Melinda Shore <[email-masked]>
Date: Sun, 19 Mar 2017 10:32:32 -0800

> TRANS - appear to have a draft on github and issues in trac (shudder)

To clarify, authors have a draft in github - we're good with
authors/editors using whatever tools they find most effective
and aren't going to mandate draft tool use one way or another.

The issues are in trac because it was important, given a
highly factionalized working group participant base, to have
the issue tracker on a neutral, IETF-owned and managed platform.
I think that regardless of whatever else is used, there's a
lot of process value in having good IETF-managed tools available,
and I'd love it if we could get a git service (including ticketing
and their wiki) up on IETF resources.  But trac is what we've got
so trac is what we use.

I think the goal here is to give people the tools to be effective
rather than having them be controlled by their tools.

Melinda

---

From: "Eggert, Lars" <[email-masked]>
Date: Mon, 20 Mar 2017 09:34:21 +0000

> So far, code sprints have focused on datatracker, I believe.

My brain read datatracker when you wrote tools :-) But I think having this information in the datartacker would be a good thing too, and then tools can pick it up from there.

Lars

---

From: Martin Thomson <[email-masked]>
Date: Tue, 21 Mar 2017 09:39:56 +1100

I forgot the groups I chair.

GEOJSON uses github for issues and drafts. The community used github before
they came to the IETF and so much of the discussion is there.

CAPPORT has no working group documents, but I anticipate setting up an
organization soon. We haven't discussed work mode yet.

---

From: Benjamin Kaduk <[email-masked]>
Date: Sun, 26 Mar 2017 12:29:48 -0500

We are trying out something of an experiment for kitten, related to
our abandonment of the formal "WGLC" period for reviews.

Instead, the chairs will be able to declare consensus after a
document has received "sufficient review" (vaguely defined), so
we're going to try using a github page to track what reviews a
document has received.  That will also give us guidance on who to
pester in order to get additional (re)reviews in order to be able to
move a document forward.

The current version looks like:
https://github.com/kittenwg/draft-ietf-kitten-krb-service-discovery
but we'd of course welcome feedback and/or suggestions.

-Ben