RFC 8875

Working Group GitHub Administration

📅 published August 2020, from ietf

RFC 8875: Working Group GitHub Administration 🎀

Okay bestie, this is RFC 8875, called Working Group GitHub Administration 💖 It's an Informational doc, which means it's published for information and doesn't set any rules for the internet. It's from the IETF, written by A. Cooper (Cisco) and P. Hoffman (ICANN), dated August 2020, with ISSN 2070-1721 🦋 The header doesn't list anything it obsoletes or updates, so it's standing on its own ✨

Abstract ✨

GitHub is getting bigger in IETF working group life 📈 This doc is for working groups that are thinking about starting to use it, and it lays out uses and conventions for them. It doesn't mandate any processes, and it doesn't require working groups that aren't on GitHub to change anything 🫶

Status of This Memo 📜

This doc isn't an Internet Standards Track spec. It's just published for info 🧐

This is an IETF product 👑 It represents the consensus of the IETF community, it got public review, and it was approved for publication by the Internet Engineering Steering Group (IESG). Not every IESG-approved doc is a candidate for any level of Internet Standard, so check Section 2 of RFC 7841 if you're curious 🤓

Want the current status, errata, or a way to give feedback? Go to https://www.rfc-editor.org/info/rfc8875 💌

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
2.  Administrative Process and Conventions
  2.1.  Creation of GitHub Organizations
  2.2.  Migration of an Existing Organization
  2.3.  Personnel Changes
  2.4.  Working Group Closing
  2.5.  Creation of Document Repository
  2.6.  Listing Related Repositories
3.  Working Group Process
  3.1.  Contributions
  3.2.  Backing Up and Archiving GitHub Content
4.  Security Considerations
5.  IANA Considerations
6.  Informative References
Authors' Addresses

1. Introduction 🌸

Lots of IETF working groups and participants already use GitHub in different ways for their IETF document work 💅 Others want their working group to use GitHub to help build working group docs, but they're not sure how to get started or which conventions to follow 🤔 Some other working groups use or plan to use other code-repository services like GitLab and Bitbucket, which work differently than GitHub 🦋

This document specifies a set of administrative processes and conventions for IETF working groups to use if they choose to use GitHub to facilitate their work. The specifications here aren't aimed at working groups or individuals who are already using GitHub for IETF work. Practices vary among existing working groups, and some of them don't line up with the conventions proposed here, and that's fine 💖 The goal isn't to force uniformity on current practice. It's to help working groups get started with GitHub in a reviewed and validated way, if they want to 🎀

2. Administrative Process and Conventions 📋

This section specifies an administrative process and conventions to support the creation and management of GitHub organizations for working groups and single-document repositories in a uniform way. The steps may be done manually by the IETF Secretariat, or they may be automated. See https://github.com/richsalz/ietf-gh-scripts and https://github.com/martinthomson/i-d-template for working examples of automation that is in use in some working groups 🤖

In this document, the question of whether processes should be manual or automated is deliberately left unspecified, since these are implementation details that the IETF Secretariat and Tools Team will address 🛠️

Most of the conventions below are drawn from [RFC8874] ✨

2.1. Creation of GitHub Organizations 🏗️

This document specifies that there be a facility in the IETF Datatracker (https://datatracker.ietf.org/) interface to allow an area director (AD) or working group chair to request the creation of a GitHub organization for a particular working group. Ideally, this facility would appear both as part of the working group chartering UI and the working group page UI.

When an area director or working group chair makes a request to create a GitHub organization, the following process would be initiated:

  1. Create a GitHub organization for the working group.
  2. Name the organization in the format ietf-wg-<wgname>...
  3. Initialize the organization by designating the IETF Secretariat and the area directors in the working group's area as owners. If the responsible AD for the working group is from another area, that AD will be an owner as well.
  4. Initialize the organization with a team that has administrator access. This team will consist of the working group chairs and working group secretary, if one exists.

After the organization is created, the URL for the organization would be added to the working group's page in the Datatracker 🔗

Steps 3 and 4 above imply that the GitHub identities of the organization owners and administrators are known. Recording GitHub identities in the Datatracker (see https://trac.tools.ietf.org/tools/ietfdb/ticket/2548) would facilitate this. The person requesting the organization would need to be notified if the GitHub identities of any of the people meant to be owners or administrators were not available 🙈

2.2. Migration of an Existing Organization 🚚

If a working group already has an organization, it would be useful to be able to make it have the same management as one would get by going through the steps in Section 2.1. That is, it would be good to be able to run Steps 3 and 4 from Section 2.1 so that the rest of the activities in this section, such as personnel changes, work the same way as for organizations that were created as specified herein 🧃

2.3. Personnel Changes 👥

When there are personnel changes in the area or the working group, those changes would be reflected in the GitHub organization. There should be an ability in the Datatracker to specify that personnel changes have occurred 📝

2.4. Working Group Closing 🌙

When a working group is closed, the team with administrative access would be removed, and the owner list would be returned to the Secretariat and current ADs at the time of closing. The organization summary and the repositories within the organization would be updated to indicate that they are no longer under development. Later, the owner list could become just the Secretariat, or it might include others chosen by the Secretariat or the IESG 👋

2.5. Creation of Document Repository 📁

There are lots of different scenarios and configurations where it might be useful to have automation or established administrative conventions for repositories within WG organizations, such as:

  • Creating a new repository for an individual draft (at the discretion of the WG chair);
  • Creating a new repository for an already adopted working group draft;
  • Migrating an existing document repository into the WG organization; and
  • Creating a new repository that contains multiple drafts.

As an incremental step, this document specifies that there be a facility in the Datatracker interface to allow an administrator of an ietf-wg-<wgname> organization to request the creation of a new repository within that organization for a single document. The document authors would be identified as collaborators. The repository name would be the draft name. Ideally, the repository would be configured with a skeleton draft file, default CONTRIBUTING, LICENSE, and README files, and continuous integration support, in the vein of https://github.com/martinthomson/i-d-template. Performing this step would automatically inform the IETF Secretariat that this repository should be backed up as described in Section 3.2 💾

The IETF Datatracker should allow users to add links to repositories (for GitHub and other repository services) on working group, document, and user pages. At the time of this writing, this feature was under development 🚧

4. Security Considerations ✨

okay bestie, this section is short but it's SERIOUS 🫶 someone who can sneak changes into Internet-Drafts, especially late in a working group's process, could maybe slip in changes to protocols that end up getting adopted, and nobody notices 😭💀 that's giving main character villain energy and we are NOT here for it.

there's also a risk of data loss because everything is centralized in one service 🙈 this is recognized and mitigated by the plan in Section 3.2 (the backup and archiving stuff we just covered), so go check that out if you haven't 💜

5. IANA Considerations 🎀

no IANA actions in this one, so nothing to do here bestie 💅

6. Informative References 🌈

Authors' Addresses 💖

Alissa Cooper Cisco Email: alcoop@cisco.com

Paul Hoffman ICANN Email: paul.hoffman@icann.org

that's a wrap on RFC 8875, babe 🌸 the big takeaway is: keep your repos organized, back everything up, and don't let anyone sneak stuff past you 👑✨

📦 where this page comes from