draft-ietf-git-using-github-06
Internet-Draft GitHub Usage Guidance March 2020 Thomson & Stark Expires 20 September 2020 [Page] Workgroup: Network Internet-Draft: draft-ietf-git-using-github-06 Published: 19 March 2020 Intended Status: Informational Expires: 20 September 2020 Authors: M. Thomson Mozilla B. Stark AT&T Working Group GitHub Usage Guidance Abstract This document provides a set of guidelines for Working Groups that choose to use GitHub for their work. ¶ Note to Readers Discussion of this document takes place on the GitHub@ietf mailing list (ietf-and-github@ietf.org), which is archived at https://mailarchive.ietf.org/arch/search?email_list=ietf-and-github . ¶ Source for this draft and an issue tracker can be found at https://github.com/ietf-gitwg/using-github . ¶ Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. ¶ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF).
Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/ . ¶ Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." ¶ This Internet-Draft will expire on 20 September 2020. ¶ 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 The IETF has an open and transparent process for developing standards. The use of GitHub 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 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 providing 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, [ GH-CONFIG ] , 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 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 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 to GitHub.
For instance, BitBucket and GitLab 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 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 [ GH-CONFIG
The rest of this page is on the live site.