RFC 8874

Working Group GitHub Usage Guidance

📅 published August 2020, from ietf

Working Group GitHub Usage Guidance 🎀

Okay bestie, so this is RFC 8874, called Working Group GitHub Usage Guidance 💅 It's written by M. Thomson from Mozilla and B. Stark from AT&T. It's Informational, dated August 2020, and its ISSN is 2070-1721. The title block doesn't list any RFCs it obsoletes or updates ✨

Abstract

Quick summary: this doc gives a set of guidelines for working groups that choose to use GitHub for their work 🌸

Status of This Memo

This doc is not an Internet Standards Track specification. It's published for informational purposes 💜

This doc is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). Not every document the IESG approves is a candidate for any level of Internet Standard, so see Section 2 of RFC 7841 🧚

You can find info about this doc's current status, any errata, and how to give feedback at https://www.rfc-editor.org/info/rfc8874 🦋

Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved 🎀

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they're in effect on the date of publication. Please read these carefully, bestie, because they explain your rights and restrictions for this doc. Code Components pulled out of this doc must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come 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 💖 Using GitHub (https://github.com/) or similar tools as part of that process can have a few objectives. GitHub has tools that are super helpful for editing documents 📝 Using this service has been found to cut the time a working group needs to produce documents, and to improve the quality of the final result. Iconic 🔥

Version control improves traceability and visibility of changes ✨ Issue tracking can manage open issues and keep a record of how they got resolved. Pull requests let people engage more on technical and editorial changes, and they encourage contributions from a bigger group of people 🫶 Using GitHub can also broaden the community of contributors for a spec. Main character energy 👑

The main purpose of this doc is to give guidelines on how a working group might bring GitHub's capabilities into its process for developing Internet-Drafts 🦋 Whether to use GitHub, and whether to adopt these practices, is up to the working group's discretion 💅

This doc is meant as a supplement to existing working group practices. It gives guidance to working group chairs and participants on how to best use GitHub within the framework set by RFC 2418 [RFC2418] 🎀 It aims to set norms that reduce the variation in usage patterns between different working groups, and to help avoid issues that have come up in the past 🌸

There's a companion doc, [RFC8875], that describes the administrative processes supporting the practices in this one 🧚

IRTF research groups can work similarly to working groups, but this doc only directly addresses the needs of working groups. Other groups might still draw inspiration from what's in here ✨

1.1. Distributed Version Control Systems

Version control systems are a critical part of software engineering, and they're also super useful for document editing 💜

Git (https://git-scm.com/) is a distributed version control system that can run without a central service 🌸 Each instance of a repository holds a number of revisions. Each revision stores the complete state of a set of files. Users can make new revisions in their own copy of a repository and share revisions between copies of repositories 🦋

1.2. GitHub

GitHub is a service run at <https://github.com/> 🌈 It gives you centralized storage for Git repositories. GitHub is freely accessible on the open Internet 💖

GitHub gives you a simplified, integrated interface to Git. It also has basic user management, an issue tracker, associated wikis, project hosting, and other features 🎀

There are a huge number of projects on GitHub and a very large community of contributors 😭 One way some IETF working groups have benefited from it is through more reviews of the document and its associated issues, plus other improvements that come from making it easier for a broader community to take part 🫶

1.3. Other Services

Git isn't the only version control system out there, and GitHub isn't the only hosting choice either 🧚 Other services host revision control repositories and offer similar extra features to GitHub. For example, BitBucket (https://bitbucket.org/) and GitLab (https://about.gitlab.com/) have similar feature sets. Software for custom installations exists too 💅

This doc focuses mainly on GitHub because it has a large and active community of contributors. So some content might not apply to other similar services 🍓 A working group that decides to adopt an alternative tool or service can still get a lot out of the general guidance in here 💜

1.4. Document Goals

This doc aims to describe how a working group might best apply GitHub to its work 🦋 The intent is to give each working group a lot of flexibility in how it uses GitHub 🌈

This doc requires that policies for using GitHub are agreed upon and clearly communicated within the working group (see Section 2) 🎀 The rest of the doc has guidelines and advice on how to build a workable policy 💅

The requirements here apply when a working group decides to use GitHub as a primary means of interaction. Individuals can set their own policies when using GitHub to manage their own drafts, or drafts they edit on behalf of a working group that hasn't explicitly adopted GitHub 🫶

For both sets of users, this doc tries to give some advice on practices that have worked well ✨

This doc only addresses using GitHub to develop documents. A working group could choose to use the tool to help manage its charter or session materials, like agendas, minutes, and presentations. The advice here might apply more broadly, but using GitHub to manage other material is out of scope for this doc 🙈

1.5. Notational Conventions

Okay, so the keyword rule 🔥 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 doc uses a lot of terms related to Git and GitHub. Check [GLOSSARY] for info on those terms 📚

2. Administrative Policies 👑

The following administrative rules give 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 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 the responsible area directors and the IETF Secretariat. Working group chairs SHOULD also be included as owners. Area directors MAY also designate a delegate who 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 that follow these guidelines can be found in [RFC8875] 🦋

2.2. Communicating Policies

Each working group MAY set its own policy on whether and how it uses GitHub 🌈 It's important that occasional participants, and others who are used to IETF tools, can work out what the policy is and easily find the policy and the GitHub organization 💖

A simple way to do this is to include a link to the GitHub organization on the working group charter page in the datatracker 🎀 If there are other resources, like mailing lists, links to those can be added too ✨

Repositories MUST include a copy of, or a reference to, the policy that applies to managing any documents they contain 🫶 Updating the README or CONTRIBUTING file in the repository with the details of the process makes sure the process is recorded somewhere stable, other than the mailing list archive. It 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 ✨

Okay so working group chairs are the ones in charge of figuring out how to hit the charter goals in a way that's open and transparent 💅 They're also the ones who check whether anyone is actually interested in using GitHub, and who run the consensus call on 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. The vibe check with the area directors is lowkey essential 🦋

3.1. What to Use GitHub For

Working group chairs decide which GitHub features the working group will rely on. Section 4 goes deeper into the different features that can be used, so go read that if you're curious 🌸

Working group chairs who decide to use GitHub MUST inform the working group of their decision on the working group mailing list. An email explaining how the working group plans to use GitHub is enough, though it might be helpful to remind new contributors of these guidelines every now and then 💌

Working group chairs are responsible for making sure any policy they adopt gets enforced and maintained 👑

The set of GitHub features (Section 4) that the working group relies on needs to be clearly documented in policies. This document gives some guidance on potential policies and how they might be applied 📝

Features the working group doesn't rely on can still be made available to document editors, who are then free to use them for their own purposes. For example, even if the working group doesn't formally use issues to track items that need more discussion before consensus, keeping the issue tracker open for editors can be super valuable 🧚

Working group policies need to be set with the goal of improving transparency, participation, and ultimately the quality of documents. Sometimes it might make sense to limit what document editors are able to do in order to serve these goals. Chairs are encouraged to check in with document editors every so often to make sure the policies are actually working 💖

A document editor can still use GitHub on their own for documents they edit, even if the working group doesn't officially choose GitHub. Any such public repository MUST follow the IETF Note Well and bear notices; see Section 2.2. This recognizes that editors have traditionally picked their own methods for managing the documents they edit, while still making sure contributors understand their obligations under IETF processes 🌈

Work done in GitHub has no special status. Anything that comes out of GitHub activity needs to be taken to the working group, and it's subject to approval, rejection, or modification by the working group, same as any other input. No shortcuts, bestie 🙈

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 before 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 done by having the name of the document reflect its status (so draft-ietf-<wgname>-... means the document was adopted), or through a prominent notice, like one in the README 🍓

Experience has shown that keeping separate repositories for independent documents is the most manageable move. It lets the work in each repository stay focused on a single item ✨

Closely related documents, like those that together address a single milestone, might be placed in a single repository. This makes it easier for editors to manage changes and issues that affect multiple documents 🦋

Maintaining multiple documents in the same repository can add overhead that hurts individual documents. For instance, issues might need extra markings to identify which document they affect. Also, because editors all have write access to the repository, managing who has write access to a larger repository is harder (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 assigning 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, like 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 only gets read access to a repository. This doesn't give those contributors extra privileges. Instead, it lets issues and pull requests be assigned to those people, so it can be used to hand out editorial or review tasks to individuals outside the editor team 🧚

3.4. Document Formats

In addition to the canonical XML format [RFC7991], document editors might choose a different input form for editing documents, such as Markdown. Markdown-based formats are more accessible for new contributors, though ultimately the decision about format is left to document editors 💜

Formats that are not text-based SHOULD NOT be used, because they're ill-disposed to the sorts of interaction that revision control enables 😭

4. Contribution Methods 🌸

Contributions to documents come in lots of forms, and GitHub gives you a bunch of options on top of email. Input on GitHub can look like new issues and pull requests, comments on issues and pull requests, or comments on commits 🦋

4.1. Issue Tracker

The GitHub issue tracker can be an effective way to manage the open issues on a document. Issues, both open and closed, can be a really useful record of decisions the working group has made 📝

Issues can be given arbitrary labels, assigned to contributors, and grouped into milestones. The issue tracker is built into the repository, and 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. The tracker could be limited to recording that issues exist, or it might be 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 GitHub issue tracker are the main topic of Section 5 🎀

4.1.1. Issue Labels

Labeling issues can be a total game changer for managing them 🌈 For instance, marking substantive issues separately from editorial ones can help guide discussion. Labels are also helpful for spotting issues where consensus has been reached but editors still need to work 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 relates specifically to the use of labels to the working group. That includes what the labels mean, and who can apply and remove them. 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 lets them close issues. The user who opens an issue can close it too 🫶

Chairs MUST provide guidance on who is permitted to close an issue and under what conditions. Restrictions on who can close an issue, and in what circumstances, are generally not advisable until a document has reached a certain level of maturity 🍓

4.1.3. Reopening Issues

Issues that have reached a resolution with working group consensus MUST NOT be reopened unless new information is presented. No relitigating the vibes 🙈

For long-running work items, new contributors often raise issues that have already been resolved. There can also be a temptation to reopen contentious issues that were resolved with rough consensus. Figuring out whether the arguments for reopening an issue actually represent new information might take some discussion in the working group 😭

Chairs are empowered to use their discretion in deciding whether or not to reopen issues. For trickier matters, the chairs MAY insist that the working group reach consensus on whether an issue should be reopened. Note, though, that anything that comes out of this process still needs 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 lets a user request a change to a repository. A user doesn't need 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, so they can 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 a discussion of what counts as a substantial change. A pull request creates an artifact that records the reasons for changes and gives other contributors a chance to review them. Ideally, pull requests that address substantive issues mention the issue they address in the opening comment. A working group policy could require pull requests to be used this way 🦋

   |  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 share a lot of properties with issues, including the ability to host discussion and carry labels. Most importantly, using pull requests creates a record of actions taken 📝

For significant changes, leaving a pull request open until the working group's discussion of the issue concludes lets the pull request track that discussion and properly capture the outcome. Pull requests can be updated as discussions continue, or in response to feedback 🧚

Groups of editors could adopt a practice where one editor creates a pull request and another merges it. This makes sure changes are reviewed by editors. Editors get to decide how they manage changes among themselves 👑✨

4.2.1. Discussion on Pull Requests 🦋

Okay so pull requests get everything issues get, AND you can review the actual changes in them 💅 That's super valuable, but it comes with some drama ngl.

Review comments (other than the summary) are attached to specific lines of the proposed change. If the pull request gets changed later, those comments can be really hard to find, or literally impossible to find 😭 That's rough for contributors who aren't tracking discussions super closely.

So working group chairs SHOULD discourage using 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 takes some real judgment from editors, bestie. Working group chairs MAY occasionally flag a pull request and ask editors to hold off on merging until working group consensus has been assessed. ✨

Also, the copy of a document on GitHub doesn't have to be a perfect mirror of working group consensus at every single moment. Editors need some flexibility in how they manage a document. 🌸

4.3. Monitoring Activity 🔥

GitHub sends individualized email notifications about activity, and each user can adjust them to their vibe 🎀 On top of that, some working groups have set up read-only mailing lists that get notifications about activity on working group repositories. These lists can be too much to keep up with, but having an archive of actions is seriously useful.

Another option is periodic email summaries, like the ones made by a notification tool such as github-notify-ml (https://github.com/dontcallmedom/github-notify-ml). It's been used effectively in several working groups, though it does require server infrastructure 🖥️

Also, clear reporting about the changes in each revision of an Internet-Draft helps contributors keep up with activity. This might look like asking editors for a change log that captures the substantive changes in each revision. 📝

5. Typical Working Group Policies 🌈

Current experience with GitHub suggests a few different approaches for using the tool more in working groups. ✨

This section walks through some basic modes for interacting with GitHub, each one more involved than the last. It starts with a super lightweight vibe where document management is the only feature that's formally used, and then it gets progressively more intensive as the GitHub issue tracking features come into play. These approaches differ mainly in how discussion of substantive matters is managed. Most of the advice in this document applies equally to all the models 💜

Working groups can adjust these policies to suit their needs, but they're advised to avoid gratuitous changes just for consistency across the IETF as a whole. It's also possible to use different processes for different documents in the same working group 🦋

Working group chairs are responsible for confirming that the working group has consensus to adopt any process. Heads up: a more tightly controlled process can end up privileging positions that are already captured in documents, which might disadvantage alternative viewpoints 👀

5.1. Document Management Mode 🎀

In this mode, GitHub repositories are used to manage changes to documents, but the bulk of the work happens over email, face-to-face meetings, and other more traditional interactions. The whole point is to enable document and issue management on GitHub while keeping the process as simple as possible 💖

In the version of this mode with the least GitHub interaction, a repository is created for document management by editors. Editors might maintain issues and pull requests for their own benefit, but those 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, a record of the existence of substantive technical discussions is tracked using issues in the issue tracker. However, discussion of any substantial matters always happens on mailing lists 📬

Under this mode, anyone can open issues and pull requests, but anything deemed substantive MUST be resolved exclusively on the mailing list. GitHub discussion is limited to recording the state of issues. Only editorial matters can be resolved in the issue tracker 🫶

Chairs and editors get discretion in deciding what counts as substantive. As documents mature, it's generally prudent to consult the mailing list whenever there's doubt. Like with other working group decisions, chairs are the arbiters if there's a dispute ⚖️

A recurring problem with this mode is that discussions tend to spontaneously pop up in the issue tracker 🙈 It takes some discipline from chairs and editors to make sure any substantive matters get taken to the mailing list.

Keeping mailing lists as the main venue for discussing substantive matters means this mode, along with the document management mode, fits best with existing working group practices. Participants in a working group operating under either model can reasonably expect to get all relevant communication about the group's work from the working group mailing list 💌

Even though the mailing list is used for making decisions, the issue tracker can still be a useful record of where issues stand. It's often helpful if chairs or editors record details of decisions in issue comments when they close issues as resolved ✅

5.3. Issue Discussion Mode 💬

This mode is different from the others because discussion about substantive technical matters is allowed to happen on GitHub issues. Decisions are always subject to confirmation on the mailing list, but participants are allowed to hold substantive discussions in the issue tracker. In some cases, that can include making some decisions without involving the working group mailing list at all 👀

The working group mailing list is still a critical place for decision making, even when issue discussion happens elsewhere. Working group mailing lists usually include a wider audience than the people following issue discussions, so difficult issues always benefit from list discussion 🌈

Decisions about working group consensus MUST always be confirmed using the working group mailing list. Depending on how mature the documents are, though, this might be a lighter interaction, like sending an email confirmation for an initial set of resolutions that came out of issue tracker discussions 💅

Using the mailing list to resolve difficult or controversial issues is strongly encouraged. For those cases, the issue tracker might be used to more fully develop an understanding of the problems before starting a discussion on the mailing list, kind of like the design team process (see Section 6.5 of [RFC2418]) 🧠

As a more involved process, adopting this mode can require changing policies as documents become more mature 🌸

5.3.1. Early Design Phases 🌱

During the early phases of a protocol's design, chairs MAY allow editors to manage all aspects of issues. Editors get to decide how to both identify and resolve technical issues, including making any changes they feel are necessary 🔥

The main reason to give editors more discretionary power is to speed up how quickly changes can get made. In many cases, documents adopted by a working group are already mature enough that a looser process isn't beneficial. A looser process increases the risk of missing issues that need working group consensus, and of integrating substantive changes based on decisions that don't reflect what the working group actually agreed on 😬

Changes made by editors under this process still have plenty of ways to catch and fix problems. GitHub and Git provide tools for making sure changes are tracked and can be audited 🔍 Within the usual working group process, Internet-Drafts are expected to get regular review. Also, process checkpoints like Working Group Last Call (WGLC; Section 7.4 of [RFC2418]) provide extra safeguards against abuse 🛡️

Working groups are advised against giving editors this much flexibility for the entire life cycle of a document. 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 know not just that the document as a whole still has working group support, but that changes aren't being made without wider consultation 🫶

Chairs MAY choose to manage the process of deciding which issues are substantive. For example, 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 even more important 📬

Chairs can declare working group consensus about how to resolve issues in the abstract, which lets editors decide how to capture those decisions in the documents 🌸

More mature documents need more than consensus. They need 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 makes sure previous consensus decisions aren't overturned without cause ✨ Chairs MAY institute this stricter process prior to WGLC 🎀

Note: It's generally sufficient to trust editors to manage adherence to these policies, helped along by the transparency that the version control system provides. There are tools that can tightly control access to repositories, but they can be overly constraining 💅

5.4. Issue Labeling Schemes 🏷️

Several schemes for using issue labels to manage issues have been used successfully. This section outlines those strategies and how they might be applied 🌈

A design/editorial split (see Section 5.4.1) is useful in every case where the issue tracking capability is used. A working group that only uses GitHub for issue tracking might find that distinction is all they need 🧚

Working groups or editors might use additional labels as they choose. Any label 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 attached to those issues 🫶

5.4.1. Editorial/Design Labeling ✨

okay so the BIGGEST question you can ask about an issue is whether it's substantive 👀. That's the whole vibe behind the editorial and design labels 💅.

An issue labeled editorial has no substantive effect on a document 🌸. Its only glow-up is making the spec easier to understand ✨. Editors get to decide how to handle these, no drama 🫶.

An issue labeled design has or might have a substantive effect on a document 🔥. For protocol specs, that means it might touch implementations or interoperability requirements 🦋. Resolving a design issue needs working group consensus, even if the outcome is to make no change 😭. Yes, even "no change" needs the group to agree, bestie 💀.

This distinction works for every kind of document 🌈. For example, a design issue on an Informational document could be raised just to talk about possible changes to important concepts in the doc 🧚.

5.4.2. Decision Labeling 🎀

Labels can totally be used to run processes 📋. As documents mature and issues pile up, labels help clearly mark the status of each one 🍓. They're especially useful for managing working group decisions 👑.

For less mature documents, issues with resolutions but no specific proposed text might get marked editor-ready ✨. That signals there's consensus on an approach, just not on a specific proposal yet 🦋. Chairs might use it to say discussion is complete and that editors get discretion to write the text 💅.

If specific text is needed to resolve issues, which is more the case for mature documents, editors might use a proposal-ready label 📝 to mark issues they believe have acceptable resolutions 🙌.

For resolved issues, chairs might use a has-consensus label to mark issues where formal working group decisions have been made (Section 6.1 of [RFC2418]) 👑.

A future or next-version label might be used to mark and save issues for a future version of, or extension to, a protocol 🧚. This is especially handy when the resolution is to take no action 🌸.

5.4.3. Component Labeling 🧩

Repositories with multiple interrelated documents, or one complex document with multiple logical components, might benefit from labels that identify different aspects of the work 🌈. Which labels fit best depends on how each document is structured 💖.

5.4.4. Other Labels 🏷️

Other labels can be used depending on what editors and working group processes need 🫶. For example:

  • An invalid label might be used for issues that were raised in error 🙈.
  • A blocked label might indicate an issue is waiting on an external process or a related issue ⏳.
  • A parked label might be used for issues that don't need immediate working group attention 🛌.

6. Internet-Draft Publication 📦

While a document is being developed, individual revisions can be built and formally submitted as an Internet-Draft 🚀. That creates a stable snapshot and puts the in-progress document in front of a wider audience 👀. Documents submitted as Internet-Drafts aren't 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 🗓️. That includes IETF meetings, other in-person meetings, and telephone or video conferences 📞. Discussion could use the current version from version control, but participants can't be expected to watch changes in real time 😵. A published Internet-Draft gives everyone a common, stable state to look at 🫶.

Internet-Drafts that use a GitHub repository SHOULD include a notice that references the repository 📌. That notice might also say where to discuss the draft 💬.

Revisions used to generate documents submitted as Internet-Drafts SHOULD be tagged in repositories so there's 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 happens on GitHub could be part of the consensus process, but the ultimate decision on consensus for a document is made by the chairs [RFC2026] 👑.

GitHub enables more involved interactions, which can lead to way more activity than a typical working group mailing list 😅. Participants who want to limit their time commitment might follow GitHub selectively, either by following only specific issues or by checking the state of the document now and then 🧘. Other participants might not use GitHub at all 🤷.

Chairs, just a reminder: 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 mean hearing 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 the early stages of a document's development 🛠️. 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 there's 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 📄. That gets published to GitHub Pages, which lets users view the most recent revision 🌐. Including a prominent link to this version (such as in the README) makes it easier for new contributors to find a readable copy of the latest draft 🔗. Including links to differences between this generated version and any published document helps contributors spot 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 its specification, such as schema or source code, a continuous integration system might also validate those languages 🧠. Tests for any source code in the document might be run, or examples might be checked for correctness 🧪.

9. Advice to Editors 💌

Document editors are primarily responsible for maintaining documents, but taking on a few extra tasks can greatly improve the process for the working group 🫶.

Using GitHub means a contribution is more likely to come from someone who isn't very familiar with the work 🙋. Pull requests from new contributors can contain errors or omissions 😬. Duplicate issues are super common 👯. Proposed changes might have grammatical errors or diverge from existing style ✍️. If a change is generally sound, editors could accept it and then make any necessary corrections, rather than rejecting the pull request or requesting changes 💪.

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's an obvious solution, a pull request 💡. It doesn't 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 🔐

Okay bestie, this section is SERIOUS 🚨. Read every word.

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 on 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, since 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 and 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 📚✨

Okay, here are the extra reads, bestie 🤓📖

Acknowledgments 🫶

Okay, the thank-you list, and it's giving gratitude 💖 This work would not have been possible without the hard work of everyone who trialed the use of GitHub at the IETF 🙌 Alia Atlas contributed significant text to an earlier draft version of this document, which is iconic behavior 👑 Tommy Pauly, Rich Salz, and Christopher Wood all provided significant input too, and they are absolutely slaying 💅✨

Authors' Addresses 🌸

  • Martin Thomson, Mozilla, Email: mt@lowentropy.net 💜
  • Barbara Stark, AT&T, Email: barbara.stark@att.com 🦋
📦 where this page comes from