Merge branch 'master' into mirja

Author: martinthomson

draft-ietf-git-using-github.md

@@ -23,6 +23,13 @@ author:
    email: barbara.stark@att.com
 
 informative:
+  GLOSSARY:
+    title: "GitHub glossary"
+    date: 2020-03
+    target: "https://help.github.com/en/github/getting-started-with-github/github-glossary"
+    author:
+      -
+        organization: GitHub
 
 --- abstract
 
@@ -34,10 +41,10 @@ GitHub for their work.
 
 Discussion of this document takes place on the GitHub@ietf mailing list
 (ietf-and-github@ietf.org), which is archived at
-<https://mailarchive.ietf.org/arch/search?email_list=ietf-and-github>.
+[](https://mailarchive.ietf.org/arch/search?email_list=ietf-and-github).
 
 Source for this draft and an issue tracker can be found at
-<https://github.com/ietf-gitwg/using-github>.
+[](https://github.com/ietf-gitwg/using-github).
 
 
 --- middle
@@ -47,7 +54,7 @@ Source for this draft and an issue tracker can be found at
 The IETF has an open and transparent process for developing standards.  The use
 of [GitHub](https://github.com/) 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
+Use of this service has been found to reduce the time that a Working Group needs
 to produce documents and to improve the quality of the final result.
 
 The use of version control improves traceability and visibility of changes.
@@ -57,7 +64,7 @@ editorial changes, and encourage contributions from a larger set of
 contributors.  Using GitHub can also broaden the community of contributors for a
 specification.
 
-The main purpose of this document is providing guidelines for how Working Groups
+The main purpose of this document is providing guidelines for how a Working Group
 might integrate the capabilities provided by GitHub into their processes for
 developing Internet-Drafts. The choices of whether to use GitHub and whether to
 adopt these practices if they do is at the discretion of the Working Group.
@@ -81,7 +88,7 @@ However, such groups may draw inspiration for GitHub use from the contents herei
 Version control systems are a critical component of software engineering and are
 also quite useful for document editing.
 
-[Git](https://git-scm.com) is a distributed version control system that can operate without a central
+[Git](https://git-scm.com/) 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
@@ -90,7 +97,7 @@ of repositories.
 
 ## GitHub
 
-GitHub is a service operated at [https://github.com/](https://github.com/).
+GitHub is a service operated at [](https://github.com/).
 GitHub provides centralized storage for git repositories.  GitHub is freely
 accessible on the open Internet.
 
@@ -129,7 +136,7 @@ clearly communicated within the Working Group (see {{policy}}).  The remainder
 of the document contains guidelines and advice on how to construct a workable
 policy.
 
-The requirements here apply to the case where Working Groups decide to use
+The requirements here apply to the case where a Working Group decides to use
 GitHub as a primary means of interaction.  Individuals can set their own
 policies when using GitHub for managing their own drafts, or for managing drafts
 that they edit on behalf of a Working Group that has not explicitly adopted
@@ -139,7 +146,7 @@ For both sets of users, this document aims to provide some amount of advice on
 practices that have been effective.
 
 This document only aims to address use of GitHub in developing documents.
-Working Groups could choose to use the tool to aid in managing their charter or
+A Working Group could choose to use the tool to aid in managing their charter or
 session materials such as agendas, minutes, and presentations.  Though the
 advice here might apply more broadly, using GitHub to manage other material is
 out of scope for this document.
@@ -152,6 +159,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 document are to be interpreted as described in BCP 14 {{!RFC2119}} {{!RFC8174}}
 when, and only when, they appear in all capitals, as shown here.
 
+This document uses a lot of terms related to git and GitHub; see {{GLOSSARY}}
+for information on these terms.
+
 
 # Administrative Policies {#policy}
 
@@ -162,9 +172,9 @@ transparency.
 ## Organizations
 
 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
+The Working Group SHOULD create a new organization for its work.  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=I-D.ietf-git-github-wg-configuration}}.
 
 A single organization SHOULD NOT be used for all IETF activity, or all activity
@@ -182,7 +192,7 @@ does not also include the ability to push to all repositories and ownership does
 not grant any other significant privileges.
 
 Details about creating organizations adhering to these guidelines can be found
-in {{!GH-CONFIG=I-D.ietf-git-github-wg-configuration}}.
+in {{?GH-CONFIG=I-D.ietf-git-github-wg-configuration}}.
 
 
 ## Communicating Policies {#notices}
@@ -229,7 +239,7 @@ Working Group Chairs decide what GitHub features the Working Group will rely
 upon.  {{features}} contains a more thorough discussion on the different
 features that can be used.
 
-Working Group Chairs who decide to use GitHub MUST inform their Working Groups
+Working Group Chairs who decide to use GitHub MUST inform the Working Group
 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.
@@ -251,8 +261,8 @@ Working Group policies need to be set with the goal of improving transparency,
 participation, and ultimately the quality of the consensus behind documents.  At
 times, it might be appropriate to impose some limitations on what document
 editors are able to do in order to serve these goals.  Chairs SHOULD
-periodically consult with document editors to ensure that policies are
-effective.
+periodically consult with document editors and the Working Group to ensure that
+policies are effective.
 
 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
@@ -273,12 +283,11 @@ discretion of the chairs.  Chairs could decide to only create new repositories
 for adopted Working Group items, or they might create repositories for
 individual documents on request.
 
-All repositories for Working Group documents within the Working Group
-organization MUST be public.  Repositories for private documents MAY be
-kept private, but only where there is a specific reason for doing so.  For
-instance, a document that details a security vulnerability might be kept
-private prior to its initial publication as an Internet-Draft. Once an
-Internet-Draft is published, repositories SHOULD be made public.
+Maintaining private repositories for Working Group products is not recommended
+without specific cause.  For instance, a document that details a security
+vulnerability might be kept private prior to its initial publication as an
+Internet-Draft. Once an Internet-Draft is published, repositories for Working
+Group documents MUST be made public.
 
 The adoption status of any document MUST be clear from the contents of the
 repository.  This can be achieved by having the name of the document reflect
@@ -314,7 +323,7 @@ write access to repositories.  Users other than document editors, including
 chairs, SHOULD NOT write to Working Group documents without prior coordination
 with document editors.
 
-Working Groups MAY create a team for regular contributors that is only given
+A Working Group 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
@@ -453,17 +462,17 @@ some challenges.
 Comments in a review other than a summary are attached to specific lines of the
 proposed change.  Such comments can be hard or impossible to find if changes are
 subsequently made to the pull request.  This is problematic for contributors who
-do not track discussion closely.
+do not track discussions closely.
 
 For this reason, Working Group chairs SHOULD discourage the use of inline
 comments for substantial technical discussion of issues.
 
 
 ### Merging Pull Requests
 
-Working Groups MUST determine who is permitted to merge pull requests.  Document
-editors SHOULD be permitted to merge pull requests at their discretion.  This
-requires that editors exercise some judgment.  Working Group chairs MAY
+A Working Group MUST determine who is permitted to merge pull requests.
+Document editors SHOULD be permitted to merge pull requests at their discretion.
+This requires that editors exercise some judgment.  Working Group chairs MAY
 occasionally identify a pull request and request that editors withhold merging
 until Working Group consensus has been assessed.
 
@@ -505,15 +514,15 @@ described.  These approaches differ primarily in how discussion of substantive
 matters is managed.  Most of the advice in this document applies equally to all
 models.
 
-Working Groups can adjust these policies to suit their needs, but are advised to
-avoid gratuitous changes for the sake of consistency across the IETF as a whole.
-It is possible to use different processes for different documents in the Working
-Group.
+A Working Group can adjust these policies to suit their needs, but are advised
+to avoid gratuitous changes for the sake of consistency across the IETF as a
+whole.  It is possible to use different processes for different documents in the
+Working Group.
 
-Working Group chairs SHOULD confirm that the Working Group has consensus to
-adopt any process.  In particular, the introduction of a more tightly-controlled
-process can have the effect of privileging positions already captured in
-documents, which might disadvantage alternative viewpoints.
+Working Group chairs are responsible for confirming that the Working Group has
+consensus to adopt any process.  In particular, the introduction of a more
+tightly-controlled process can have the effect of privileging positions already
+captured in documents, which might disadvantage alternative viewpoints.
 
 
 ## Document Management Mode {#mode-doc}
@@ -637,9 +646,9 @@ issues as they see fit.
 As documents mature further, explicit confirmation of technical decisions with
 the Working Group mailing list becomes more important.
 
-Gaining Working Group consensus about the resolution of issues can be done in
-the abstract, with editors being permitted to capture the outcome of discussions
-as they see fit.
+Chairs can declare Working Group consensus about the resolution of
+issues in the abstract, allowing editors discretion on how to capture the
+decisions in documents.
 
 More mature documents require not only consensus, but consensus about specific
 text.  Ideally, substantive changes to documents that have passed WGLC are
@@ -663,7 +672,7 @@ successfully.  This section outlines these strategies and how they might be
 applied.
 
 A design/editorial split (see {{label-design}}) is useful in all cases that the
-issue tracking capability is used.  Working Groups that only use GitHub for
+issue tracking capability is used.  A Working Groups that only uses GitHub for
 issue tracking might find that distinction sufficient for their needs.
 
 Working Groups or editors might use additional labels as they choose.  Any label
@@ -750,9 +759,9 @@ snapshot and makes the content of the in-progress document available to a wider
 audience.  Documents submitted as Internet-Drafts are not expected to address
 all open issues or merge outstanding pull requests.
 
-Editors SHOULD create a new Internet-Draft submission two weeks prior to every
-session, which includes IETF meetings, other in-person meetings, and telephone
-or video conferences (see Section 7.1 of {{?RFC2418}}).  Though discussion could
+Section 7.1 of {{?RFC2418}} recommends that editors create a new Internet-Draft
+submission two weeks prior to every session, which includes IETF meetings, other
+in-person meetings, and telephone or video conferences.  Though discussion could
 use the current version of a document from version control, participants in a
 session cannot be expected to monitor changes to documents in real-time; a
 published Internet-Draft ensures that there is a common, stable state that is