Subject: [Ietf-and-github] RobWilton review of draft-ietf-git-using-github-05

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Tue, 10 Mar 2020 16:23:01 +0000

Hi,

I have reviewed this document as an incoming Ops/Mgmt AD.

Overall, I am a strong proponent of this work, and I'm of the opinion that leveraging tools such as github can and will greatly help IETF.

I do have some comments/questions/suggestions on the document:

Main comments:

  1.  My main concerns with IETF's use of github are:
     *   Losing ownership control of the repository.
     *   Inexperienced users accidentally committing private SSH keys, or otherwise leaking access.
     *   Loosing access to historical data if a new better tool comes along, e.g. if we want to migrate repositories.

I think that (a) can be mitigated by adding extra organization owners, beyond just the responsible AD.  E.g., the github-config suggests also adding the Secretariat.  We should be consistent here, and I think that we should decide whether having just the AD and Secretariat is sufficient.  Would it also make sense to mandate the 2FA must be used by all members? If so, then this can be enforced in the organization settings.

The second point can probably be mitigated in a couple of ways:
- Educating users: to ensure that they don't accidentally commit credentials to the repo, to enable 2FA, and to generate account recovery passwords.  Should this document cover this.
- Perhaps having a gitignore file that filters out standard ssh key names?

The third point I know least about.  I understand that the plan is that IETF will backup the repos + issues + wikipages?  Hopefully the issues/wikipages are backed up in a format that a script could be written to update into future tools if required.

  1.  It was slightly unclear to me exactly what the full lifecycle of managing documents in github is meant to be.  E.g. is it only for drafts up to the point that they are published as RFCs, or is there an expectation that repositories could exist for longer than that, e.g. for tracking issues, future revisions, or errata.  I think that there are some source of truth considerations here that perhaps need to be carefully documented in the repo readme.  E.g. folks reading the doc on github are not getting the formal RFC, no notification about errata, etc.

I also have some other comments on particular sections:

1.3: Other Services
   "This document concentrates primarily on GitHub as it has a large and
   active community of contributors."

- Presumably another reason why github was chosen wasn't just because of large/active contributors, but also because various IETF WGs are actively making use of github for managing documents - I know that we are.

1.4: Document Goals
   "This document only aims to address use of GitHub in developing
   Documents"

- As above regarding the comment on document lifecycle, is that just through to RFC editor, or beyond?

1.5: Notational Conventions
   "The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are
   used in this document.  It's not shouting; when they are capitalized,
   they have the special meaning defined in BCP 14 [RFC2119] [RFC8174]."

- Nice, but this doesn't appear to quite follow the normal RFC8174 boilerplate. ;-)

2.1: Organizations

   Each organization requires owners.  The owner team for a Working
   Group repository MUST include responsible Area Directors.

- Should this also include IETF Secretariat (i.e. for consistency with the github configuration draft)?

2.2: Communicating Policies

- Should IETF github repositories not also have a LICENSE file? E.g. in alignment with the Note-well?

3: Deciding to Use GitHub

   Chairs MUST involve Area Directors in any decision to use GitHub for
   anything more than managing drafts.

- Is it clear what "draft" means here?  Would "Internet-Draft" be better?  It might be worth checking other usage of draft in the document.

3.1: What to Use GitHub For
- Looking at the first paragraph in section 3, and the second paragraph in section 3.1, it is slightly unclear to me whether it is the WG or WG chairs who choose whether github should be used by the WG.
   "Features that the Working Group does not rely upon SHOULD be made
   available to document editors."
   "Chairs SHOULD periodically consult with
   document editors to ensure that policies are effective."
- I suggest "should" rather than SHOULD for both of these.
   "A document editor can still use GitHub independently for documents
   that they edit, even if the Working Group does not expressly choose
   to use GitHub.  Any such public repository MUST follow the IETF Note
   Well and bear notices; see Section 2.2.  This recognizes that editors
   have traditionally chosen their own methods for managing the
   documents they edit but preserves the need for contributors to
   understand their obligations with respect to IETF processes."
- I agree with the sentiment here, but I think that there perhaps should be some more rules:
     - Is the assumption that this repository is not under ietf-wg-<name>?
     - If not, perhaps this document should recommended a statement that the repository is for use by the authors and does not necessarily reflect the procedures defined in draft-ietf-git-using-github, and that the WG work formally happens on the WG email alias.

3.3: Editors and Contributors
   Working Groups MAY create a team for regular contributors that is
   only given read access to a repository.  This does not confer
   additional privileges on these contributors, it instead allows for
   issues and pull requests to be assigned to those people.  This can be
   used to manage the assignment of editorial or review tasks to
   individuals outside of the editor team.

   - If these are public repositories then I would thought that everyone has read access anyway, and can have issues assigned to them, etc.

6: Internet-Draft Publication

   Revisions used to generate documents that are submitted as Internet-
   Drafts SHOULD be tagged in repositories to provide a record of
   submissions.

   - Perhaps suggest the format of the tag.  I.e. the tag should just be the name/version of the draft being published.  [Ideally, longer term we would have tooling to help with this.]

Thanks,
Rob

---

From: "Martin Thomson" <[email-masked]>
Date: Wed, 11 Mar 2020 17:18:09 +1100

Hi Rob,

Thanks for reviewing this and your thoughts here.

I've built you a PR here: https://github.com/ietf-gitwg/using-github/pull/44
Some of your comments are already addressed by other PRs though: https://github.com/ietf-gitwg/using-github/pulls

On Wed, Mar 11, 2020, at 03:23, Rob Wilton (rwilton) wrote:
> I think that (a) can be mitigated by adding extra organization owners, 
> beyond just the responsible AD. E.g., the github-config suggests also 
> adding the Secretariat. We should be consistent here, and I think that 
> we should decide whether having just the AD and Secretariat is 
> sufficient. Would it also make sense to mandate the 2FA must be used by 
> all members? If so, then this can be enforced in the organization 
> settings.

The first part of this probably applies to the -config draft mostly.  My understanding is that it isn't more definitive in order to allow chairs some flexibility in how they operate.  I personally think that having a backup is sensible.  At the same time, having a single account with access to many repositories is a bit scary.

The 2FA thing is good advice, but I would again leave that to individual groups.  But not because it isn't good advice, more because the state of the art for login is likely to change.  WebAuthn is even better than 2FA, but that is used even less today.  In 2 years maybe that won't be true.

In the group I chair (I can't see 2FA status for groups I don't administer), 4/8 contributors have 2FA, which would seem to make a mandate difficult to require.  That said, if we are even remotely worried about phishing, a recommendation is good.

> - Perhaps having a gitignore file that filters out standard ssh key names?

That might be too much detail for an RFC.

See also https://datatracker.ietf.org/doc/draft-nottingham-how-did-that-get-into-the-repo/

(I'll take a PR on my tools if you have something concrete, but I don't know how to target SSH keys with a .gitignore; I guess I could just add id_ed25519 and id_rsa, but that isn't enough, surely.  Or maybe that is enough...)

> The third point I know least about. I understand that the plan is that 
> IETF will backup the repos + issues + wikipages? Hopefully the 
> issues/wikipages are backed up in a format that a script could be 
> written to update into future tools if required.

This is work in progress.  Robert Sparks has a draft statement of work and I expect that to go out to bid soon.

>  1.  It was slightly unclear to me exactly what the full lifecycle of 
> managing documents in github is meant to be. E.g. is it only for drafts 
> up to the point that they are published as RFCs, or is there an 
> expectation that repositories could exist for longer than that, e.g. 
> for tracking issues, future revisions, or errata. I think that there 
> are some source of truth considerations here that perhaps need to be 
> carefully documented in the repo readme. E.g. folks reading the doc on 
> github are not getting the formal RFC, no notification about errata, 
> etc.

This is focused on the production process.  I don't think that we do a great job of closing the loop.  Some work with the RPC was done, but no one left that process very happy and it hasn't been taken up again.

>From my perspective, I see this as iterative.  We need to have better processes for dealing with maintenance of work that goes for publication, but a number of factors tend to interfere.  Part of that is our insistence on an archival format, part of it is the length of time that publication takes, part of that is that we just don't have this built into the culture always.

Maybe the new IESG can continue to work on this problem.  I know that the current and previous IESGs have tried a number of approaches.

> - Presumably another reason why github was chosen wasn't just because 
> of large/active contributors, but also because various IETF WGs are 
> actively making use of github for managing documents – I know that we 
> are.

Yes.  I consider those people already within the IETF to be a large part of that community.

>  “This document only aims to address use of GitHub in developing
>  Documents”
> 

As it says, this is "developing documents".  More to be done, I guess.

> - Nice, but this doesn't appear to quite follow the normal RFC8174 

Fixed in my copy at Barry's prompting.

> the github configuration draft)?

Yes.  I've added them at a "SHOULD" level.  I think that's consistent with the other draft (which avoids icky 2119 words).

> alignment with the Note-well?

Yes.  My tools provide a default one that says "See the guidelines for contributions."

https://github.com/martinthomson/i-d-template/blob/master/template/LICENSE.md

As this document relates to contributions, and the -configuration draft already mentions the LICENSE file, I think we're covered adequately without getting into that.

> - Is it clear what "draft" means here? Would “Internet-Draft” be 
> better? It might be worth checking other usage of draft in the document.

Please see https://github.com/ietf-gitwg/using-github/pull/43 which includes text that I think greatly improves this.

> - I suggest “should” rather than SHOULD for both of these.

I agree.  None of this needs normative force.

>  “A document editor can still use GitHub independently for documents [...]
> 

No.  Though that is a discussion to have between chairs and editors.  Some groups are comfortable with individual submissions living in the WG org, others are concerned about what that might imply.

>  - If not, perhaps this document should recommended a statement that 
> the repository is for use by the authors and does not necessarily 
> reflect the procedures defined in draft-ietf-git-using-github, and that 
> the WG work formally happens on the WG email alias.

I don't think we can reasonably expect to levy requirements on work that happens essentially outside of these processes, except to the extent that we insist on the notice.  Even that is stretching it a little to my mind.

>  - If these are public repositories then I would thought that everyone 
> has read access anyway, and can have issues assigned to them, etc.

You need to be part of the organization before you can be assigned work.  I think that avoids GitHub from dealing with a specific class of spam.

>  - Perhaps suggest the format of the tag. I.e. the tag should just be 
> the name/version of the draft being published. [Ideally, longer term we 
> would have tooling to help with this.]

We do indeed have tooling and documentation, but I don't want to prescribe a specific format in a document like this (I was in the rough regarding the org naming convention).  Convention would seem to suffice here.

See https://github.com/martinthomson/i-d-template/blob/master/doc/SUBMITTING.md

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Fri, 13 Mar 2020 12:03:30 +0000

Hi Martin,

Apologies for the delayed response.  Further comments inline ...

> -----Original Message-----
> From: Martin Thomson <[email-masked]>
> Sent: 11 March 2020 06:18
> To: Rob Wilton (rwilton) <[email-masked]>; The IESG <[email-masked]>;
> [email-masked]
> Cc: [email-masked]; [email-masked]; Christopher Wood
> <[email-masked]>
> Subject: Re: RobWilton review of draft-ietf-git-using-github-05
> 
> Hi Rob,
> 
> Some of your comments are already addressed by other PRs though:
> https://github.com/ietf-gitwg/using-github/pulls
> 
> > sufficient. Would it also make sense to mandate the 2FA must be used
> > by all members? If so, then this can be enforced in the organization
> > settings.
> 
> The first part of this probably applies to the -config draft mostly.  My
> understanding is that it isn't more definitive in order to allow chairs
> some flexibility in how they operate.
[RW] 

Okay, I was sort reading the split between the two documents as specification vs implementation.

  I personally think that having a
> backup is sensible.  At the same time, having a single account with access
> to many repositories is a bit scary.
[RW] 
Hum yes, maybe having the Secretariat on all WGs is not a good choice.  Perhaps we should say that all ADs for the area should be owners rather than just the responsible AD, and there must always be a minimum of 2 owners?  So, for the general area perhaps it would be the AD and the Secretariat?

Obviously this would need to be aligned with the config draft.

> 
> The 2FA thing is good advice, but I would again leave that to individual
> groups.  But not because it isn't good advice, more because the state of
> the art for login is likely to change.  WebAuthn is even better than 2FA,
> but that is used even less today.  In 2 years maybe that won't be true.
[RW]
Perhaps the security section could mention some of the risks (e.g. losing data, losing control, having nefarious changes injected into a draft), and suggest that this could be mitigated by using good authentication of github accounts, such as 2FA or WebAuthn.

> 
> In the group I chair (I can't see 2FA status for groups I don't
> administer), 4/8 contributors have 2FA, which would seem to make a mandate
> difficult to require.  That said, if we are even remotely worried about
> phishing, a recommendation is good.

True, but this is BCP/guidance rather than mandating.

My concern is less about losing the data (since that is being backed up), but more about losing control of an account/organization that is under the IETF's name.  I'm not sure what policies Github has for recovering an account/organisation that one loses control over, but I'm sure it would be hassle, and embarrassing. 

> (I'll take a PR on my tools if you have something concrete, but I don't
> know how to target SSH keys with a .gitignore; I guess I could just add
> id_ed25519 and id_rsa, but that isn't enough, surely.  Or maybe that is
> enough...)
[RW] 

No concrete proposal, but perhaps even a simple .gitignore might be better than nothing.

FWIW: It is this sort of article that I am concerned about:
https://nakedsecurity.sophos.com/2019/03/25/thousands-of-coders-are-leaving-their-crown-jewels-exposed-on-github/

Some of the contributors to IETF will be quite new to git/github etc, so really it is about warning them about stuff they should be careful to avoid.  Even a sentence or two in the security considerations might help.

> > managing documents in github is meant to be. E.g. is it only for
> > drafts up to the point that they are published as RFCs, or is there an
> This is focused on the production process.  I don't think that we do a
> great job of closing the loop.  Some work with the RPC was done, but no
> one left that process very happy and it hasn't been taken up again.
> 
> From my perspective, I see this as iterative.  We need to have better
> processes for dealing with maintenance of work that goes for publication,
> but a number of factors tend to interfere.  Part of that is our insistence
> on an archival format, part of it is the length of time that publication
> takes, part of that is that we just don't have this built into the culture
> always.
[RW] 

Yes, I agree that an iterative approach is good.

I think that it might be helpful early in the document for it to state that the scope focus of the document is for the progression of draft documents up to the RFC Editor stage.

> 
> Maybe the new IESG can continue to work on this problem.  I know that the
> current and previous IESGs have tried a number of approaches.
[RW] 

As the incoming Mgmt AD, I care about YANG models, and this is obviously one of the areas where tooling helps.  Some authors already have (slightly hairy) Makefiles that automate various stages of the work, others do everything manually.  But I have an interest in working out how IETF can better manage/develop/refine YANG models so this is something I hope to pursue, time permitting of course.

Off topic, I think that a VSCode language server protocol for developing drafts could be interesting, not least because it has the capability of working with any editor that supports LSPs.

> Yes.  I've added them at a "SHOULD" level.  I think that's consistent with
> the other draft (which avoids icky 2119 words).
[RW] 
Okay.  See above, I now wonder whether having other ADs might be better, due to your comment of giving ownership of all WG orgs to one person.

> As this document relates to contributions, and the -configuration draft
> already mentions the LICENSE file, I think we're covered adequately
> without getting into that.
[RW] 
Okay.

> Please see https://github.com/ietf-gitwg/using-github/pull/43 which
> includes text that I think greatly improves this.
> 
> No.  Though that is a discussion to have between chairs and editors.  Some
> groups are comfortable with individual submissions living in the WG org,
> others are concerned about what that might imply.
[RW] 

I agree not to specify this.

> > reflect the procedures defined in draft-ietf-git-using-github, and
> > that the WG work formally happens on the WG email alias.
> 
> I don't think we can reasonably expect to levy requirements on work that
> happens essentially outside of these processes, except to the extent that
> we insist on the notice.  Even that is stretching it a little to my mind.
[RW] 
Perhaps.

FWIW, it is this sort of issue that I am concerned about:
https://networkengineering.stackexchange.com/questions/44010/is-ipv10-a-joke-or-a-serious-rfc-draft

> You need to be part of the organization before you can be assigned work.
> I think that avoids GitHub from dealing with a specific class of spam.
[RW] 
Ah, okay.

> > the name/version of the draft being published. [Ideally, longer term
> > we would have tooling to help with this.]
> 
> We do indeed have tooling and documentation, but I don't want to prescribe
> a specific format in a document like this (I was in the rough regarding
> the org naming convention).  Convention would seem to suffice here.
[RW] 
Okay.

Thanks,
Rob

---

From: Rob Sayre <[email-masked]>
Date: Fri, 13 Mar 2020 22:25:04 +1000

On Fri, Mar 13, 2020 at 10:03 PM Rob Wilton (rwilton) <rwilton=
[email-masked]> wrote:

>
> My concern is less about losing the data (since that is being backed up),
> but more about losing control of an account/organization that is under the
> IETF's name.  I'm not sure what policies Github has for recovering an
> account/organisation that one loses control over, but I'm sure it would be
> hassle, and embarrassing.
>

How is this different from any other system the IETF might use?

thanks,
Rob

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Fri, 13 Mar 2020 17:57:08 +0000

Hi Rob,

From: Ietf-and-github <[email-masked]> On Behalf Of Rob Sayre
Sent: 13 March 2020 12:25
To: Rob Wilton (rwilton) <rwilton=[email-masked]>
Cc: [email-masked]; [email-masked]; [email-masked]; The IESG <[email-masked]>; Martin Thomson <[email-masked]>; Christopher Wood <[email-masked]>
Subject: Re: [Ietf-and-github] RobWilton review of draft-ietf-git-using-github-05

On Fri, Mar 13, 2020 at 10:03 PM Rob Wilton (rwilton) <rwilton=[email-masked]<mailto:[email-masked]>> wrote:

I’m not that familiar with all the IETF infrastructure or services that are used:

  *   If IETF is hosting stuff in the cloud, then I would imagine that relatively few folks have the owner/admin authorizations and they should already know to look after them carefully.
  *   For stuff being physically hosted by IETF then I presume that an admin could always disconnect them from the Internet, turn off the power, wipe the disk, etc.
  *   For other accounts, I suspect losing credentials is probably less impactful, but I don’t know what these services are.

In the github case, there are a few differences:

  *   The ADs and 150+ WG chairs may be less familiar about github and the security considerations – they may think that setting up 2FA isn’t worth the hassle.
  *   Over time it is plausible that github may host lots of IETF docs/drafts, and hence those documents may turn up more frequently in web searches.  If a prominent draft is in an account that IETF doesn’t control, then that draft could be modified in ways that cause problems and confusion.
  *   I don’t know how easy it is to get back control of a github account once you have lost it.  E.g. from https://help.github.com/en/github/authenticating-to-github/recovering-your-account-if-you-lose-your-2fa-credentials:

Warning: For security reasons, GitHub Support may not be able to restore access to accounts with two-factor authentication enabled if you lose your two-factor authentication credentials or lose access to your account recovery methods.

Thanks,
Rob

thanks,
Rob

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 16 Mar 2020 15:12:26 +1100

On Fri, Mar 13, 2020, at 23:03, Rob Wilton (rwilton) wrote:
> Hum yes, maybe having the Secretariat on all WGs is not a good choice.  
> Perhaps we should say that all ADs for the area should be owners rather 
> than just the responsible AD, and there must always be a minimum of 2 
> owners?  So, for the general area perhaps it would be the AD and the 
> Secretariat?
> 

I will raise the question with the WG, as it is not limited to this draft.  The -configuration draft has a broader net that includes the responsible AD, the ADs for the area, and the secretariat.

> [RW]
> My concern is less about losing the data (since that is being backed 
> up), but more about losing control of an account/organization that is 
> under the IETF's name.  I'm not sure what policies Github has for 
> recovering an account/organisation that one loses control over, but I'm 
> sure it would be hassle, and embarrassing. 

I'm sure that the process is torturous.  I tagged some text on to other changes I'm making.  See https://github.com/ietf-gitwg/using-github/pull/52/commits/302feb524c457f10a3fea21dcee140bd5dc6218e

> Some of the contributors to IETF will be quite new to git/github etc, 
> so really it is about warning them about stuff they should be careful 
> to avoid.  Even a sentence or two in the security considerations might 
> help.

I think that this is a question of scope.  Personally, I think that's going a little outside the remit of the draft.  And I'd rather attack this particular problem with tools.

> https://networkengineering.stackexchange.com/questions/44010/is-ipv10-a-joke-or-a-serious-rfc-draft

Ah, that old problem. :/

I don't think that we can help with that, other than avoiding paving the path to having something look official.  We've talked about having tools like xml2rfc produce different styling for individual drafts than is used for presenting "official" content on IETF-controlled servers.  That might help, though things progress very slowly on this front.

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 16 Mar 2020 11:49:25 +0000

Hi Martin,

> Sent: 16 March 2020 04:12
> > > backup is sensible.  At the same time, having a single account with
> > > access to many repositories is a bit scary.
> > [RW]
> > Perhaps we should say that all ADs for the area should be owners
> > rather than just the responsible AD, and there must always be a
> > minimum of 2 owners?  So, for the general area perhaps it would be the
> > AD and the Secretariat?
> >
> I will raise the question with the WG, as it is not limited to this draft.
> The -configuration draft has a broader net that includes the responsible
> AD, the ADs for the area, and the secretariat.
[RW] 
Thanks.

> > recovering an account/organisation that one loses control over, but
> > I'm sure it would be hassle, and embarrassing.
> 
> I'm sure that the process is torturous.  I tagged some text on to other
> changes I'm making.  See https://github.com/ietf-gitwg/using-
> github/pull/52/commits/302feb524c457f10a3fea21dcee140bd5dc6218e
[RW] 

This looks along the right lines to me.  I would suggest adding "users" to the list of folks who should use best security practices, but happy to leave this to your discretion.

> > https://nakedsecurity.sophos.com/2019/03/25/thousands-of-coders-are-le
> > aving-their-crown-jewels-exposed-on-github/
> >
> I think that this is a question of scope.  Personally, I think that's
> going a little outside the remit of the draft.  And I'd rather attack this
> particular problem with tools.
[RW] 

I agree, that tooling is the best solution to this.

I think that tooling, in addition to the paragraph that you linked to above, is enough for me.

> I don't think that we can help with that, other than avoiding paving the
> path to having something look official.  We've talked about having tools
> like xml2rfc produce different styling for individual drafts than is used
> for presenting "official" content on IETF-controlled servers.  That might
> help, though things progress very slowly on this front.
[RW] 

I agree.

Thanks for incorporating my review comments.

Regards,
Rob