Working Group GitHub Usage Guidance
RFC 8874

• Status
• IESG evaluation record
• IESG writeups
• Email expansions
• History

• Versions
• 00
• 01
• 02
• 03
• 04
• 05
• 06



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