Working Group GitHub Usage Guidance
RFC 8874
Document | Type | RFC - Informational (August 2020; No errata) | |
---|---|---|---|
Authors | Martin Thomson , Barbara Stark | ||
Last updated | 2020-08-27 | ||
Replaces | draft-thomson-git-using-github | ||
Stream | IETF | ||
Formats | plain text html xml pdf htmlized bibtex | ||
Reviews | |||
Stream | WG state | Submitted to IESG for Publication | |
Document shepherd | Christopher Wood | ||
Shepherd write-up | Show (last changed 2020-03-20) | ||
IESG | IESG state | RFC 8874 (Informational) | |
Action Holders |
(None)
|
||
Consensus Boilerplate | Yes | ||
Telechat date | |||
Responsible AD | Alissa Cooper | ||
Send notices to | Christopher Wood <caw@heapingbits.net> | ||
IANA | IANA review state | Version Changed - Review Needed | |
IANA action state | No IANA Actions |
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 processesShow full document text