doc: Add RFC documents

1 files changed, 1048 insertions, 0 deletions

diff --git a/doc/rfc/rfc8874.txt b/doc/rfc/rfc8874.txt
new file mode 100644
index 0000000..a6b7298
--- /dev/null
+++ b/doc/rfc/rfc8874.txt
@@ -0,0 +1,1048 @@
+
+
+
+
+Internet Engineering Task Force (IETF)                        M. Thomson
+Request for Comments: 8874                                       Mozilla
+Category: Informational                                         B. Stark
+ISSN: 2070-1721                                                     AT&T
+                                                             August 2020
+
+
+                  Working Group GitHub Usage Guidance
+
+Abstract
+
+   This document provides a set of guidelines for working groups that
+   choose to use GitHub for their work.
+
+Status of This Memo
+
+   This document is not an Internet Standards Track specification; it is
+   published for informational purposes.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Not all documents
+   approved by the IESG are candidates for any level of Internet
+   Standard; see Section 2 of RFC 7841.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   https://www.rfc-editor.org/info/rfc8874.
+
+Copyright Notice
+
+   Copyright (c) 2020 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (https://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+Table of Contents
+
+   1.  Introduction
+     1.1.  Distributed Version Control Systems
+     1.2.  GitHub
+     1.3.  Other Services
+     1.4.  Document Goals
+     1.5.  Notational Conventions
+   2.  Administrative Policies
+     2.1.  Organizations
+     2.2.  Communicating Policies
+   3.  Deciding to Use GitHub
+     3.1.  What to Use GitHub For
+     3.2.  Repositories
+     3.3.  Editors and Contributors
+     3.4.  Document Formats
+   4.  Contribution Methods
+     4.1.  Issue Tracker
+       4.1.1.  Issue Labels
+       4.1.2.  Closing Issues
+       4.1.3.  Reopening Issues
+     4.2.  Pull Requests
+       4.2.1.  Discussion on Pull Requests
+       4.2.2.  Merging Pull Requests
+     4.3.  Monitoring Activity
+   5.  Typical Working Group Policies
+     5.1.  Document Management Mode
+     5.2.  Issue Tracking Mode
+     5.3.  Issue Discussion Mode
+       5.3.1.  Early Design Phases
+       5.3.2.  Managing Mature Documents
+     5.4.  Issue Labeling Schemes
+       5.4.1.  Editorial/Design Labeling
+       5.4.2.  Decision Labeling
+       5.4.3.  Component Labeling
+       5.4.4.  Other Labels
+   6.  Internet-Draft Publication
+   7.  Assessing Consensus
+   8.  Continuous Integration
+   9.  Advice to Editors
+   10. Security Considerations
+   11. IANA Considerations
+   12. References
+     12.1.  Normative References
+     12.2.  Informative References
+   Acknowledgments
+   Authors' Addresses
+
+1.  Introduction
+
+   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 a working
+   group needs to produce documents and to improve the quality of the
+   final result.
+
+   The use of version control improves the traceability and visibility
+   of changes.  Issue tracking can be used to manage open issues and
+   provide a record of their resolution.  Pull requests allow for better
+   engagement on technical and 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 to provide guidelines for how a
+   working group might integrate the capabilities provided by GitHub
+   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
+   practices.  It provides guidance to working group chairs and
+   participants on how they can best use GitHub within the framework
+   established by RFC 2418 [RFC2418].  This document aims to establish
+   norms that reduce the variation in usage patterns between different
+   working groups and to help avoid issues that have been encountered in
+   the past.
+
+   A companion document, [RFC8875], describes administrative processes
+   that support the practices described in this document.
+
+   Although the operation of IRTF research groups can be similar in
+   function to working groups, this document only directly addresses the
+   needs of working groups.  However, other groups may draw inspiration
+   for GitHub use from the contents herein.
+
+1.1.  Distributed Version Control Systems
+
+   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 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.
+
+1.2.  GitHub
+
+   GitHub is a service operated at <https://github.com/>.  GitHub
+   provides centralized storage for Git repositories.  GitHub is freely
+   accessible on the open Internet.
+
+   GitHub provides a simplified and integrated interface to Git and also
+   provides basic user management, an issue tracker, associated wikis,
+   project hosting, and other features.
+
+   There are a large number of projects at GitHub and a very large
+   community of contributors.  One way in which some IETF working groups
+   have benefited from use of the service is through increased numbers
+   of reviews of the document and associated issues, along with other
+   improvements that come from facilitating participation by a broader
+   community.
+
+1.3.  Other Services
+
+   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 as GitHub.  For instance, BitBucket (https://bitbucket.org/)
+   and GitLab (https://about.gitlab.com/) provide similar feature sets.
+   In addition to a hosted service, software for custom installations
+   exists.
+
+   This document concentrates primarily on GitHub as it has a large and
+   active community of contributors.  As a result, some content might
+   not be applicable to other similar services.  A working group that
+   decides to adopt an alternative tool or service can still benefit
+   from the general guidance in this document.
+
+1.4.  Document Goals
+
+   This document aims to describe how a working group might best apply
+   GitHub to their work.  The intent is to allow each working group
+   considerable flexibility in how they use GitHub.
+
+   This document requires that policies for use of GitHub are agreed
+   upon and clearly communicated within the working group (see
+   Section 2).  The remainder of the document contains guidelines and
+   advice on how to construct a workable policy.
+
+   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 GitHub.
+
+   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.  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.
+
+1.5.  Notational Conventions
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+   "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
+
+   The following administrative rules provide the necessary oversight
+   and transparency.
+
+2.1.  Organizations
+
+   Organizations are a way of forming groups of contributors on GitHub.
+   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 [RFC8875].
+
+   A single organization SHOULD NOT be used for all IETF activity or all
+   activity within an area.  Large organizations create too much
+   overhead for general management tasks.
+
+   GitHub requires that each organization have at least one owner.  The
+   owners for a working group repository MUST include responsible area
+   directors and the IETF Secretariat.  Working group chairs SHOULD also
+   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 two owners.
+
+   Within an organization, members can be grouped into teams.  A team
+   with "Admin" access to repositories SHOULD be created for the working
+   group chairs and any working group secretary.
+
+   Details about creating organizations adhering to these guidelines can
+   be found in [RFC8875].
+
+2.2.  Communicating Policies
+
+   Each working group MAY set its own policy as to whether and how it
+   uses GitHub.  It is important that occasional participants in the
+   working group and others accustomed to IETF tools be able to
+   determine this and easily find the policy and GitHub organization.
+
+   A simple example of how to do this is to include a link to the GitHub
+   organization on the working group charter page in the datatracker.
+   Similarly, if there are additional resources, such as mailing lists,
+   links to those resources could also be added.
+
+   Repositories MUST include a copy of or reference to the policy that
+   applies to managing any documents they contain.  Updating the README
+   or CONTRIBUTING file in the repository with details of the process
+   ensures that the process is recorded in a stable location other than
+   the mailing list archive.  This also makes working group policies
+   available to casual contributors who might only interact with the
+   GitHub repository.
+
+   GitHub prominently links to the CONTRIBUTING file on certain pages.
+   This file SHOULD be used in preference to the README for information
+   that new contributors need.  The README SHOULD contain a link to the
+   CONTRIBUTING file.
+
+   In addition to working group policies, notices on repositories MUST
+   include citations for the IETF Note Well (https://www.ietf.org/about/
+   note-well/).
+
+3.  Deciding to Use GitHub
+
+   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 for making a consensus call about
+   whether the proposed policy and use is acceptable.
+
+   Chairs SHOULD involve area directors in any decision to use GitHub,
+   especially where substantive discussion of issues is permitted as
+   described in Section 5.3.
+
+3.1.  What to Use GitHub For
+
+   Working group chairs decide what GitHub features the working group
+   will rely upon.  Section 4 contains a more thorough discussion on the
+   different features that can be used.
+
+   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.
+
+   Working group chairs are responsible for ensuring that any policy
+   they adopt is enforced and maintained.
+
+   The set of GitHub features (Section 4) that the working group relies
+   upon need to be clearly documented in policies.  This document
+   provides some guidance on potential policies and how those might be
+   applied.
+
+   Features that the working group does not rely upon can be made
+   available to document editors.  Editors are then able to use these
+   features for their own purposes.  For example, though the working
+   group might not formally use issues to track items that require
+   further discussion in order to reach consensus, keeping the issue
+   tracker available to editors can be valuable.
+
+   Working group policies need to be set with the goal of improving
+   transparency, participation, and ultimately the quality of 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 are encouraged to periodically consult with document editors
+   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 such public repository MUST follow the IETF Note
+   Well and bear notices; see Section 2.2.  This recognizes that editors
+   have traditionally chosen their own methods for managing the
+   documents they edit but preserves the need for contributors to
+   understand their obligations with respect to IETF processes.
+
+   Work done in GitHub has no special status.  The output of any
+   activity using GitHub needs to be taken to the working group and is
+   subject to approval, rejection, or modification by the working group
+   as with any other input.
+
+3.2.  Repositories
+
+   New repositories can be created within the working group organization
+   at the 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.
+
+   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 status (that is, draft-ietf-<wgname>-... indicates
+   that the document was adopted) or through a prominent notice (such as
+   in the README).
+
+   Experience has shown that maintaining separate repositories for
+   independent documents is most manageable.  This allows the work in
+   that repository to be focused on a single item.
+
+   Closely related documents, such as those that together address a
+   single milestone, might be placed in a single repository.  This
+   allows editors to more easily manage changes and issues that affect
+   multiple documents.
+
+   Maintaining multiple documents in the same repository can add
+   overhead that negatively affects individual documents.  For instance,
+   issues might require additional markings to identify the document
+   that they affect.  Also, because editors all have write access to the
+   repository, managing the set of people with write access to a larger
+   repository is more difficult (Section 3.3).
+
+3.3.  Editors and Contributors
+
+   Working group chairs MUST give document editors write access to
+   document repositories.  This can be done by creating teams with write
+   access and allocating editors to those teams or by making editors
+   collaborators on the repository.
+
+   Working group chairs MAY also grant other individuals write access
+   for other reasons such as maintaining supporting code or build
+   configurations.  Working group chairs, as administrators or owners of
+   the organization, might also have write access to repositories.
+   Users other than document editors, including chairs, SHOULD NOT make
+   changes to working group documents without prior coordination with
+   document editors.
+
+   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 tasks to
+   individuals outside of the editor team.
+
+3.4.  Document Formats
+
+   In addition to the canonical XML format [RFC7991], document editors
+   might choose to use a different input form for editing documents,
+   such as Markdown.  Markdown-based formats are more accessible for new
+   contributors, though ultimately, decisions about format are left to
+   document editors.
+
+   Formats that are not text-based SHOULD NOT be used, as these are ill-
+   disposed to the sorts of interaction that revision control enables.
+
+4.  Contribution Methods
+
+   Contributions to documents come in many forms.  GitHub provides a
+   range of options in addition to email.  Input on GitHub can take the
+   form of new issues and pull requests, comments on issues and pull
+   requests, and comments on commits.
+
+4.1.  Issue Tracker
+
+   The GitHub issue tracker can be an effective way of managing the set
+   of open issues on a document.  Issues, both open and closed, can be a
+   useful way of recording decisions made by a working group.
+
+   Issues can be given arbitrary labels, assigned to contributors, and
+   assembled into milestones.  The issue tracker is integrated into the
+   repository; an issue can be closed using a special marker in a commit
+   message.
+
+   When deciding to use GitHub, working group chairs MUST decide how the
+   GitHub issue tracker is used.  Use of the issue tracker could be
+   limited to recording the existence of issues, or it might be used as
+   the venue for substantial technical discussion between contributors.
+
+   A working group policy MAY require that all substantive changes be
+   tracked using issues.  Suggested policies for the use of the GitHub
+   issue tracker are the primary subject of Section 5.
+
+4.1.1.  Issue Labels
+
+   A system of labeling issues can be effective in managing issues.  For
+   instance, marking substantive issues separately from editorial can be
+   helpful at guiding discussion.  Using labels can also be helpful in
+   identifying issues for which consensus has been achieved but that
+   require editors to integrate the changes into a document.
+
+   Labels can be used to identify particular categories of issues or to
+   mark specific issues for discussion at an upcoming session.
+
+   Chairs communicate any process that specifically relates to the use
+   of labels to the working group.  This includes the semantics of
+   labels, and who can apply and remove these labels.  Section 5.4
+   describes some basic strategies that might be adopted to manage
+   decision-making processes.
+
+4.1.2.  Closing Issues
+
+   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
+   issue.  Chairs MUST provide guidance on who is permitted to close an
+   issue and under what conditions.
+
+   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.
+
+4.1.3.  Reopening Issues
+
+   Issues that have reached a resolution that has working group
+   consensus MUST NOT be reopened unless new information is presented.
+
+   For long-running work items, new contributors often raise issues that
+   have already been resolved.  Moreover, there could be temptation to
+   reopen contentious issues resolved with rough consensus.  Determining
+   whether arguments presented in favor of reopening an issue represents
+   new information might require some discussion in the working group.
+
+   Chairs are empowered to exercise discretion in determining whether or
+   not 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
+
+   A pull request is a GitHub feature that allows a user to request a
+   change to a repository.  A user does not need to have write access to
+   a repository to create a pull request.  A user can create a "fork",
+   or copy, of any public repository.  The user has write access to
+   their own fork, allowing them to make local changes.  A pull request
+   asks the owner of a repository to merge a specific set of changes
+   from a fork (or any branch) into their copy.
+
+   Editors are encouraged to make pull requests for all substantial
+   changes rather than committing directly to the "primary" branch of
+   the repository.  See Section 5.3.2 for discussion on what constitutes
+   a substantial change.  A pull request creates an artifact that
+   records the reasons for changes and provides other contributors with
+   an opportunity to review the change.  Ideally, pull requests that
+   address substantive issues mention the issue they address in the
+   opening comment.  A working group policy could require that pull
+   requests be used in this fashion.
+
+      |  Note: This document assumes that there is a unified effort on a
+      |  document, all concentrated on a single Git branch.  More
+      |  advanced usage of Git is not in the scope of this document.
+
+   Pull requests have many of the same properties as issues, including
+   the ability to host discussion and bear labels.  Critically, using
+   pull requests creates a record of actions taken.
+
+   For significant changes, leaving a pull request open until discussion
+   of the issue within the working group concludes allows the pull
+   request to track the discussion and properly capture the outcome of
+   discussions.  Pull requests can be updated as discussions continue,
+   or in response to feedback.
+
+   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.
+
+4.2.1.  Discussion on Pull Requests
+
+   In addition to the features that pull requests share with issues,
+   users can also review the changes in a pull request.  This is a
+   valuable feature, but it presents 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
+   discussions closely.
+
+   For this reason, working group chairs SHOULD discourage the use of
+   inline comments for substantial technical discussion of issues.
+
+4.2.2.  Merging Pull Requests
+
+   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.
+
+   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
+   every point in time.  Document editors need some flexibility in how
+   they manage a document.
+
+4.3.  Monitoring Activity
+
+   GitHub produces individualized email notifications of activity that
+   each user can adjust to their preferences.  In addition to these,
+   some working groups have created read-only mailing lists that receive
+   notifications about activity on working group repositories.  The
+   volume of information on these lists can be too high to monitor
+   actively, but access to an archive of actions can be useful.
+
+   An alternative is to rely on periodic email summaries of activity,
+   such as those produced by a notification tool like github-notify-ml
+   (https://github.com/dontcallmedom/github-notify-ml).  This tool has
+   been used effectively in several working groups, though it requires
+   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
+
+   Current experience with use of GitHub suggests a few different
+   approaches to greater use of the tool in working groups.
+
+   This section describes some basic modes for interacting with GitHub,
+   each progressively more involved.  This starts with a very
+   lightweight interaction where document management is the only feature
+   that is formally used; then, progressively more intensive use of the
+   GitHub issue tracking capabilities is 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.
+
+   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
+
+   In this mode of interaction, GitHub repositories are used to manage
+   changes to documents, but the bulk of the work is conducted using
+   email, face-to-face meetings, and other more traditional
+   interactions.  The intent of this policy is to enable document and
+   issue management using GitHub while minimizing the complexity of the
+   process.
+
+   In the version of this mode with the least interaction with GitHub, a
+   repository is created for the purposes of document management by
+   editors.  Editors might maintain issues and pull requests for their
+   own benefit, but these have no formal standing in the working group
+   process.
+
+5.2.  Issue Tracking Mode
+
+   In addition to managing documents, the working group might choose to
+   use GitHub for tracking outstanding issues.  In this mode of
+   interaction, a record of the existence of substantive technical
+   discussions is tracked using issues in the issue tracker.  However,
+   discussion of any substantial matters is always conducted on mailing
+   lists.
+
+   Under this mode, issues and pull requests can be opened by anyone,
+   but anything deemed substantive MUST be resolved exclusively on the
+   mailing list.  Discussion on GitHub is limited to recording the state
+   of issues.  Only editorial matters can be resolved using the issue
+   tracker.
+
+   Chairs and editors are given discretion in determining what issues
+   are substantive.  As documents mature, it is generally prudent to
+   prefer consulting the mailing list where there is doubt.  As with
+   other working group decisions, chairs are the arbiters in case of
+   dispute.
+
+   A recurrent problem with this mode of interaction is the tendency for
+   discussions to spontaneously develop in the issue tracker.  This
+   requires a degree of discipline from chairs and editors to ensure
+   that any substantive matters are taken to the mailing list.
+
+   Retaining mailing lists as the primary venue for discussion of
+   substantive matters ensures that this mode, along with the document
+   management mode, is most compatible with existing work practices for
+   working groups.  Participants in a working group that operates under
+   either model can reasonably be expected to receive all relevant
+   communication about the work of the group from the working group
+   mailing list.
+
+   Though the mailing list is used for making decisions, the issue
+   tracker can still be a useful record of the state of issues.  It is
+   often useful if chairs or editors record details of decisions in
+   issue comments when closing issues as resolved.
+
+5.3.  Issue Discussion Mode
+
+   This GitHub interaction mode differs from the other modes in that
+   discussion relating to substantive technical matters is allowed to
+   occur on GitHub issues.  Though decisions are always subject to
+   confirmation on the mailing list, participants are permitted to
+   conduct substantive discussions on the issue tracker.  In some cases,
+   this can include making some decisions without involving the working
+   group mailing list.
+
+   A working group mailing list remains a critical venue for decision
+   making, even where issue discussion occurs elsewhere.  Working group
+   mailing lists generally include a wider audience than those who
+   follow issue discussion, so difficult issues always benefit from list
+   discussion.
+
+   Decisions about working group consensus MUST always be confirmed
+   using the working group mailing list.  However, depending on the
+   maturity of documents, this might be a more lightweight interaction
+   such as sending an email confirmation for an initial set of
+   resolutions arising from discussions on the issue tracker.
+
+   Using the mailing list to resolve difficult or controversial issues
+   is strongly encouraged.  In those cases, the issue tracker might be
+   used to more fully develop an understanding of problems before
+   initiating a discussion on the mailing list, along lines similar to
+   the design team process (see Section 6.5 of [RFC2418]).
+
+   As a more involved process, adopting this mode can require changes in
+   policies as documents become more mature.
+
+5.3.1.  Early Design Phases
+
+   During early phases of the design of a protocol, chairs MAY allow
+   editors to manage all aspects of issues.  Editors are permitted to
+   make decisions about how to both identify and resolve technical
+   issues, including making any changes that editors feel necessary.
+
+   The primary reason to grant editors more discretionary power is to
+   improve the speed with which changes can be made.  In many cases,
+   documents that are adopted by a working group are already
+   sufficiently mature, and a looser process is not beneficial.  A
+   looser process increases the risk of missing issues that need working
+   group consensus and integrating substantive changes based on
+   decisions that don't reflect the consensus of the working group.
+
+   Changes made by editors under this process do not lack options for
+   identifying and correcting problems.  GitHub and Git provide tools
+   for ensuring that changes are tracked and can be audited.  Within the
+   usual working group process, it is expected that Internet-Drafts will
+   receive regular review.  Also, process checkpoints like Working Group
+   Last Call (WGLC; Section 7.4 of [RFC2418]) provide additional
+   safeguards against abuse.
+
+   Working groups are advised against allowing editors this degree of
+   flexibility for the entirety of a document life cycle.  Once a
+   document is more stable and mature, it could be useful to move to a
+   more tightly controlled process.
+
+5.3.2.  Managing Mature Documents
+
+   As a document matures, it becomes more important to understand not
+   just that the document as a whole retains the support of the working
+   group, but that changes are not made without wider consultation.
+
+   Chairs MAY choose to manage the process of deciding which issues are
+   substantive.  For instance, chairs might reserve the ability to use
+   the "design" label for new issues (see Section 5.4.1) and to close
+   issues marked as "design".  Chairs SHOULD always allow document
+   editors to identify and address editorial issues as they see fit.
+
+   As documents mature further, explicit confirmation of technical
+   decisions with the working group mailing list becomes more important.
+
+   Chairs can declare working group consensus regarding 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 proposed as pull requests and MUST be discussed on
+   the mailing list.  Having chairs explicitly confirm consensus on
+   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
+      |  adherence with these policies, aided by the transparency
+      |  provided by the version control system.  There are tools that
+      |  can be used to more tightly control access to repositories, but
+      |  they can be overly constraining.
+
+5.4.  Issue Labeling Schemes
+
+   Several schemes for use of issue labels in managing issues have been
+   used successfully.  This section outlines these strategies and how
+   they might be applied.
+
+   A design/editorial split (see Section 5.4.1) is useful in all cases
+   in which the issue tracking capability is used.  A working group 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 that is used as part of a process requires that the process
+   be documented and announced by working group chairs.  Editors SHOULD
+   be permitted to use labels to manage issues without any formal
+   process significance being attached to those issues.
+
+5.4.1.  Editorial/Design Labeling
+
+   The most important distinction about an issue is whether it is
+   substantive.  The labels of "editorial" and "design" are used to
+   represent this distinction.
+
+   An issue labeled as "editorial" has no substantive effect on a
+   document except to the extent that addressing the issue might make
+   understanding the specification easier.  Resolution of "editorial"
+   issues can be left to the discretion of editors.
+
+   An issue labeled as "design" has or might have a substantive effect
+   on a document.  For protocol specifications, a "design" issue is one
+   that might affect implementations or interoperability requirements.
+   Addressing a "design" issue ultimately requires working group
+   consensus, even if the resolution is to make no change.
+
+   This distinction can be applied to all types of documents.  For
+   instance, a "design" issue for an Informational document might be
+   raised to discuss possible changes to important concepts in the
+   document.
+
+5.4.2.  Decision Labeling
+
+   Labels can be used to manage processes.  As documents mature and
+   issues become more numerous, labels can be used to clearly mark the
+   status of issues.  In particular, the labeling of issues can be used
+   to help manage working group decisions.
+
+   For documents that are less mature, issues with resolutions but no
+   specific proposals for changes to text might be marked "editor-ready"
+   as a way of signaling that there is consensus on an approach, but no
+   specific proposal.  Chairs might use this to signal that discussion
+   is complete and that editors are to be given discretion in the
+   construction of text.
+
+   In contrast, if specific text is a prerequisite for resolving issues,
+   as might be the case for more mature documents, a "proposal-ready"
+   label might be used by editors to mark issues that they believe to
+   have acceptable resolutions.
+
+   For resolved issues, a "has-consensus" label might be used by chairs
+   to mark issues for which formal working group decisions have been
+   made (Section 6.1 of [RFC2418]).
+
+   A "future" or "next-version" label might be used to mark and thereby
+   save issues for a future version of, or extension to, a protocol,
+   particularly where a resolution is made to take no action.
+
+5.4.3.  Component Labeling
+
+   Repositories with multiple interrelated documents or a complex
+   document with multiple logical components might benefit from labels
+   that identify different aspects of the work.  The choice of
+   appropriate labels for components will depend on the structure of
+   specific documents.
+
+5.4.4.  Other Labels
+
+   Other labels can be used depending on the needs of editors and
+   working group processes.  For example,
+
+   *  An "invalid" label might be used for issues that were raised in
+      error.
+
+   *  A "blocked" label might indicate an issue is awaiting resolution
+      of an external process or related issue.
+
+   *  A "parked" label might be used to indicate issues that do not
+      require immediate working group attention.
+
+6.  Internet-Draft Publication
+
+   During the development of a document, individual revisions of the
+   document can be built and formally submitted as an Internet-Draft.
+   This creates a stable 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.
+
+   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
+   known to all participants.
+
+   Internet-Drafts that use a GitHub repository SHOULD include a notice
+   that includes a reference to the repository.  This notice might also
+   include information about where to discuss the draft.
+
+   Revisions used to generate documents that are submitted as Internet-
+   Drafts SHOULD be tagged in repositories to provide a record of
+   submissions.
+
+   Working group chairs MAY request a revision of an Internet-Draft
+   being managed on GitHub at any time, in consultation with document
+   editors.
+
+7.  Assessing Consensus
+
+   The work that occurs on GitHub could be part of the consensus
+   process, but the ultimate decision on consensus regarding a document
+   is made by the chairs [RFC2026].
+
+   GitHub facilitates more involved interactions, which can result in a
+   much higher level of activity than a typical working group mailing
+   list.  Participants who wish to limit their time commitment might
+   follow GitHub activity selectively, either by following only specific
+   issues or by occasionally reviewing the state of the document.  Other
+   participants might not use GitHub at all.  Chairs are reminded that
+   assessing consensus based on GitHub content alone cannot be assumed
+   to reach all interested participants.
+
+   As described in [RFC2418], chairs consider input from all discussion
+   venues when assessing consensus.  These include mailing lists, IETF
+   meetings, and interim meetings in addition to discussion on GitHub.
+   Each venue has different selection biases that might need to be
+   considered.
+
+   A working group chair MUST consult the working group mailing list for
+   any issue that is potentially contentious.  Relying on input provided
+   through GitHub alone might result in gaining input from a narrower
+   set of participants.  This includes important milestones like Working
+   Group Last Call, where review from the widest possible audience
+   ensures a higher quality document.
+
+   If permitted, GitHub will be used for technical discussion and
+   decisions, especially during early stages of development of a
+   document.  Any decisions are confirmed through review within the
+   working group and, ultimately, through Working Group Last Call; see
+   Section 7.4 of [RFC2418].
+
+   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.
+
+8.  Continuous Integration
+
+   Various third-party services offer the ability to run tests and other
+   work when changes are made to a repository.
+
+   One common practice is to use these continuous integration services
+   to build a text or HTML version of a document.  This is then
+   published to GitHub Pages, which allows users to view a version of
+   the most recent revision of a document.  Including a prominent link
+   to this version of the document (such as in the README) makes it
+   easier for new contributors to find a readable copy of the most
+   recent version of a draft.  In addition, including links to
+   differences between this generated version and any published document
+   helps contributors identify recent changes.
+
+   Continuous integration can also validate pull requests and other
+   changes for errors.  The most basic check is whether the source file
+   can be transformed successfully into a valid Internet-Draft.  For
+   example, this might include checking that the XML source is
+   syntactically correct.
+
+   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.
+
+9.  Advice to Editors
+
+   Document editors are primarily responsible for maintaining documents.
+   Taking on a few additional tasks can greatly improve the process for
+   the working group.
+
+   Using GitHub means that it is more likely that a contribution is made
+   by users who are not very familiar with the work.  Pull requests from
+   new contributors can contain errors or omissions.  Duplicate issues
+   are commonplace.  Proposed changes might have grammatical errors or
+   they might diverge from existing style.  If a change is generally
+   sound, rather than rejecting the pull request or requesting changes,
+   editors could instead accept the change and then make any necessary
+   corrections.
+
+   Editors SHOULD NOT close a pull request or issue without first
+   understanding why the item was created.  Editors and chairs SHOULD
+   try to explain every action clearly and concisely.  Even if a
+   contributor seems rude, being courteous in response is always best.
+
+   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.
+
+   This takes a little more effort, but these simple steps can help
+   encourage contributions, which will ultimately improve the quality of
+   documents.
+
+10.  Security Considerations
+
+   Continuity of operations is always a consideration when taking a
+   dependency on an external service.  If GitHub were to fail in some
+   way, anyone relying upon its services would be seriously affected.
+
+   Widespread use of Git reduces the exposure to a system failure
+   because the primary repository is replicated in multiple locations.
+   This includes hosted web pages; the content of web pages is
+   maintained as a branch in the main repository.
+
+   However, other information maintained on GitHub is more vulnerable to
+   loss.  This includes issues and discussion on those issues,
+   discussion and reviews of commits and pull requests, and any content
+   hosted on the wiki.  Tools exist for extracting this information for
+   backup.
+
+   As specified in [RFC8875], backup copies of repositories and other
+   important data SHOULD be maintained.
+
+   The potential for malicious actions by compromised or malcontent
+   editors, chairs, and area directors is relevant in maintaining the
+   integrity of the content that GitHub hosts.  Backups allow for
+   recovery of content, and regular submissions as Internet-Drafts
+   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.
+
+   A compromise of credentials could mean loss of control for
+   repositories an 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
+
+   This document has no IANA actions.
+
+12.  References
+
+12.1.  Normative References
+
+   [RFC2026]  Bradner, S., "The Internet Standards Process -- Revision
+              3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996,
+              <https://www.rfc-editor.org/info/rfc2026>.
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119,
+              DOI 10.17487/RFC2119, March 1997,
+              <https://www.rfc-editor.org/info/rfc2119>.
+
+   [RFC2418]  Bradner, S., "IETF Working Group Guidelines and
+              Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418,
+              September 1998, <https://www.rfc-editor.org/info/rfc2418>.
+
+   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+              May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+12.2.  Informative References
+
+   [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",
+              RFC 7991, DOI 10.17487/RFC7991, December 2016,
+              <https://www.rfc-editor.org/info/rfc7991>.
+
+   [RFC8875]  Cooper, A. and P. Hoffman, "Working Group GitHub
+              Administration", RFC 8875, DOI 10.17487/RFC8875, August
+              2020, <https://www.rfc-editor.org/info/rfc8875>.
+
+Acknowledgments
+
+   This work would not have been possible without the hard work of those
+   people who have trialed the use of GitHub at the IETF.  Alia Atlas
+   contributed significant text to an earlier draft version of this
+   document.  Tommy Pauly, Rich Salz, and Christopher Wood all provided
+   significant input.
+
+Authors' Addresses
+
+   Martin Thomson
+   Mozilla
+
+   Email: mt@lowentropy.net
+
+
+   Barbara Stark
+   AT&T
+
+   Email: barbara.stark@att.com