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 A):
The IETF has an open and transparent process for developing
standards.  The use of GitHub or similar tools, when used as part of
this process, can have several objectives.  GitHub provides tools
that can be helpful in editing documents.  Use of this service has
been found to reduce the time that Working Groups need to produce
documents and to improve the quality of the final result.
Paragraph (version B):
The IETF has an open and transparent process for developing
standards.  The use of GitHub [3] or similar tools, when used as part
of this process, can have several objectives.  GitHub provides tools
that can be helpful in editing documents.  Use of this service has
been found to reduce the time that Working Groups need to produce
documents and to improve the quality of the final result.
Paragraph (version A):
Git is a distributed version control system that can operate without
a central service.  Each instance of a repository contains a number
of revisions.  Each revision stores the complete state of a set of
files.  Users are able to create new revisions in their copy of a
repository and share revisions between copies of repositories.
Paragraph (version A):
GitHub is a service operated at https://github.com/ [3].  GitHub
provides centralized storage for git repositories.  GitHub is freely
accessible on the open Internet, albeit currently only via IPv4.
Paragraph (version B):
Git [4] is a distributed version control system that can operate
without a central service.  Each instance of a repository contains a
number of revisions.  Each revision stores the complete state of a
set of files.  Users are able to create new revisions in their copy
of a repository and share revisions between copies of repositories.
Paragraph (version B):
GitHub is a service operated at https://github.com/ [5].  GitHub
provides centralized storage for git repositories.  GitHub is freely
accessible on the open Internet, albeit currently only via IPv4.
Paragraph (version A):
Git is not the only version control system available, nor is GitHub
the only possible choice for hosting.  There are other services that
host revision control repositories and provide similar additional
features to GitHub.  For instance, BitBucket [4] and GitLab [5]
provide similar feature sets.  In addition to a hosted service,
software for custom installations exists.
Paragraph (version B):
Git is not the only version control system available, nor is GitHub
the only possible choice for hosting.  There are other services that
host revision control repositories and provide similar additional
features to GitHub.  For instance, BitBucket [6] and GitLab [7]
provide similar feature sets.  In addition to a hosted service,
software for custom installations exists.
Paragraph (version A):
This document does require that policies for use of GitHub are agreed
and clearly communicated within the Working Group (see policy).  The
remainder of the document contains guidelines and advice on how to
construct a workable policy.
Paragraph (version B):
This document requires that policies for use of GitHub are agreed and
clearly communicated within the Working Group (see policy).  The
remainder of the document contains guidelines and advice on how to
construct a workable policy.
Paragraph (version A):
In addition to Working Group policies, notices on repositories MUST
include citations for the IETF Note Well [6].
Paragraph (version A):
Working Group Chairs are responsible for determining how to best
accomplish the Charter in an open and transparent fashion.  The
Working Group Chairs are responsible for determining if there is
interest in using GitHub and making a consensus call to determine if
the proposed policy and use is acceptable.
Paragraph (version B):
In addition to Working Group policies, notices on repositories MUST
include citations for the IETF Note Well [8].
Paragraph (version B):
Working Group Chairs are responsible for determining how to best
accomplish the charter objectives in an open and transparent fashion.
The Working Group Chairs are responsible for determining if there is
interest in using GitHub and making a consensus call to determine if
the proposed policy and use is acceptable.
Paragraph (version A):
Working Group Chairs that decide to use GitHub MUST inform their
Working Groups of their decision on the Working Group mailing list.
An email detailing how the Working Group intends to use GitHub is
sufficient, though it might be helpful to occasionally remind new
contributors of these guidelines.
Paragraph (version B):
Working Group Chairs who decide to use GitHub MUST inform their
Working Groups of their decision on the Working Group mailing list.
An email detailing how the Working Group intends to use GitHub is
sufficient, though it might be helpful to occasionally remind new
contributors of these guidelines.
Paragraph (version A):
Restrictions on closing issues are generally not advisable until a
document has reached a certain degree of maturity.
Paragraph (version B):
Restrictions on who can close an issue and under what circumstances
are generally not advisable until a document has reached a certain
degree of maturity.
Paragraph (version A):
Groups of editors could adopt a practice of having one editor create
a pull request and another merge it.  This ensures that changes are
reviewed by editors.  Editors are given discretion in how they manage
changes.
Paragraph (version B):
Groups of editors could adopt a practice of having one editor create
a pull request and another merge it.  This ensures that changes are
reviewed by editors.  Editors are given discretion in how they manage
changes amongst themselves.
Paragraph (version A):
An alternative is to rely on periodic email summaries of activity,
such as those produced by a notification tool like github-notify-ml
[7].  This tool has been used effectively in several Working Groups,
though it requires server infrastructure.
Paragraph (version B):
An alternative is to rely on periodic email summaries of activity,
such as those produced by a notification tool like github-notify-ml
[9].  This tool has been used effectively in several Working Groups,
though it requires server infrastructure.
Paragraph (version A):
Working Group chairs MAY request the creation of an Internet-Draft at
any time, in consultation with document editors.
Paragraph (version B):
Working Group chairs MAY request a revision of an Internet-Draft
being managed on Github at any time, in consultation with document
editors.
Paragraph (version A):
Chairs MUST consider input from all discussion venues when assessing
consensus including GitHub, mailing lists, and in-person meetings.
Each venue has different selection biases that might need to be
considered.
Paragraph (version B):
Chairs MUST consider input from all discussion venues when assessing
consensus including GitHub, mailing lists, interim meetings, and IETF
meetings.  Each venue has different selection biases that might need
to be considered.
Paragraph (version A):
The use of issues and labels has been effective in managing
contentious issues.  Explicitly labeling closed issues to explicitly
identify those with formal consensus means that there is no confusion
about the status of issues.
Paragraph (version B):
The use of issues and labels has been effective in managing
contentious issues.  Explicitly labeling closed issues to identify
those with formal consensus means that there is no confusion about
the status of issues.
Paragraph (version A):
For a document that use formal languages as part of the
specification, such as schema or source code, a continuous
integration system might also be used to validate any formal language
that the document contains.  Tests for any source code that the
document contains might be run, or examples might be checked for
correctness.
Paragraph (version B):
For a document that uses formal languages as part of the
specification, such as schema or source code, a continuous
integration system might also be used to validate any formal language
that the document contains.  Tests for any source code that the
document contains might be run, or examples might be checked for
correctness.
Paragraph (version A):
If a contributor makes a comment that raises what a new issue,
editors can create an issue or - if there is an obvious solution - a
pull request.  It does not matter what venue the issue was raised in
(e.g., email, issue discussion, a pull request review); capturing
issues quickly ensures that problems become visible and can be
tracked.
Paragraph (version B):
If a contributor makes a comment that raises a new issue, editors can
create an issue or - if there is an obvious solution - a pull
request.  It does not matter what venue the issue was raised in
(e.g., email, issue discussion, a pull request review); capturing
issues quickly ensures that problems become visible and can be
tracked.