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

[Martin Thomson <[e-mail]>]

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 above regarding the comment on document lifecycle, is that just 
> through to RFC editor, or beyond?

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 
> boilerplate. ;-)

Fixed in my copy at Barry's prompting.

>  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)?

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

> - Should IETF github repositories not also have a LICENSE file? E.g. in 
> 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.

>  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.

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 [...]
> 
> - 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>?

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.

>  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.]

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