Draft: draft-ietf-git-using-github

Commentary: See cc
Mailing list commentary: I have reviewed draft - ietf - git - using - github-03 in preparation for IETF last call . The document is almost ready for LC . I have just a couple of substantive questions and suggestions to be answered before initiating the LC . I ’ ve also included some nits that should be resolved together with any last call comments . = = = Substantive comments = = = = = General = = Should there be some words in this document about how research groups might draw inspiration from this document , but that specific guidance for research groups is out of scope ? = = Section 2.1 = = draft - ietf - git - github - wg - configuration settled on the naming convention ietf - wg- so this document needs to be updated to align with that . = = Section 4.2 = = Do you want to say a few words about who determines what constitutes a " substantial " change ( or add a forward reference to Section 5 and provide some uniform statement about it there ) ? For example , might some WGs determine that anything non - editorial is substantial ( also discussed in 5.3.2 ) ? Whose call would that be ? = = Section 4.3 = = Should we see if the secretariat can setup server infrastructure to support github - notify - ml for WGs that want it , and have a process whereby WGs can request support for it ? This would imply changes to draft - ietf - git - github - wg - configuration rather than to this document , but I figured I would ask while I ' m reviewing this . = = Section 10 = = I 'd like to suggest : OLD Maintaining a mirror of a repository that is hosted on GitHub is relatively simple and might be considered as a way to provide a backup for the primary repository . NEW Maintaining a mirror of a repository that is hosted on GitHub is relatively simple and is specified in [ GH - CONFIG ] to provide IETF - hosted backups for WG repositories . = = Nits = = Section 1 : Perhaps you should add a citation to on first use of Github . Section 1.1 : Same comment as above , adding a citation for might be useful for completeness / posterity . Section 1.4 : s / does require / requires/ Section 3 : s / accomplish the Charter / accomplish the charter objectives/ Section 3.1 : s / Working Group Chairs that decide / Working Group Chairs who decide/ Section 3.4 : You might want to clarify what you mean by text - based ( some people might interpret it as documents being submitted in binary or something ... better to be clear ) Section 4.1.2 : " Restrictions on closing issues are generally not advisable until a document has reached a certain degree of maturity . " This is a little vague . Perhaps you mean " Restrictions on who can close an issue " ? Section 4.2 : s / how they manage changes./how they manage changes amongst themselves./ Section 6 : s / MAY request the creation of an Internet - Draft at any time / MAY request a revision of an Internet - Draft being managed on Github at any time/ Section 7 : s / GitHub , mailing lists , and in - person meetings / GitHub , mailing lists , interim meetings , and IETF meetings/ Section 7 : s / explicitly identify / identify/ Section 8 : s / For a document that use / For a document that uses/ Section 9 : s / that raises what a new issue / that raises a new issue/ Thanks ,
Paragraph (version B):
Although similar, guidance for IRTF Research Groups is out of scope
for this document.  However, such groups may draw inspiration for
GitHub use from the contents herein.
Paragraph (version A):
Organizations are a way of forming groups of contributors on GitHub.
Each Working Group SHOULD create a new organization for the Working
Group.  A Working Group organization SHOULD be named consistently so
that it can be found.  For instance, the name could be ietf-<wgname>
or ietf-<wgname>-wg.
Paragraph (version B):
Organizations are a way of forming groups of contributors on GitHub.
Each Working Group SHOULD create a new organization for the Working
Group.  A Working Group organization SHOULD be named consistently so
that it can be found.  For instance, the name could be ietf-
wg-<wgname>, as recommended in GH-CONFIG.
Paragraph (version A):
Editors SHOULD make pull requests for all substantial changes rather
than committing directly to the "master" branch of the repository.  A
pull request creates an artifact that records the reasons for changes
and provides other contributors with an opportunity to review the
change.  Pull requests that address substantive issues SHOULD mention
the issue they address in the opening comment.
Paragraph (version B):
Editors SHOULD make pull requests for all substantial changes rather
than committing directly to the "master" branch of the repository.
See mature-documents for discussion on what constitutes a substantial
change.  A pull request creates an artifact that records the reasons
for changes and provides other contributors with an opportunity to
review the change.  Pull requests that address substantive issues
SHOULD mention the issue they address in the opening comment.
Paragraph (version A):
Widespread use of git reduces the exposure to a system failure
because the primary repository is replicated in multiple locations.
This includes hosted web pages; the content of web pages is
maintained as a branch in the main repository.  Maintaining a mirror
of a repository that is hosted on GitHub is relatively simple and
might be considered as a way to provide a backup for the primary
repository.
Paragraph (version B):
Widespread use of git reduces the exposure to a system failure
because the primary repository is replicated in multiple locations.
This includes hosted web pages; the content of web pages is
maintained as a branch in the main repository.  As specified in GH-
CONFIG, maintaining a mirror of a repository hosted on GitHub
provides IETF-hosted backups for WG repositories.