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

["Rob Wilton (rwilton)" <[e-mail]>]

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