From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc8874.txt | 1048 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1048 insertions(+) create mode 100644 doc/rfc/rfc8874.txt (limited to 'doc/rfc/rfc8874.txt') diff --git a/doc/rfc/rfc8874.txt b/doc/rfc/rfc8874.txt new file mode 100644 index 0000000..a6b7298 --- /dev/null +++ b/doc/rfc/rfc8874.txt @@ -0,0 +1,1048 @@ + + + + +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 + 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 (https://git-scm.com/) 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 . 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 of the document 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 as GitHub. For instance, BitBucket (https://bitbucket.org/) + and GitLab (https://about.gitlab.com/) 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 + upon 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-, 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 responsible area + directors and the IETF Secretariat. Working group chairs SHOULD also + be included as owners. Area directors MAY also designate a delegate + that 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 adhering to these guidelines can + be found in [RFC8875]. + +2.2. Communicating Policies + + Each working group MAY set its own policy as to whether and how it + uses GitHub. It is important that occasional participants in the + working group and others accustomed to IETF tools be able to + determine this and easily find the policy and GitHub organization. + + A simple example of how to do this is to include a link to the GitHub + organization on the working group charter page in the datatracker. + Similarly, if there are additional resources, such as mailing lists, + links to those resources could also be added. + + Repositories MUST include a copy of or reference to the policy that + applies to managing any documents they contain. Updating the README + or CONTRIBUTING file in the repository with details of the process + ensures that the process is recorded in a stable location other than + the mailing list archive. This 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 + + Working group chairs are responsible for determining how to best + accomplish the charter objectives in an open and transparent fashion. + The working group chairs are responsible for determining if there is + interest in using GitHub and for making a consensus call about + 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. + +3.1. What to Use GitHub For + + Working group chairs decide what GitHub features the working group + will rely upon. Section 4 contains a more thorough discussion on the + different features that can be used. + + Working group chairs who decide to use GitHub MUST inform the working + group of their decision on the working group mailing list. An email + detailing how the working group intends to use GitHub is sufficient, + though it might be helpful to occasionally remind new contributors of + these guidelines. + + Working group chairs are responsible for ensuring that any policy + they adopt is enforced and maintained. + + The set of GitHub features (Section 4) that the working group relies + upon need to be clearly documented in policies. This document + provides some guidance on potential policies and how those might be + applied. + + Features that the working group does not rely upon can be made + available to document editors. Editors are then able to use these + features for their own purposes. For example, though the working + group might not formally use issues to track items that require + further discussion in order to reach consensus, keeping the issue + tracker available to editors can be valuable. + + Working group policies need to be set with the goal of improving + transparency, participation, and ultimately the quality of documents. + At times, it might be appropriate to impose some limitations on what + document editors are able to do in order to serve these goals. + Chairs are encouraged to periodically consult with document editors + to ensure that policies are effective. + + A document editor can still use GitHub independently for documents + that they edit, even if the working group does not expressly choose + to use GitHub. Any such public repository MUST follow the IETF Note + Well and bear notices; see Section 2.2. This recognizes that editors + have traditionally chosen their own methods for managing the + documents they edit but preserves the need for contributors to + understand their obligations with respect to IETF processes. + + Work done in GitHub has no special status. The output of any + activity using GitHub needs to be taken to the working group and is + subject to approval, rejection, or modification by the working group + as with any other input. + +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 prior to 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 achieved by having the name of the + document reflect status (that is, draft-ietf--... indicates + that the document was adopted) or through a prominent notice (such as + in the README). + + Experience has shown that maintaining separate repositories for + independent documents is most manageable. This allows the work in + that repository to be focused on a single item. + + Closely related documents, such as those that together address a + single milestone, might be placed in a single repository. This + allows editors to more easily manage changes and issues that affect + multiple documents. + + Maintaining multiple documents in the same repository can add + overhead that negatively affects individual documents. For instance, + issues might require additional markings to identify the document + that they affect. Also, because editors all have write access to the + repository, managing the set of people with write access to a larger + repository is more difficult (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 allocating 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 such as 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 is + only given read access to a repository. This does not confer + additional privileges on these contributors; it instead allows for + issues and pull requests to be assigned to those people. This can be + used to manage the assignment of editorial or review tasks to + individuals outside of the editor team. + +3.4. Document Formats + + In addition to the canonical XML format [RFC7991], document editors + might choose to use a different input form for editing documents, + such as Markdown. Markdown-based formats are more accessible for new + contributors, though ultimately, decisions about format are left to + document editors. + + Formats that are not text-based SHOULD NOT be used, as these are ill- + disposed to the sorts of interaction that revision control enables. + +4. Contribution Methods + + Contributions to documents come in many forms. GitHub provides a + range of options in addition to email. Input on GitHub can take the + form of new issues and pull requests, comments on issues and pull + requests, and comments on commits. + +4.1. Issue Tracker + + The GitHub issue tracker can be an effective way of managing the set + of open issues on a document. Issues, both open and closed, can be a + useful way of recording decisions made by a working group. + + Issues can be given arbitrary labels, assigned to contributors, and + assembled into milestones. The issue tracker is integrated into the + repository; 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. Use of the issue tracker could be + limited to recording the existence of issues, or it might be used as + 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 use of the GitHub + issue tracker are the primary subject of Section 5. + +4.1.1. Issue Labels + + A system of labeling issues can be effective in managing issues. For + instance, marking substantive issues separately from editorial can be + helpful at guiding discussion. Using labels can also be helpful in + identifying issues for which consensus has been achieved but that + require editors to integrate 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 specifically relates to the use + of labels to the working group. This includes the semantics of + labels, and who can apply and remove these labels. 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 allows them to + close issues. The user that opens an issue is also able to close the + issue. Chairs MUST provide guidance on who is permitted to close an + issue and under what conditions. + + Restrictions on who can close an issue and under what circumstances + are generally not advisable until a document has reached a certain + degree of maturity. + +4.1.3. Reopening Issues + + Issues that have reached a resolution that has working group + consensus MUST NOT be reopened unless new information is presented. + + For long-running work items, new contributors often raise issues that + have already been resolved. Moreover, there could be temptation to + reopen contentious issues resolved with rough consensus. Determining + whether arguments presented in favor of reopening an issue represents + new information might require some discussion in the working group. + + Chairs are empowered to exercise discretion in determining whether or + not to reopen issues. For more difficult matters, the chairs MAY + insist that the working group reach consensus on whether an issue + should be reopened. Note, however, that any product of this process + still needs to have 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 allows a user to request a + change to a repository. A user does not need to have 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, allowing them to 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 discussion on what constitutes + a substantial change. A pull request creates an artifact that + records the reasons for changes and provides other contributors with + an opportunity to review the change. Ideally, pull requests that + address substantive issues mention the issue they address in the + opening comment. A working group policy could require that pull + requests be used in this fashion. + + | 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 have many of the same properties as issues, including + the ability to host discussion and bear labels. Critically, using + pull requests creates a record of actions taken. + + For significant changes, leaving a pull request open until discussion + of the issue within the working group concludes allows the pull + request to track the discussion and properly capture the outcome of + discussions. Pull requests can be updated as discussions continue, + or in response to feedback. + + Groups of editors could adopt a practice of having one editor create + a pull request and another merge it. This ensures that changes are + reviewed by editors. Editors are given discretion in how they manage + changes amongst themselves. + +4.2.1. Discussion on Pull Requests + + In addition to the features that pull requests share with issues, + users can also review the changes in a pull request. This is a + valuable feature, but it presents some challenges. + + Comments in a review other than a summary are attached to specific + lines of the proposed change. Such comments can be hard or + impossible to find if changes are subsequently made to the pull + request. This is problematic for contributors who do not track + discussions closely. + + For this reason, working group chairs SHOULD discourage the use of + 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 requires that editors exercise + some judgment. Working group chairs MAY occasionally identify a pull + request and request that editors withhold merging until working group + consensus has been assessed. + + Note that the copy of a document that is maintained on GitHub does + not need to be a perfect reflection of working group consensus at + every point in time. Document editors need some flexibility in how + they manage a document. + +4.3. Monitoring Activity + + GitHub produces individualized email notifications of activity that + each user can adjust to their preferences. In addition to these, + some working groups have created read-only mailing lists that receive + notifications about activity on working group repositories. The + volume of information on these lists can be too high to monitor + actively, but access to an archive of actions can be useful. + + An alternative is to rely on periodic email summaries of activity, + such as those produced by a notification tool like github-notify-ml + (https://github.com/dontcallmedom/github-notify-ml). This tool has + been used effectively in several working groups, though it requires + server infrastructure. + + Additionally, clear reporting about the changes that were included in + each revision of an Internet-Draft helps ensure that contributors can + follow activity. This might be achieved by requesting that editors + provide a change log that captures substantive changes to the + document in each revision. + +5. Typical Working Group Policies + + Current experience with use of GitHub suggests a few different + approaches to greater use of the tool in working groups. + + This section describes some basic modes for interacting with GitHub, + each progressively more involved. This starts with a very + lightweight interaction where document management is the only feature + that is formally used; then, progressively more intensive use of the + GitHub issue tracking capabilities is described. These approaches + differ primarily in how discussion of substantive matters is managed. + Most of the advice in this document applies equally to all models. + + Working groups can adjust these policies to suit their needs but are + advised to avoid gratuitous changes for the sake of consistency + across the IETF as a whole. It is possible to use different + processes for different documents in the working group. + + Working group chairs are responsible for confirming that the working + group has consensus to adopt any process. In particular, the + introduction of a more tightly controlled process can have the effect + of privileging positions already captured in documents, which might + disadvantage alternative viewpoints. + +5.1. Document Management Mode + + In this mode of interaction, GitHub repositories are used to manage + changes to documents, but the bulk of the work is conducted using + email, face-to-face meetings, and other more traditional + interactions. The intent of this policy is to enable document and + issue management using GitHub while minimizing the complexity of the + process. + + In the version of this mode with the least interaction with GitHub, a + repository is created for the purposes of document management by + editors. Editors might maintain issues and pull requests for their + own benefit, but these 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 of + interaction, a record of the existence of substantive technical + discussions is tracked using issues in the issue tracker. However, + discussion of any substantial matters is always conducted on mailing + lists. + + Under this mode, issues and pull requests can be opened by anyone, + but anything deemed substantive MUST be resolved exclusively on the + mailing list. Discussion on GitHub is limited to recording the state + of issues. Only editorial matters can be resolved using the issue + tracker. + + Chairs and editors are given discretion in determining what issues + are substantive. As documents mature, it is generally prudent to + prefer consulting the mailing list where there is doubt. As with + other working group decisions, chairs are the arbiters in case of + dispute. + + A recurrent problem with this mode of interaction is the tendency for + discussions to spontaneously develop in the issue tracker. This + requires a degree of discipline from chairs and editors to ensure + that any substantive matters are taken to the mailing list. + + Retaining mailing lists as the primary venue for discussion of + substantive matters ensures that this mode, along with the document + management mode, is most compatible with existing work practices for + working groups. Participants in a working group that operates under + either model can reasonably be expected to receive all relevant + communication about the work of the group from the working group + mailing list. + + Though the mailing list is used for making decisions, the issue + tracker can still be a useful record of the state of issues. It is + often useful if chairs or editors record details of decisions in + issue comments when closing issues as resolved. + +5.3. Issue Discussion Mode + + This GitHub interaction mode differs from the other modes in that + discussion relating to substantive technical matters is allowed to + occur on GitHub issues. Though decisions are always subject to + confirmation on the mailing list, participants are permitted to + conduct substantive discussions on the issue tracker. In some cases, + this can include making some decisions without involving the working + group mailing list. + + A working group mailing list remains a critical venue for decision + making, even where issue discussion occurs elsewhere. Working group + mailing lists generally include a wider audience than those who + follow issue discussion, so difficult issues always benefit from list + discussion. + + Decisions about working group consensus MUST always be confirmed + using the working group mailing list. However, depending on the + maturity of documents, this might be a more lightweight interaction + such as sending an email confirmation for an initial set of + resolutions arising from discussions on the issue tracker. + + Using the mailing list to resolve difficult or controversial issues + is strongly encouraged. In those cases, the issue tracker might be + used to more fully develop an understanding of problems before + initiating a discussion on the mailing list, along lines similar to + the design team process (see Section 6.5 of [RFC2418]). + + As a more involved process, adopting this mode can require changes in + policies as documents become more mature. + +5.3.1. Early Design Phases + + During early phases of the design of a protocol, chairs MAY allow + editors to manage all aspects of issues. Editors are permitted to + make decisions about how to both identify and resolve technical + issues, including making any changes that editors feel necessary. + + The primary reason to grant editors more discretionary power is to + improve the speed with which changes can be made. In many cases, + documents that are adopted by a working group are already + sufficiently mature, and a looser process is not beneficial. A + looser process increases the risk of missing issues that need working + group consensus and integrating substantive changes based on + decisions that don't reflect the consensus of the working group. + + Changes made by editors under this process do not lack options for + identifying and correcting problems. GitHub and Git provide tools + for ensuring that changes are tracked and can be audited. Within the + usual working group process, it is expected that Internet-Drafts will + receive regular review. Also, process checkpoints like Working Group + Last Call (WGLC; Section 7.4 of [RFC2418]) provide additional + safeguards against abuse. + + Working groups are advised against allowing editors this degree of + flexibility for the entirety of a document life cycle. 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 understand not + just that the document as a whole retains the support of the working + group, but that changes are not made without wider consultation. + + Chairs MAY choose to manage the process of deciding which issues are + substantive. For instance, 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 more important. + + Chairs can declare working group consensus regarding the resolution + of issues in the abstract, allowing editors discretion on how to + capture the decisions in documents. + + More mature documents require not only consensus, but 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 ensures that previous consensus decisions are not overturned + without cause. Chairs MAY institute this stricter process prior to + WGLC. + + | Note: It is generally sufficient to trust editors to manage + | adherence with these policies, aided by the transparency + | provided by the version control system. There are tools that + | can be used to more tightly control access to repositories, but + | they can be overly constraining. + +5.4. Issue Labeling Schemes + + Several schemes for use of issue labels in managing issues have been + used successfully. This section outlines these strategies and how + they might be applied. + + A design/editorial split (see Section 5.4.1) is useful in all cases + in which the issue tracking capability is used. A working group that + only uses GitHub for issue tracking might find that distinction + sufficient for their needs. + + Working groups or editors might use additional labels as they choose. + Any label that is 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 being attached to those issues. + +5.4.1. Editorial/Design Labeling + + The most important distinction about an issue is whether it is + substantive. The labels of "editorial" and "design" are used to + represent this distinction. + + An issue labeled as "editorial" has no substantive effect on a + document except to the extent that addressing the issue might make + understanding the specification easier. Resolution of "editorial" + issues can be left to the discretion of editors. + + An issue labeled as "design" has or might have a substantive effect + on a document. For protocol specifications, a "design" issue is one + that might affect implementations or interoperability requirements. + Addressing a "design" issue ultimately requires working group + consensus, even if the resolution is to make no change. + + This distinction can be applied to all types of documents. For + instance, a "design" issue for an Informational document might be + raised to discuss possible changes to important concepts in the + document. + +5.4.2. Decision Labeling + + Labels can be used to manage processes. As documents mature and + issues become more numerous, labels can be used to clearly mark the + status of issues. In particular, the labeling of issues can be used + to help manage working group decisions. + + For documents that are less mature, issues with resolutions but no + specific proposals for changes to text might be marked "editor-ready" + as a way of signaling that there is consensus on an approach, but no + specific proposal. Chairs might use this to signal that discussion + is complete and that editors are to be given discretion in the + construction of text. + + In contrast, if specific text is a prerequisite for resolving issues, + as might be the case for more mature documents, a "proposal-ready" + label might be used by editors to mark issues that they believe to + have acceptable resolutions. + + For resolved issues, a "has-consensus" label might be used by chairs + to mark issues for which formal working group decisions have been + made (Section 6.1 of [RFC2418]). + + A "future" or "next-version" label might be used to mark and thereby + save issues for a future version of, or extension to, a protocol, + particularly where a resolution is made to take no action. + +5.4.3. Component Labeling + + Repositories with multiple interrelated documents or a complex + document with multiple logical components might benefit from labels + that identify different aspects of the work. The choice of + appropriate labels for components will depend on the structure of + specific documents. + +5.4.4. Other Labels + + Other labels can be used depending on the needs of editors and + working group processes. For example, + + * An "invalid" label might be used for issues that were raised in + error. + + * A "blocked" label might indicate an issue is awaiting resolution + of an external process or related issue. + + * A "parked" label might be used to indicate issues that do not + require immediate working group attention. + +6. Internet-Draft Publication + + During the development of a document, individual revisions of the + document can be built and formally submitted as an Internet-Draft. + This creates a stable snapshot and makes the content of the in- + progress document available to a wider audience. Documents submitted + as Internet-Drafts are not 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, which + includes IETF meetings, other in-person meetings, and telephone or + video conferences. Though discussion could use the current version + of a document from version control, participants in a session cannot + be expected to monitor changes to documents in real time; a published + Internet-Draft ensures that there is a common, stable state that is + known to all participants. + + Internet-Drafts that use a GitHub repository SHOULD include a notice + that includes a reference to the repository. This notice might also + include information about where to discuss the draft. + + Revisions used to generate documents that are submitted as Internet- + Drafts SHOULD be tagged in repositories to provide 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 occurs on GitHub could be part of the consensus + process, but the ultimate decision on consensus regarding a document + is made by the chairs [RFC2026]. + + GitHub facilitates more involved interactions, which can result in a + much higher level of activity than a typical working group mailing + list. Participants who wish to limit their time commitment might + follow GitHub activity selectively, either by following only specific + issues or by occasionally reviewing the state of the document. Other + participants might not use GitHub at all. Chairs are reminded that + 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 result in gaining input 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 early stages of development of a + document. 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 that there is 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. This is then + published to GitHub Pages, which allows users to view a version of + the most recent revision of a document. Including a prominent link + to this version of the document (such as in the README) makes it + easier for new contributors to find a readable copy of the most + recent version of a draft. In addition, including links to + differences between this generated version and any published document + helps contributors identify 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 the + specification, such as schema or source code, a continuous + integration system might also be used to validate any formal language + that the document contains. Tests for any source code that the + document contains might be run, or examples might be checked for + correctness. + +9. Advice to Editors + + Document editors are primarily responsible for maintaining documents. + Taking on a few additional tasks can greatly improve the process for + the working group. + + Using GitHub means that it is more likely that a contribution is made + by users who are not very familiar with the work. Pull requests from + new contributors can contain errors or omissions. Duplicate issues + are commonplace. Proposed changes might have grammatical errors or + they might diverge from existing style. If a change is generally + sound, rather than rejecting the pull request or requesting changes, + editors could instead accept the change and then make any necessary + corrections. + + 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 is an obvious solution, a pull request. + It does not 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 + + 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 upon 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; 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 an 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, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC2418] Bradner, S., "IETF Working Group Guidelines and + Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418, + September 1998, . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + +12.2. Informative References + + [GLOSSARY] GitHub, "GitHub glossary", March 2020, + . + + [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", + RFC 7991, DOI 10.17487/RFC7991, December 2016, + . + + [RFC8875] Cooper, A. and P. Hoffman, "Working Group GitHub + Administration", RFC 8875, DOI 10.17487/RFC8875, August + 2020, . + +Acknowledgments + + This work would not have been possible without the hard work of those + people who have trialed the use of GitHub at the IETF. Alia Atlas + contributed significant text to an earlier draft version of this + document. Tommy Pauly, Rich Salz, and Christopher Wood all provided + significant input. + +Authors' Addresses + + Martin Thomson + Mozilla + + Email: mt@lowentropy.net + + + Barbara Stark + AT&T + + Email: barbara.stark@att.com -- cgit v1.2.3