< draft-ietf-git-using-github-05.txt   draft-ietf-git-using-github-06.txt >
Network M. Thomson Network M. Thomson
Internet-Draft Mozilla Internet-Draft Mozilla
Intended status: Best Current Practice B. Stark Intended status: Informational B. Stark
Expires: 5 September 2020 AT&T Expires: 20 September 2020 AT&T
4 March 2020 19 March 2020
Working Group GitHub Usage Guidance Working Group GitHub Usage Guidance
draft-ietf-git-using-github-05 draft-ietf-git-using-github-06
Abstract Abstract
This document describes best practices for Working Groups that use This document provides a set of guidelines for Working Groups that
GitHub for their work. choose to use GitHub for their work.
Note to Readers Note to Readers
Discussion of this document takes place on the GitHub@ietf mailing Discussion of this document takes place on the GitHub@ietf mailing
list (ietf-and-github@ietf.org), which is archived at 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.
(https://mailarchive.ietf.org/arch/search?email_list=ietf-and-
github).
Source for this draft and an issue tracker can be found at Source for this draft and an issue tracker can be found at
https://github.com/ietf-gitwg/using-github (https://github.com/ietf- https://github.com/ietf-gitwg/using-github.
gitwg/using-github).
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 5 September 2020. This Internet-Draft will expire on 20 September 2020.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 2, line 23 skipping to change at page 2, line 20
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Distributed Version Control Systems . . . . . . . . . . . 4 1.1. Distributed Version Control Systems . . . . . . . . . . . 4
1.2. GitHub . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. GitHub . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Other Services . . . . . . . . . . . . . . . . . . . . . 4 1.3. Other Services . . . . . . . . . . . . . . . . . . . . . 4
1.4. Document Goals . . . . . . . . . . . . . . . . . . . . . 5 1.4. Document Goals . . . . . . . . . . . . . . . . . . . . . 5
1.5. Notational Conventions . . . . . . . . . . . . . . . . . 5 1.5. Notational Conventions . . . . . . . . . . . . . . . . . 5
2. Administrative Policies . . . . . . . . . . . . . . . . . . . 5 2. Administrative Policies . . . . . . . . . . . . . . . . . . . 5
2.1. Organizations . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Organizations . . . . . . . . . . . . . . . . . . . . . . 6
2.2. Communicating Policies . . . . . . . . . . . . . . . . . 6 2.2. Communicating Policies . . . . . . . . . . . . . . . . . 6
3. Deciding to Use GitHub . . . . . . . . . . . . . . . . . . . 7 3. Deciding to Use GitHub . . . . . . . . . . . . . . . . . . . 7
3.1. What to Use GitHub For . . . . . . . . . . . . . . . . . 7 3.1. What to Use GitHub For . . . . . . . . . . . . . . . . . 7
3.2. Repositories . . . . . . . . . . . . . . . . . . . . . . 8 3.2. Repositories . . . . . . . . . . . . . . . . . . . . . . 8
3.3. Editors and Contributors . . . . . . . . . . . . . . . . 9 3.3. Editors and Contributors . . . . . . . . . . . . . . . . 9
3.4. Document Formats . . . . . . . . . . . . . . . . . . . . 9 3.4. Document Formats . . . . . . . . . . . . . . . . . . . . 9
4. Contribution Methods . . . . . . . . . . . . . . . . . . . . 9 4. Contribution Methods . . . . . . . . . . . . . . . . . . . . 9
4.1. Issue Tracker . . . . . . . . . . . . . . . . . . . . . . 9 4.1. Issue Tracker . . . . . . . . . . . . . . . . . . . . . . 10
4.1.1. Issue Labels . . . . . . . . . . . . . . . . . . . . 10 4.1.1. Issue Labels . . . . . . . . . . . . . . . . . . . . 10
4.1.2. Closing Issues . . . . . . . . . . . . . . . . . . . 10 4.1.2. Closing Issues . . . . . . . . . . . . . . . . . . . 10
4.1.3. Reopening Issues . . . . . . . . . . . . . . . . . . 10 4.1.3. Reopening Issues . . . . . . . . . . . . . . . . . . 11
4.2. Pull Requests . . . . . . . . . . . . . . . . . . . . . . 11 4.2. Pull Requests . . . . . . . . . . . . . . . . . . . . . . 11
4.2.1. Discussion on Pull Requests . . . . . . . . . . . . . 11 4.2.1. Discussion on Pull Requests . . . . . . . . . . . . . 12
4.2.2. Merging Pull Requests . . . . . . . . . . . . . . . . 12 4.2.2. Merging Pull Requests . . . . . . . . . . . . . . . . 12
4.3. Monitoring Activity . . . . . . . . . . . . . . . . . . . 12 4.3. Monitoring Activity . . . . . . . . . . . . . . . . . . . 12
5. Typical Working Group Policies . . . . . . . . . . . . . . . 12 5. Typical Working Group Policies . . . . . . . . . . . . . . . 13
5.1. Document Management Mode . . . . . . . . . . . . . . . . 13 5.1. Document Management Mode . . . . . . . . . . . . . . . . 13
5.2. Issue Tracking Mode . . . . . . . . . . . . . . . . . . . 13 5.2. Issue Tracking Mode . . . . . . . . . . . . . . . . . . . 14
5.3. Issue Discussion Mode . . . . . . . . . . . . . . . . . . 14 5.3. Issue Discussion Mode . . . . . . . . . . . . . . . . . . 15
5.3.1. Early Design Phases . . . . . . . . . . . . . . . . . 15 5.3.1. Early Design Phases . . . . . . . . . . . . . . . . . 15
5.3.2. Managing Mature Documents . . . . . . . . . . . . . . 15 5.3.2. Managing Mature Documents . . . . . . . . . . . . . . 16
5.4. Issue Labelling Schemes . . . . . . . . . . . . . . . . . 16 5.4. Issue Labelling Schemes . . . . . . . . . . . . . . . . . 17
5.4.1. Editorial/Design Labelling . . . . . . . . . . . . . 16 5.4.1. Editorial/Design Labelling . . . . . . . . . . . . . 17
5.4.2. Decision Labelling . . . . . . . . . . . . . . . . . 17 5.4.2. Decision Labelling . . . . . . . . . . . . . . . . . 17
5.4.3. Component Labelling . . . . . . . . . . . . . . . . . 17 5.4.3. Component Labelling . . . . . . . . . . . . . . . . . 18
5.4.4. Other Labels . . . . . . . . . . . . . . . . . . . . 17 5.4.4. Other Labels . . . . . . . . . . . . . . . . . . . . 18
6. Internet-Draft Publication . . . . . . . . . . . . . . . . . 18 6. Internet-Draft Publication . . . . . . . . . . . . . . . . . 18
7. Assessing Consensus . . . . . . . . . . . . . . . . . . . . . 18 7. Assessing Consensus . . . . . . . . . . . . . . . . . . . . . 19
8. Continuous Integration . . . . . . . . . . . . . . . . . . . 19 8. Continuous Integration . . . . . . . . . . . . . . . . . . . 20
9. Advice to Editors . . . . . . . . . . . . . . . . . . . . . . 20 9. Advice to Editors . . . . . . . . . . . . . . . . . . . . . . 20
10. Security Considerations . . . . . . . . . . . . . . . . . . . 20 10. Security Considerations . . . . . . . . . . . . . . . . . . . 21
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 22
12.1. Normative References . . . . . . . . . . . . . . . . . . 21 12.1. Normative References . . . . . . . . . . . . . . . . . . 22
12.2. Informative References . . . . . . . . . . . . . . . . . 21 12.2. Informative References . . . . . . . . . . . . . . . . . 22
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 22 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23
1. Introduction 1. Introduction
The IETF has an open and transparent process for developing The IETF has an open and transparent process for developing
standards. The use of GitHub (https://github.com/) or similar tools, standards. The use of GitHub (https://github.com/) or similar tools,
when used as part of this process, can have several objectives. when used as part of this process, can have several objectives.
GitHub provides tools that can be helpful in editing documents. Use GitHub provides tools that can be helpful in editing documents. Use
of this service has been found to reduce the time that Working Groups of this service has been found to reduce the time that a Working
need to produce documents and to improve the quality of the final Group needs to produce documents and to improve the quality of the
result. final result.
The use of version control improves traceability and visibility of The use of version control improves traceability and visibility of
changes. Issue tracking can be used to manage open issues and changes. Issue tracking can be used to manage open issues and
provide a record of their resolution. Pull requests allow for better provide a record of their resolution. Pull requests allow for better
engagement on technical and editorial changes, and encourage engagement on technical and editorial changes, and encourage
contributions from a larger set of contributors. Using GitHub can contributions from a larger set of contributors. Using GitHub can
also broaden the community of contributors for a specification. also broaden the community of contributors for a specification.
The main purpose of this document is providing guidelines for how The main purpose of this document is providing guidelines for how a
Working Groups might integrate the capabilities provided by GitHub Working Group might integrate the capabilities provided by GitHub
into their processes for developing Internet-Drafts. into their processes for developing Internet-Drafts. Whether to use
GitHub and whether to adopt these practices is left to the discretion
of the Working Group.
This document is meant as a supplement to existing Working Group This document is meant as a supplement to existing Working Group
practices. It provides guidance to Working Group chairs and practices. It provides guidance to Working Group chairs and
participants on how they can best use GitHub within the framework participants on how they can best use GitHub within the framework
established by RFC 2418 [RFC2418]. This document aims to establish established by RFC 2418 [RFC2418]. This document aims to establish
norms that reduce the variation in usage patterns between different norms that reduce the variation in usage patterns between different
Working Groups and to help avoid issues that have been encountered in Working Groups and to help avoid issues that have been encountered in
the past. the past.
A companion document, [GH-CONFIG], describes administrative processes A companion document, [GH-CONFIG], describes administrative processes
that support the practices described in this document. that support the practices described in this document.
Although similar, guidance for IRTF Research Groups is out of scope Although the operation of IRTF Research Groups can be similar in
for this document. However, such groups may draw inspiration for function to Working Groups, this document only directly addresses the
GitHub use from the contents herein. needs of Working Groups. However, other groups may draw inspiration
for GitHub use from the contents herein.
1.1. Distributed Version Control Systems 1.1. Distributed Version Control Systems
Version control systems are a critical component of software Version control systems are a critical component of software
engineering and are also quite useful for document editing. engineering and are also quite useful for document editing.
Git (https://git-scm.com) is a distributed version control system Git (https://git-scm.com/) is a distributed version control system
that can operate without a central service. Each instance of a that can operate without a central service. Each instance of a
repository contains a number of revisions. Each revision stores the repository contains a number of revisions. Each revision stores the
complete state of a set of files. Users are able to create new complete state of a set of files. Users are able to create new
revisions in their copy of a repository and share revisions between revisions in their copy of a repository and share revisions between
copies of repositories. copies of repositories.
1.2. GitHub 1.2. GitHub
GitHub is a service operated at https://github.com/ GitHub is a service operated at https://github.com/. GitHub provides
(https://github.com/). GitHub provides centralized storage for git centralized storage for git repositories. GitHub is freely
repositories. GitHub is freely accessible on the open Internet, accessible on the open Internet.
albeit currently only via IPv4.
GitHub provides a simplified and integrated interface to not only GitHub provides a simplified and integrated interface to git, and
git, but also provides basic user management, an issue tracker, also provides basic user management, an issue tracker, associated
associated wikis, project hosting, and other features. wikis, project hosting, and other features.
There are a large number of projects at GitHub and a very large There are a large number of projects at GitHub and a very large
community of contributors. One way in which some IETF Working Groups community of contributors. One way in which some IETF Working Groups
have benefited is through increased numbers of reviews and associated have benefited from use of the service is through increased numbers
issues, along with other improvements that come from broader of reviews and associated issues, along with other improvements that
participation by facilitating those in the community to participate. come from facilitating participation by a broader community.
1.3. Other Services 1.3. Other Services
Git is not the only version control system available, nor is GitHub Git is not the only version control system available, nor is GitHub
the only possible choice for hosting. There are other services that the only possible choice for hosting. There are other services that
host revision control repositories and provide similar additional host revision control repositories and provide similar additional
features to GitHub. For instance, BitBucket (https://bitbucket.org/) features to GitHub. For instance, BitBucket (https://bitbucket.org/)
and GitLab (https://about.gitlab.com/) provide similar feature sets. and GitLab (https://about.gitlab.com/) provide similar feature sets.
In addition to a hosted service, software for custom installations In addition to a hosted service, software for custom installations
exists. exists.
skipping to change at page 5, line 16 skipping to change at page 5, line 16
This document aims to describe how a Working Group might best apply This document aims to describe how a Working Group might best apply
GitHub to their work. The intent is to allow each Working Group GitHub to their work. The intent is to allow each Working Group
considerable flexibility in how they use GitHub. considerable flexibility in how they use GitHub.
This document requires that policies for use of GitHub are agreed and This document requires that policies for use of GitHub are agreed and
clearly communicated within the Working Group (see Section 2). The clearly communicated within the Working Group (see Section 2). The
remainder of the document contains guidelines and advice on how to remainder of the document contains guidelines and advice on how to
construct a workable policy. construct a workable policy.
The requirements here apply to the case where Working Groups decide The requirements here apply to the case where a Working Group decides
to use GitHub as a primary means of interaction. Individuals can set to use GitHub as a primary means of interaction. Individuals can set
their own policies when using GitHub for managing their own drafts, their own policies when using GitHub for managing their own drafts,
or for managing drafts that they edit on behalf of a Working Group or for managing drafts that they edit on behalf of a Working Group
that has not explicitly adopted GitHub. that has not explicitly adopted GitHub.
For both sets of users, this document aims to provide some amount of For both sets of users, this document aims to provide some amount of
advice on practices that have been effective. advice on practices that have been effective.
This document only aims to address use of GitHub in developing This document only aims to address use of GitHub in developing
documents. Working Groups could choose to use the tool to aid in documents. A Working Group could choose to use the tool to aid in
managing their charter or session materials such as agendas, minutes, managing their charter or session materials such as agendas, minutes,
and presentations. Though the advice here might apply more broadly, and presentations. Though the advice here might apply more broadly,
using GitHub to manage other material is out of scope for this using GitHub to manage other material is out of scope for this
document. document.
1.5. Notational Conventions 1.5. Notational Conventions
The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
used in this document. It's not shouting; when they are capitalized, "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
they have the special meaning defined in BCP 14 [RFC2119] [RFC8174]. "OPTIONAL" in this 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.
2. Administrative Policies 2. Administrative Policies
The following administrative rules provide the necessary oversight The following administrative rules provide the necessary oversight
and transparency. and transparency.
2.1. Organizations 2.1. Organizations
Organizations are a way of forming groups of contributors on GitHub. Organizations are a way of forming groups of contributors on GitHub.
Each Working Group SHOULD create a new organization for the Working The Working Group SHOULD create a new organization for its work. A
Group. A Working Group organization SHOULD be named consistently so Working Group organization SHOULD be named consistently so that it
that it can be found. For instance, the name could be ietf- can be found. For instance, the name could be ietf-wg-<wgname>, as
wg-<wgname>, as recommended in [GH-CONFIG]. recommended in [GH-CONFIG].
A single organization SHOULD NOT be used for all IETF activity, or A single organization SHOULD NOT be used for all IETF activity, or
all activity within an area. Large organizations create too much all activity within an area. Large organizations create too much
overhead for general management tasks, particularly when there is a overhead for general management tasks.
need to maintain membership.
Each organization requires owners. The owner team for a Working GitHub requires that each organization have at least one owner. The
Group repository MUST include responsible Area Directors. Area owners for a Working Group repository MUST include responsible Area
Directors MAY also designate a delegate that becomes an owner and Directors and the IETF Secretariat. Working Group chairs SHOULD also
Working Group chairs MAY also be owners. be included as owners. Area Directors MAY also designate a delegate
that becomes an owner, such as another Area Director from the same
area. An organization MUST have at least 2 owners.
A team with administrator access SHOULD be created for the Working Within an organization, members can be grouped into teams. A team
Group Chairs and any Working Group Secretary. Administrator access with "Admin" access to repositories SHOULD be created for the Working
is preferable, since this does not also include the ability to push Group Chairs and any Working Group Secretary.
to all repositories and ownership does not grant any other
significant privileges.
Details about creating organizations adhering to these guidelines can Details about creating organizations adhering to these guidelines can
be found in [GH-CONFIG]. be found in [GH-CONFIG].
2.2. Communicating Policies 2.2. Communicating Policies
Each Working Group MAY set its own policy as to whether and how it Each Working Group MAY set its own policy as to whether and how it
uses GitHub. It is important that occasional participants in the WG uses GitHub. It is important that occasional participants in the WG
and others accustomed to IETF tools be able to determine this and and others accustomed to IETF tools be able to determine this and
easily find the policy and GitHub organization. easily find the policy and GitHub organization.
A simple example of how to do this is to include a link to the GitHub A simple example of how to do this is to include a link to the GitHub
organization on the WG Charter page in the datatracker. Similarly, organization on the WG Charter page in the datatracker. Similarly,
if there are multiple mailing list options, links to those mailing if there are additional resources, such as mailing lists, links to
lists should be given. those resources could also be added.
Repositories MUST include a copy or reference to the policy that Repositories MUST include a copy of or reference to the policy that
applies to managing any documents they contain. Updating the README applies to managing any documents they contain. Updating the README
or CONTRIBUTING file in the repository with details of the process or CONTRIBUTING file in the repository with details of the process
ensures that the process is recorded in a stable location other than ensures that the process is recorded in a stable location other than
the mailing list archive. This also makes Working Group policies the mailing list archive. This also makes Working Group policies
available to casual contributors who might only interact with the available to casual contributors who might only interact with the
GitHub repository. GitHub repository.
GitHub prominently links to the CONTRIBUTING file on certain pages. GitHub prominently links to the CONTRIBUTING file on certain pages.
This file SHOULD be used in preference to the README for information This file SHOULD be used in preference to the README for information
that new contributors need. The README SHOULD contain a link to the that new contributors need. The README SHOULD contain a link to the
skipping to change at page 7, line 13 skipping to change at page 7, line 19
note-well/). note-well/).
3. Deciding to Use GitHub 3. Deciding to Use GitHub
Working Group Chairs are responsible for determining how to best Working Group Chairs are responsible for determining how to best
accomplish the charter objectives in an open and transparent fashion. accomplish the charter objectives in an open and transparent fashion.
The Working Group Chairs are responsible for determining if there is The Working Group Chairs are responsible for determining if there is
interest in using GitHub and making a consensus call to determine if interest in using GitHub and making a consensus call to determine if
the proposed policy and use is acceptable. the proposed policy and use is acceptable.
Chairs MUST involve Area Directors in any decision to use GitHub for Chairs SHOULD involve Area Directors in any decision to use GitHub,
anything more than managing drafts. especially where substantive discussion of issues is permitted as
described in Section 5.3.
3.1. What to Use GitHub For 3.1. What to Use GitHub For
Working Group Chairs decide what GitHub features the Working Group Working Group Chairs decide what GitHub features the Working Group
will rely upon. Section 4 contains a more thorough discussion on the will rely upon. Section 4 contains a more thorough discussion on the
different features that can be used. different features that can be used.
Working Group Chairs who decide to use GitHub MUST inform their Working Group Chairs who decide to use GitHub MUST inform the Working
Working Groups of their decision on the Working Group mailing list. Group of their decision on the Working Group mailing list. An email
An email detailing how the Working Group intends to use GitHub is detailing how the Working Group intends to use GitHub is sufficient,
sufficient, though it might be helpful to occasionally remind new though it might be helpful to occasionally remind new contributors of
contributors of these guidelines. these guidelines.
Working Group Chairs are responsible for ensuring that any policy Working Group Chairs are responsible for ensuring that any policy
they adopt is enforced and maintained. they adopt is enforced and maintained.
The set of GitHub features (Section 4) that the Working Group relies The set of GitHub features (Section 4) that the Working Group relies
upon need to be clearly documented in policies. This document upon need to be clearly documented in policies. This document
provides some guidance on potential policies and how those might be provides some guidance on potential policies and how those might be
applied. applied.
Features that the Working Group does not rely upon SHOULD be made Features that the Working Group does not rely upon can be made
available to document editors. Editors are then able to use these available to document editors. Editors are then able to use these
features for their own purposes. For example, though the Working features for their own purposes. For example, though the Working
Group might not formally use issues to track items that require Group might not formally use issues to track items that require
further discussion in order to reach consensus, keeping the issue further discussion in order to reach consensus, keeping the issue
tracker available to editors can be valuable. tracker available to editors can be valuable.
Working Group policies need to be set with the goal of improving Working Group policies need to be set with the goal of improving
transparency, participation, and ultimately the quality of the transparency, participation, and ultimately the quality of documents.
consensus behind documents. At times, it might be appropriate to
impose some limitations on what document editors are able to do in At times, it might be appropriate to impose some limitations on what
order to serve these goals. Chairs SHOULD periodically consult with document editors are able to do in order to serve these goals.
document editors to ensure that policies are effective. Chairs are encouraged to periodically consult with document editors
to ensure that policies are effective.
A document editor can still use GitHub independently for documents A document editor can still use GitHub independently for documents
that they edit, even if the Working Group does not expressly choose that they edit, even if the Working Group does not expressly choose
to use GitHub. Any such public repository MUST follow the IETF Note to use GitHub. Any such public repository MUST follow the IETF Note
Well and bear notices; see Section 2.2. This recognizes that editors Well and bear notices; see Section 2.2. This recognizes that editors
have traditionally chosen their own methods for managing the have traditionally chosen their own methods for managing the
documents they edit but preserves the need for contributors to documents they edit but preserves the need for contributors to
understand their obligations with respect to IETF processes. understand their obligations with respect to IETF processes.
Work done in GitHub has no special status. The output of any Work done in GitHub has no special status. The output of any
skipping to change at page 8, line 21 skipping to change at page 8, line 30
subject to approval, rejection, or modification by the Working Group subject to approval, rejection, or modification by the Working Group
as with any other input. as with any other input.
3.2. Repositories 3.2. Repositories
New repositories can be created within the Working Group organization New repositories can be created within the Working Group organization
at the discretion of the chairs. Chairs could decide to only create at the discretion of the chairs. Chairs could decide to only create
new repositories for adopted Working Group items, or they might new repositories for adopted Working Group items, or they might
create repositories for individual documents on request. create repositories for individual documents on request.
All repositories for Working Group documents within the Working Group Maintaining private repositories for Working Group products is not
organization MUST be public. Repositories for private documents MAY recommended without specific cause. For instance, a document that
be kept private, but only where there is a specific reason for doing details a security vulnerability might be kept private prior to its
so. For instance, a document that details a security vulnerability initial publication as an Internet-Draft. Once an Internet-Draft is
might be kept private prior to its initial publication as an published, repositories for Working Group documents MUST be made
Internet-Draft. Once an Internet-Draft is published, repositories public.
SHOULD be made public.
The adoption status of any document MUST be clear from the contents 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 of the repository. This can be achieved by having the name of the
document reflect status (that is, draft-ietf-<wgname>-... indicates document reflect status (that is, draft-ietf-<wgname>-... indicates
that the document was adopted), or through a prominent notice (such that the document was adopted), or through a prominent notice (such
as in the README). as in the README).
Experience has shown that maintaining separate repositories for Experience has shown that maintaining separate repositories for
independent documents is most manageable. This allows the work in independent documents is most manageable. This allows the work in
that repository to be focused on a single item. that repository to be focused on a single item.
skipping to change at page 9, line 20 skipping to change at page 9, line 27
collaborators on the repository. collaborators on the repository.
Working Group chairs MAY also grant other individuals write access Working Group chairs MAY also grant other individuals write access
for other reasons, such as maintaining supporting code or build for other reasons, such as maintaining supporting code or build
configurations. Working Group chairs, as administrators or owners of configurations. Working Group chairs, as administrators or owners of
the organization might also have write access to repositories. Users the organization might also have write access to repositories. Users
other than document editors, including chairs, SHOULD NOT write to other than document editors, including chairs, SHOULD NOT write to
Working Group documents without prior coordination with document Working Group documents without prior coordination with document
editors. editors.
Working Groups MAY create a team for regular contributors that is A Working Group MAY create a team for regular contributors that is
only given read access to a repository. This does not confer only given read access to a repository. This does not confer
additional privileges on these contributors, it instead allows for additional privileges on these contributors, it instead allows for
issues and pull requests to be assigned to those people. This can be issues and pull requests to be assigned to those people. This can be
used to manage the assignment of editorial or review tasks to used to manage the assignment of editorial or review tasks to
individuals outside of the editor team. individuals outside of the editor team.
3.4. Document Formats 3.4. Document Formats
In addition to the canonical XML format [RFC7991], document editors In addition to the canonical XML format [RFC7991], document editors
might choose to use a different input form for editing documents, might choose to use a different input form for editing documents,
skipping to change at page 10, line 27 skipping to change at page 10, line 36
A system of labeling issues can be effective in managing issues. For A system of labeling issues can be effective in managing issues. For
instance, marking substantive issues separately from editorial can be instance, marking substantive issues separately from editorial can be
helpful at guiding discussion. Using labels can also be helpful in helpful at guiding discussion. Using labels can also be helpful in
identifying issues for which consensus has been achieved, but that identifying issues for which consensus has been achieved, but that
require editors to integrate the changes into a document. require editors to integrate the changes into a document.
Labels can be used to identify particular categories of issues or to Labels can be used to identify particular categories of issues or to
mark specific issues for discussion at an upcoming session. mark specific issues for discussion at an upcoming session.
If labels are a core part of Working Group process, chairs MUST Chairs communicate any process that specifically relates to the use
communicate any process to the Working Group. This includes the of labels to the Working Group. This includes the semantics of
semantics of labels, and who can apply and remove these labels. labels, and who can apply and remove these labels. Section 5.4
Section 5.4 describes some basic strategies that might be adopted to describes some basic strategies that might be adopted to manage
manage decision-making processes. decision-making processes.
4.1.2. Closing Issues 4.1.2. Closing Issues
Editors have write access to repositories, which also allows them to Editors have write access to repositories, which also allows them to
close issues. The user that opens an issue is also able to close the close issues. The user that opens an issue is also able to close the
issue. Chairs MUST provide guidance on who is permitted to close an issue. Chairs MUST provide guidance on who is permitted to close an
issue and under what conditions. issue and under what conditions.
Restrictions on who can close an issue and under what circumstances Restrictions on who can close an issue and under what circumstances
are generally not advisable until a document has reached a certain are generally not advisable until a document has reached a certain
degree of maturity. degree of maturity.
4.1.3. Reopening Issues 4.1.3. Reopening Issues
Issues that have reached a resolution that has Working Group Issues that have reached a resolution that has Working Group
consensus MUST NOT be reopened unless new information is presented. consensus MUST NOT be reopened unless new information is presented.
For long-running work items, new contributors often raise issues that For long-running work items, new contributors often raise issues that
have already been resolved. Chairs need to assess whether the have already been resolved. Moreover, there could be temptation to
arguments offered represent new information or not. This can require reopen contentious issues resolved with rough consensus. Determining
some discussion to determine accurately. Resolved issues MUST remain whether arguments presented in favor of reopening an issue represents
closed unless there is consensus to reopen an issue. new information might require some discussion in the Working Group.
Chairs are empowered to exercise discretion in determining whether to
reopen issues. For more difficult matters, the chairs MAY insist
that the Working Group reach consensus on whether an issue should be
reopened. Note however that any product of this process still needs
to have the support of rough consensus in the Working Group, which
could justify reopening issues.
4.2. Pull Requests 4.2. Pull Requests
Pull requests are the GitHub feature that allow users to request A pull request is a GitHub feature that allows a user to request a
changes to a repository. A user does not need to have write access change to a repository. A user does not need to have write access to
to a repository to create a pull request. A user can create a a repository to create a pull request. A user can create a "fork",
"fork", or copy, of any public repository. The user has write access or copy, of any public repository. The user has write access to
to their own fork, allowing them to make local changes. A pull their own fork, allowing them to make local changes. A pull request
request asks the owner of a repository to merge a specific set of asks the owner of a repository to merge a specific set of changes
changes from a fork (or any branch) into their copy. from a fork (or any branch) into their copy.
Editors SHOULD make pull requests for all substantial changes rather Editors are encouraged to make pull requests for all substantial
than committing directly to the "master" branch of the repository. changes rather than committing directly to the "master" branch of the
See Section 5.3.2 for discussion on what constitutes a substantial repository. See Section 5.3.2 for discussion on what constitutes a
change. A pull request creates an artifact that records the reasons substantial change. A pull request creates an artifact that records
for changes and provides other contributors with an opportunity to the reasons for changes and provides other contributors with an
review the change. Pull requests that address substantive issues opportunity to review the change. Ideally, pull requests that
SHOULD mention the issue they address in the opening comment. address substantive issues mention the issue they address in the
opening comment. A Working Group policy could require that pull
requests are used in this fashion.
Note: This document assumes that there is a unified effort on a Note: This document assumes that there is a unified effort on a
document, all concentrated on a git "master" branch. More document, all concentrated on a git "master" branch. More
advanced usage of git is not in the scope of this document. advanced usage of git is not in the scope of this document.
Pull requests have many of the same properties as issues, including Pull requests have many of the same properties as issues, including
the ability to host discussion and bear labels. Critically, using the ability to host discussion and bear labels. Critically, using
pull requests creates a record of actions taken. pull requests creates a record of actions taken.
For significant changes, leaving a pull request open until discussion For significant changes, leaving a pull request open until discussion
skipping to change at page 11, line 48 skipping to change at page 12, line 17
Groups of editors could adopt a practice of having one editor create Groups of editors could adopt a practice of having one editor create
a pull request and another merge it. This ensures that changes are a pull request and another merge it. This ensures that changes are
reviewed by editors. Editors are given discretion in how they manage reviewed by editors. Editors are given discretion in how they manage
changes amongst themselves. changes amongst themselves.
4.2.1. Discussion on Pull Requests 4.2.1. Discussion on Pull Requests
In addition to the features that pull requests share with issues, In addition to the features that pull requests share with issues,
users can also review the changes in a pull request. This is a users can also review the changes in a pull request. This is a
valuable feature, but it has some issues. valuable feature, but presents some challenges.
Comments in a review other than a summary are attached to specific Comments in a review other than a summary are attached to specific
lines of the proposed change. Such comments can be hard or lines of the proposed change. Such comments can be hard or
impossible to find if changes are subsequently made to the pull impossible to find if changes are subsequently made to the pull
request. This is problematic for contributors who do not track request. This is problematic for contributors who do not track
discussion closely. discussions closely.
For this reason, Working Group chairs SHOULD discourage the use of For this reason, Working Group chairs SHOULD discourage the use of
inline comments for substantial technical discussion of issues. inline comments for substantial technical discussion of issues.
4.2.2. Merging Pull Requests 4.2.2. Merging Pull Requests
Working Groups MUST determine who is permitted to merge pull A Working Group MUST determine who is permitted to merge pull
requests. Document editors SHOULD be permitted to merge pull requests. Document editors SHOULD be permitted to merge pull
requests at their discretion. This requires that editors exercise requests at their discretion. This requires that editors exercise
some judgment. Working Group chairs MAY occasionally identify a pull some judgment. Working Group chairs MAY occasionally identify a pull
request and request that editors withhold merging until Working Group request and request that editors withhold merging until Working Group
consensus has been assessed. consensus has been assessed.
Note that the copy of a document that is maintained on GitHub does Note that the copy of a document that is maintained on GitHub does
not need to be a perfect reflection of Working Group consensus at not need to be a perfect reflection of Working Group consensus at
every point in time. Document editors need some flexibility in how every point in time. Document editors need some flexibility in how
they manage a document. they manage a document.
skipping to change at page 12, line 40 skipping to change at page 13, line 11
notifications about activity on Working Group repositories. The notifications about activity on Working Group repositories. The
volume of information on these lists can be too high to monitor volume of information on these lists can be too high to monitor
actively, but access to an archive of actions can be useful. actively, but access to an archive of actions can be useful.
An alternative is to rely on periodic email summaries of activity, An alternative is to rely on periodic email summaries of activity,
such as those produced by a notification tool like github-notify-ml such as those produced by a notification tool like github-notify-ml
(https://github.com/dontcallmedom/github-notify-ml). This tool has (https://github.com/dontcallmedom/github-notify-ml). This tool has
been used effectively in several Working Groups, though it requires been used effectively in several Working Groups, though it requires
server infrastructure. server infrastructure.
Additionally, clear reporting about the changes that were included in
each revision of an Internet-Draft helps ensure that contributors can
follow activity. This might be achieved by requesting that editors
provide a change log that captures substantive changes to the
document in each revision.
5. Typical Working Group Policies 5. Typical Working Group Policies
Current experience with use of GitHub suggests a few different Current experience with use of GitHub suggests a few different
approaches to greater use of the tool in Working Groups. approaches to greater use of the tool in Working Groups.
This section describes some basic modes for interacting with GitHub, This section describes some basic modes for interacting with GitHub,
each progressively more involved. This starts with a very each progressively more involved. This starts with a very
lightweight interaction where document management is the only feature lightweight interaction where document management is the only feature
that is formally used, then progressively more intensive use of the that is formally used, then progressively more intensive use of the
GitHub issue tracking capabilities are described. These approaches GitHub issue tracking capabilities are described. These approaches
differ primarily in how discussion of substantive matters is managed. differ primarily in how discussion of substantive matters is managed.
Most of the advice in this document applies equally to all models. Most of the advice in this document applies equally to all models.
Working Groups can adjust these policies to suit their needs, but are A Working Group can adjust these policies to suit their needs, but
advised to avoid gratuitous changes for the sake of consistency are advised to avoid gratuitous changes for the sake of consistency
across the IETF as a whole. across the IETF as a whole. It is possible to use different
processes for different documents in the Working Group.
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.
5.1. Document Management Mode 5.1. Document Management Mode
In this mode of interaction, GitHub repositories are used to manage In this mode of interaction, GitHub repositories are used to manage
changes to documents, but the bulk of the work is conducted using changes to documents, but the bulk of the work is conducted using
email, face-to-face meetings, and other more traditional email, face-to-face meetings, and other more traditional
interactions. The intent of this policy is to enable document and interactions. The intent of this policy is to enable document and
issue management using GitHub while minimizing the complexity of the issue management using GitHub while minimizing the complexity of the
process. process.
In the version of this mode with the least interaction with GitHub, a In the version of this mode with the least interaction with GitHub, a
repository is created for the purposes of document management by repository is created for the purposes of document management by
editors. Editors might maintain issues and pull requests for their editors. Editors might maintain issues and pull requests for their
own benefit, but these have no formal standing in the Working Group own benefit, but these have no formal standing in the Working Group
process. process.
5.2. Issue Tracking Mode 5.2. Issue Tracking Mode
In addition to managing documents, the Working Group might choose to In addition to managing documents, the Working Group might choose to
use GitHub for tracking outstanding issues. In this mode of use GitHub for tracking outstanding issues. In this mode of
interaction, all substantive technical discussions are tracked as interaction, a record of the existence of substantive technical
issues in the issue tracker. However, discussion of any substantial discussions is tracked using issues in the issue tracker. However,
matters is always conducted on mailing lists. discussion of any substantial matters is always conducted on mailing
lists.
Under this mode, issues and pull requests can be opened by anyone, Under this mode, issues and pull requests can be opened by anyone,
but anything deemed substantive MUST be resolved exclusively on the but anything deemed substantive MUST be resolved exclusively on the
mailing list. Discussion on GitHub is kept to a minimum. Only mailing list. Discussion on GitHub is limited to recording the state
editorial matters can be resolved using the issue tracker. of issues. Only editorial matters can be resolved using the issue
tracker.
Chairs and editors are given discretion in determining what issues Chairs and editors are given discretion in determining what issues
are substantive. As documents mature, it is generally prudent to are substantive. As documents mature, it is generally prudent to
prefer consulting the mailing list where there is doubt. As with prefer consulting the mailing list where there is doubt. As with
other Working Group decisions, chairs are the arbiters in case of other Working Group decisions, chairs are the arbiters in case of
dispute. dispute.
A recurrent problem with this mode of interaction is the tendency for A recurrent problem with this mode of interaction is the tendency for
discussions to spontaneously develop in the issue tracker. This discussions to spontaneously develop in the issue tracker. This
requires a degree of discipline from chairs and editors to ensure requires a degree of discipline from chairs and editors to ensure
skipping to change at page 14, line 31 skipping to change at page 15, line 24
A Working Group mailing list remains a critical venue for decision A Working Group mailing list remains a critical venue for decision
making, even where issue discussion occurs elsewhere. Working Group making, even where issue discussion occurs elsewhere. Working Group
mailing lists generally include a wider audience than those who mailing lists generally include a wider audience than those who
follow issue discussion, so difficult issues always benefit from list follow issue discussion, so difficult issues always benefit from list
discussion. discussion.
Decisions about Working Group consensus MUST always be confirmed Decisions about Working Group consensus MUST always be confirmed
using the Working Group mailing list. However, depending on the using the Working Group mailing list. However, depending on the
maturity of documents, this might be a more lightweight interaction, maturity of documents, this might be a more lightweight interaction,
such as sending an email confirmation for a set of resolutions made such as sending an email confirmation for an initial set of
using GitHub. resolutions arising from discussions on the issue tracker.
Using the mailing list to resolve difficult or controversial issues Using the mailing list to resolve difficult or controversial issues
is strongly encouraged. In those cases, the issue tracker might be is strongly encouraged. In those cases, the issue tracker might be
used to more fully develop an understanding of problems before used to more fully develop an understanding of problems before
initiating a discussion on the mailing list, along lines similar to initiating a discussion on the mailing list, along lines similar to
the design team process (see Section 6.5 of [RFC2418]). the design team process (see Section 6.5 of [RFC2418]).
As a more involved process, adopting this mode can require changes in As a more involved process, adopting this mode can require changes in
policies as documents become more mature. It is possible to use policies as documents become more mature.
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.
5.3.1. Early Design Phases 5.3.1. Early Design Phases
During early phases of the design of a protocol, chairs MAY allow During early phases of the design of a protocol, chairs MAY allow
editors to manage all aspects of issues. Editors are permitted to editors to manage all aspects of issues. Editors are permitted to
make decisions about how to both identify and resolve technical make decisions about how to both identify and resolve technical
issues, including making any changes that editors feel necessary. issues, including making any changes that editors feel necessary.
Chairs need to explicitly decide that this sort of process is needed Chairs need to explicitly decide that this sort of process is needed
and announce the decision to the Working Group. In many cases, and announce the decision to the Working Group. In many cases,
documents that are adopted by a Working Group are already documents that are adopted by a Working Group are already
sufficiently mature that a looser process is not beneficial. The sufficiently mature that a looser process is not beneficial. The
primary reason to grant editors more discretionary power is to primary reason to grant editors more discretionary power is to
improve the speed with which changes can be made. The risk is that improve the speed with which changes can be made. The risk is from
design changes might not always reflect the consensus of the Working integrating changes including substantive decisions that don't
Group. reflect the consensus of the Working Group or that the need for
consensus on an issue is not identified.
Changes made by editors under this process do not completely lack Changes made by editors under this process do not lack options for
oversight. GitHub and git provide tools for ensuring that changes identifying and correcting problems. GitHub and git provide tools
are tracked and can be audited. Within the usual Working Group for ensuring that changes are tracked and can be audited. Within the
process it is expected that Internet-Drafts will receive regular usual Working Group process it is expected that Internet-Drafts will
review. Finally, process checkpoints like Working Group Last Call receive regular review. Finally, process checkpoints like Working
(WGLC; Section 7.4 of [RFC2418]) provides additional safeguards Group Last Call (WGLC; Section 7.4 of [RFC2418]) provide additional
against abuse. safeguards against abuse.
Working Groups are advised against allowing editors this degree of Working Groups are advised against allowing editors this degree of
flexibility for the entirety of a document lifecycle. Once a flexibility for the entirety of a document lifecycle. Once a
document is more stable and mature, it is likely appropriate to move document is more stable and mature, it could be useful to move to a
to a more tightly controlled process. more tightly controlled process.
5.3.2. Managing Mature Documents 5.3.2. Managing Mature Documents
As a document matures, it becomes more important to understand not As a document matures, it becomes more important to understand not
just that the document as a whole retains the support of the Working just that the document as a whole retains the support of the Working
Group, but that changes are not made without wider consultation. Group, but that changes are not made without wider consultation.
Chairs might choose to manage the process of deciding which issues Chairs MAY choose to manage the process of deciding which issues are
are substantive. For instance, chairs might reserve the ability to substantive. For instance, chairs might reserve the ability to use
use the "design" label to new issues (see Section 5.4.1) and to close the "design" label to new issues (see Section 5.4.1) and to close
issues marked as "design". Chairs should always allow document issues marked as "design". Chairs SHOULD always allow document
editors to identify and address editorial issues as they see fit. editors to identify and address editorial issues as they see fit.
As documents mature further, explicit confirmation of technical As documents mature further, explicit confirmation of technical
decisions with the Working Group mailing list becomes more important. decisions with the Working Group mailing list becomes more important.
Gaining Working Group consensus about the resolution of issues can be Chairs can declare Working Group consensus about the resolution of
done in the abstract, with editors being permitted to capture the issues in the abstract, allowing editors discretion on how to capture
outcome of discussions as they see fit. the decisions in documents.
More mature documents require not only consensus, but consensus about More mature documents require not only consensus, but consensus about
specific text. All substantive changes to documents that have passed specific text. Ideally, substantive changes to documents that have
WGLC SHOULD be proposed as pull requests, and MUST be discussed on passed WGLC are proposed as pull requests, and MUST be discussed on
the mailing list, and MUST have chairs explicitly confirm consensus. the mailing list. Having chairs explicitly confirm consensus on
Chairs MAY institute this stricter process prior to WGLC. changes ensures that previous consensus decisions are not overturned
without cause. Chairs MAY institute this stricter process prior to
WGLC.
Note: It is generally sufficient to trust editors to manage Note: It is generally sufficient to trust editors to manage
adherence with these policies, aided by the transparency provided adherence with these policies, aided by the transparency provided
by the version control system. There are tools that can be used by the version control system. There are tools that can be used
to more tightly control access to repositories, but they can be to more tightly control access to repositories, but they can be
overly constraining. overly constraining.
5.4. Issue Labelling Schemes 5.4. Issue Labelling Schemes
Several schemes for use of issue labels in managing issues have been Several schemes for use of issue labels in managing issues have been
used successfully. This section outlines these strategies and how used successfully. This section outlines these strategies and how
they might be applied. they might be applied.
A design/editorial split (see Section 5.4.1) is useful in all cases A design/editorial split (see Section 5.4.1) is useful in all cases
that the issue tracking capability is used. Working Groups that only that the issue tracking capability is used. A Working Groups that
use GitHub for issue tracking might find that distinction sufficient only uses GitHub for issue tracking might find that distinction
for their needs. sufficient for their needs.
Working Groups or editors might use additional labels as they choose. Working Groups or editors might use additional labels as they choose.
Any label that is used as part of a process requires that the process Any label that is used as part of a process requires that the process
be documented and announced by Working Group chairs. Editors SHOULD be documented and announced by Working Group chairs. Editors SHOULD
be permitted to use labels to manage issues without any formal be permitted to use labels to manage issues without any formal
process significance being attached to those issues. process significance being attached to those issues.
5.4.1. Editorial/Design Labelling 5.4.1. Editorial/Design Labelling
The most important distinction about an issue is whether it is The most important distinction about an issue is whether it is
skipping to change at page 18, line 10 skipping to change at page 18, line 46
error. error.
* A "blocked" label might indicate an issue is awaiting resolution * A "blocked" label might indicate an issue is awaiting resolution
of an external process or related issue. of an external process or related issue.
* A "parked" label might be used to indicate issues that do not * A "parked" label might be used to indicate issues that do not
require immediate Working Group attention. require immediate Working Group attention.
6. Internet-Draft Publication 6. Internet-Draft Publication
During the development of a document, individual revisions of a During the development of a document, individual revisions of the
document can be built and formally submitted as an Internet-Draft. document can be built and formally submitted as an Internet-Draft.
This creates a stable snapshot and makes the content of the in- This creates a stable snapshot and makes the content of the in-
progress document available to a wider audience. Documents submitted progress document available to a wider audience. Documents submitted
as Internet-Drafts are not expected to address all open issues or as Internet-Drafts are not expected to address all open issues or
merge outstanding pull requests. merge outstanding pull requests.
Editors SHOULD create a new Internet-Draft submission two weeks prior Section 7.1 of [RFC2418] recommends that editors create a new
to every session, which includes IETF meetings, other in-person Internet-Draft submission two weeks prior to every session, which
meetings, and telephone or video conferences (see Section 7.1 of includes IETF meetings, other in-person meetings, and telephone or
[RFC2418]). Though discussion could use the current version of a video conferences. Though discussion could use the current version
document from version control, participants in a session cannot be of a document from version control, participants in a session cannot
expected to monitor changes to documents in real-time; a published be expected to monitor changes to documents in real-time; a published
Internet-Draft ensures that there is a common, stable state that is Internet-Draft ensures that there is a common, stable state that is
known to all participants. known to all participants.
Internet-Drafts that use a GitHub repository SHOULD include a notice Internet-Drafts that use a GitHub repository SHOULD include a notice
that includes a reference to the repository. This notice might also that includes a reference to the repository. This notice might also
include information about where to discuss the draft. include information about where to discuss the draft.
Revisions used to generate documents that are submitted as Internet- Revisions used to generate documents that are submitted as Internet-
Drafts SHOULD be tagged in repositories to provide a record of Drafts SHOULD be tagged in repositories to provide a record of
submissions. submissions.
skipping to change at page 19, line 5 skipping to change at page 19, line 41
GitHub facilitates more involved interactions, which can result in a GitHub facilitates more involved interactions, which can result in a
much higher level of activity than a typical Working Group mailing much higher level of activity than a typical Working Group mailing
list. Participants who wish to limit their time commitment might list. Participants who wish to limit their time commitment might
follow GitHub activity selectively, either by following only specific follow GitHub activity selectively, either by following only specific
issues or by occasionally reviewing the state of the document. Other issues or by occasionally reviewing the state of the document. Other
participants might not use GitHub at all. Chairs are reminded that participants might not use GitHub at all. Chairs are reminded that
assessing consensus based on GitHub content alone cannot be assumed assessing consensus based on GitHub content alone cannot be assumed
to reach all interested participants. to reach all interested participants.
Chairs MUST consider input from all discussion venues when assessing As described in [RFC2418], chairs consider input from all discussion
consensus including GitHub, mailing lists, interim meetings, and IETF venues when assessing consensus. These include mailing lists, IETF
meetings. Each venue has different selection biases that might need meetings, and interim meetings in addition to discussion on GitHub.
to be considered. Each venue has different selection biases that might need to be
considered.
A Working Group chair MUST consult the Working Group mailing list for A Working Group chair MUST consult the Working Group mailing list for
any issue that is potentially contentious. Relying on input provided any issue that is potentially contentious. Relying on input provided
through GitHub alone might result in gaining input from a narrower through GitHub alone might result in gaining input from a narrower
set of participants. This includes important milestones like Working set of participants. This includes important milestones like Working
Group Last-Call, where review from the widest possible audience Group Last-Call, where review from the widest possible audience
ensures a higher quality document. ensures a higher quality document.
If permitted, GitHub will be used for technical discussion and If permitted, GitHub will be used for technical discussion and
decisions, especially during early stages of development of a decisions, especially during early stages of development of a
document. Any decisions are ultimately confirmed through review, and document. Any decisions are confirmed through review within the
ultimately, through Working Group Last Call (see Section 7.4 of Working Group, and ultimately, through Working Group Last Call; see
[RFC2418]). Section 7.4 of [RFC2418].
The use of issues and labels has been effective in managing The use of issues and labels has been effective in managing
contentious issues. Explicitly labeling closed issues to identify contentious issues. Explicitly labeling closed issues to identify
those with formal consensus means that there is no confusion about those with formal consensus means that there is no confusion about
the status of issues. the status of issues.
8. Continuous Integration 8. Continuous Integration
Various third-party services offer the ability to run tests and other Various third-party services offer the ability to run tests and other
work when changes are made to a repository. work when changes are made to a repository.
skipping to change at page 20, line 47 skipping to change at page 21, line 35
10. Security Considerations 10. Security Considerations
Continuity of operations is always a consideration when taking a Continuity of operations is always a consideration when taking a
dependency on an external service. If GitHub were to fail in some dependency on an external service. If GitHub were to fail in some
way, anyone relying upon its services would be seriously affected. way, anyone relying upon its services would be seriously affected.
Widespread use of git reduces the exposure to a system failure Widespread use of git reduces the exposure to a system failure
because the primary repository is replicated in multiple locations. because the primary repository is replicated in multiple locations.
This includes hosted web pages; the content of web pages is This includes hosted web pages; the content of web pages is
maintained as a branch in the main repository. As specified in maintained as a branch in the main repository.
[GH-CONFIG], maintaining a mirror of a repository hosted on GitHub
provides IETF-hosted backups for WG repositories.
However, other information maintained on GitHub is more vulnerable to However, other information maintained on GitHub is more vulnerable to
loss. This includes issues and discussion on those issues, loss. This includes issues and discussion on those issues,
discussion and reviews of commits and pull requests, and any content discussion and reviews of commits and pull requests, and any content
hosted on the wiki. Tools exist for extracting this information for hosted on the wiki. Tools exist for extracting this information for
backup. backup.
As specified in [GH-CONFIG], backup copies of repositories and other
important data SHOULD be maintained.
The potential for malicious actions by compromised or malcontent The potential for malicious actions by compromised or malcontent
editors, chairs and area directors is relevant in maintaining the editors, chairs and area directors is relevant in maintaining the
integrity of the content that GitHub hosts. Backups allow for integrity of the content that GitHub hosts. Backups allow for
recovery of content, and regular submissions as Internet-Drafts recovery of content, and regular submissions as Internet-Drafts
ensure that work is not lost completely. ensure that work is not lost completely.
A compromise of GitHub does not pose a significant threat to Working
Group operations as it is expected that most data, aside from
individual credentials, is made public.
Compromise of credentials could mean loss of control for repositories
and organizations. All contributors, especially those with commit or
admin privileges SHOULD use current best practices for protection of
credentials, such as multi-factor authentication.
11. IANA Considerations 11. IANA Considerations
This document has no IANA actions. This document has no IANA actions.
12. References 12. References
12.1. Normative References 12.1. Normative References
[GH-CONFIG]
Cooper, A. and P. Hoffman, "Working Group GitHub
Administration", Work in Progress, Internet-Draft, draft-
ietf-git-github-wg-configuration-06, 13 February 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-git-
github-wg-configuration-06.txt>.
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996,
<https://www.rfc-editor.org/info/rfc2026>. <https://www.rfc-editor.org/info/rfc2026>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC2418] Bradner, S., "IETF Working Group Guidelines and [RFC2418] Bradner, S., "IETF Working Group Guidelines and
Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418, Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418,
September 1998, <https://www.rfc-editor.org/info/rfc2418>. September 1998, <https://www.rfc-editor.org/info/rfc2418>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
12.2. Informative References 12.2. Informative References
[GH-CONFIG]
Cooper, A. and P. Hoffman, "Working Group GitHub
Administration", Work in Progress, Internet-Draft, draft-
ietf-git-github-wg-configuration-06, 13 February 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-git-
github-wg-configuration-06.txt>.
[GLOSSARY] GitHub, "GitHub glossary", March 2020,
<https://help.github.com/en/github/getting-started-with-
github/github-glossary>.
[RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
RFC 7991, DOI 10.17487/RFC7991, December 2016, RFC 7991, DOI 10.17487/RFC7991, December 2016,
<https://www.rfc-editor.org/info/rfc7991>. <https://www.rfc-editor.org/info/rfc7991>.
Acknowledgments Acknowledgments
This work would not have been possible without the hard work of those This work would not have been possible without the hard work of those
people who have trialled use of GitHub at the IETF. Alia Atlas people who have trialled use of GitHub at the IETF. Alia Atlas
contributed significant text to an earlier version of this document. contributed significant text to an earlier version of this document.
Tommy Pauly, Rich Salz, and Christopher Wood all provided significant Tommy Pauly, Rich Salz, and Christopher Wood all provided significant
 End of changes. 67 change blocks. 
191 lines changed or deleted 230 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/