idnits 2.17.1 draft-ietf-git-using-github-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (19 March 2020) is 1491 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-07) exists of draft-ietf-git-github-wg-configuration-06 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Informational B. Stark 5 Expires: 20 September 2020 AT&T 6 19 March 2020 8 Working Group GitHub Usage Guidance 9 draft-ietf-git-using-github-06 11 Abstract 13 This document provides a set of guidelines for Working Groups that 14 choose to use GitHub for their work. 16 Note to Readers 18 Discussion of this document takes place on the GitHub@ietf mailing 19 list (ietf-and-github@ietf.org), which is archived at 20 https://mailarchive.ietf.org/arch/search?email_list=ietf-and-github. 22 Source for this draft and an issue tracker can be found at 23 https://github.com/ietf-gitwg/using-github. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on 20 September 2020. 42 Copyright Notice 44 Copyright (c) 2020 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. Code Components 52 extracted from this document must include Simplified BSD License text 53 as described in Section 4.e of the Trust Legal Provisions and are 54 provided without warranty as described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Distributed Version Control Systems . . . . . . . . . . . 4 60 1.2. GitHub . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.3. Other Services . . . . . . . . . . . . . . . . . . . . . 4 62 1.4. Document Goals . . . . . . . . . . . . . . . . . . . . . 5 63 1.5. Notational Conventions . . . . . . . . . . . . . . . . . 5 64 2. Administrative Policies . . . . . . . . . . . . . . . . . . . 5 65 2.1. Organizations . . . . . . . . . . . . . . . . . . . . . . 6 66 2.2. Communicating Policies . . . . . . . . . . . . . . . . . 6 67 3. Deciding to Use GitHub . . . . . . . . . . . . . . . . . . . 7 68 3.1. What to Use GitHub For . . . . . . . . . . . . . . . . . 7 69 3.2. Repositories . . . . . . . . . . . . . . . . . . . . . . 8 70 3.3. Editors and Contributors . . . . . . . . . . . . . . . . 9 71 3.4. Document Formats . . . . . . . . . . . . . . . . . . . . 9 72 4. Contribution Methods . . . . . . . . . . . . . . . . . . . . 9 73 4.1. Issue Tracker . . . . . . . . . . . . . . . . . . . . . . 10 74 4.1.1. Issue Labels . . . . . . . . . . . . . . . . . . . . 10 75 4.1.2. Closing Issues . . . . . . . . . . . . . . . . . . . 10 76 4.1.3. Reopening Issues . . . . . . . . . . . . . . . . . . 11 77 4.2. Pull Requests . . . . . . . . . . . . . . . . . . . . . . 11 78 4.2.1. Discussion on Pull Requests . . . . . . . . . . . . . 12 79 4.2.2. Merging Pull Requests . . . . . . . . . . . . . . . . 12 80 4.3. Monitoring Activity . . . . . . . . . . . . . . . . . . . 12 81 5. Typical Working Group Policies . . . . . . . . . . . . . . . 13 82 5.1. Document Management Mode . . . . . . . . . . . . . . . . 13 83 5.2. Issue Tracking Mode . . . . . . . . . . . . . . . . . . . 14 84 5.3. Issue Discussion Mode . . . . . . . . . . . . . . . . . . 15 85 5.3.1. Early Design Phases . . . . . . . . . . . . . . . . . 15 86 5.3.2. Managing Mature Documents . . . . . . . . . . . . . . 16 87 5.4. Issue Labelling Schemes . . . . . . . . . . . . . . . . . 17 88 5.4.1. Editorial/Design Labelling . . . . . . . . . . . . . 17 89 5.4.2. Decision Labelling . . . . . . . . . . . . . . . . . 17 90 5.4.3. Component Labelling . . . . . . . . . . . . . . . . . 18 91 5.4.4. Other Labels . . . . . . . . . . . . . . . . . . . . 18 92 6. Internet-Draft Publication . . . . . . . . . . . . . . . . . 18 93 7. Assessing Consensus . . . . . . . . . . . . . . . . . . . . . 19 94 8. Continuous Integration . . . . . . . . . . . . . . . . . . . 20 95 9. Advice to Editors . . . . . . . . . . . . . . . . . . . . . . 20 96 10. Security Considerations . . . . . . . . . . . . . . . . . . . 21 97 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 98 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 99 12.1. Normative References . . . . . . . . . . . . . . . . . . 22 100 12.2. Informative References . . . . . . . . . . . . . . . . . 22 101 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 23 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 104 1. Introduction 106 The IETF has an open and transparent process for developing 107 standards. The use of GitHub (https://github.com/) or similar tools, 108 when used as part of this process, can have several objectives. 109 GitHub provides tools that can be helpful in editing documents. Use 110 of this service has been found to reduce the time that a Working 111 Group needs to produce documents and to improve the quality of the 112 final result. 114 The use of version control improves traceability and visibility of 115 changes. Issue tracking can be used to manage open issues and 116 provide a record of their resolution. Pull requests allow for better 117 engagement on technical and editorial changes, and encourage 118 contributions from a larger set of contributors. Using GitHub can 119 also broaden the community of contributors for a specification. 121 The main purpose of this document is providing guidelines for how a 122 Working Group might integrate the capabilities provided by GitHub 123 into their processes for developing Internet-Drafts. Whether to use 124 GitHub and whether to adopt these practices is left to the discretion 125 of the Working Group. 127 This document is meant as a supplement to existing Working Group 128 practices. It provides guidance to Working Group chairs and 129 participants on how they can best use GitHub within the framework 130 established by RFC 2418 [RFC2418]. This document aims to establish 131 norms that reduce the variation in usage patterns between different 132 Working Groups and to help avoid issues that have been encountered in 133 the past. 135 A companion document, [GH-CONFIG], describes administrative processes 136 that support the practices described in this document. 138 Although the operation of IRTF Research Groups can be similar in 139 function to Working Groups, this document only directly addresses the 140 needs of Working Groups. However, other groups may draw inspiration 141 for GitHub use from the contents herein. 143 1.1. Distributed Version Control Systems 145 Version control systems are a critical component of software 146 engineering and are also quite useful for document editing. 148 Git (https://git-scm.com/) is a distributed version control system 149 that can operate without a central service. Each instance of a 150 repository contains a number of revisions. Each revision stores the 151 complete state of a set of files. Users are able to create new 152 revisions in their copy of a repository and share revisions between 153 copies of repositories. 155 1.2. GitHub 157 GitHub is a service operated at https://github.com/. GitHub provides 158 centralized storage for git repositories. GitHub is freely 159 accessible on the open Internet. 161 GitHub provides a simplified and integrated interface to git, and 162 also provides basic user management, an issue tracker, associated 163 wikis, project hosting, and other features. 165 There are a large number of projects at GitHub and a very large 166 community of contributors. One way in which some IETF Working Groups 167 have benefited from use of the service is through increased numbers 168 of reviews and associated issues, along with other improvements that 169 come from facilitating participation by a broader community. 171 1.3. Other Services 173 Git is not the only version control system available, nor is GitHub 174 the only possible choice for hosting. There are other services that 175 host revision control repositories and provide similar additional 176 features to GitHub. For instance, BitBucket (https://bitbucket.org/) 177 and GitLab (https://about.gitlab.com/) provide similar feature sets. 178 In addition to a hosted service, software for custom installations 179 exists. 181 This document concentrates primarily on GitHub as it has a large and 182 active community of contributors. As a result, some content might 183 not be applicable to other similar services. A Working Group that 184 decides to adopt an alternative tool or service can still benefit 185 from the general guidance in this document. 187 1.4. Document Goals 189 This document aims to describe how a Working Group might best apply 190 GitHub to their work. The intent is to allow each Working Group 191 considerable flexibility in how they use GitHub. 193 This document requires that policies for use of GitHub are agreed and 194 clearly communicated within the Working Group (see Section 2). The 195 remainder of the document contains guidelines and advice on how to 196 construct a workable policy. 198 The requirements here apply to the case where a Working Group decides 199 to use GitHub as a primary means of interaction. Individuals can set 200 their own policies when using GitHub for managing their own drafts, 201 or for managing drafts that they edit on behalf of a Working Group 202 that has not explicitly adopted GitHub. 204 For both sets of users, this document aims to provide some amount of 205 advice on practices that have been effective. 207 This document only aims to address use of GitHub in developing 208 documents. A Working Group could choose to use the tool to aid in 209 managing their charter or session materials such as agendas, minutes, 210 and presentations. Though the advice here might apply more broadly, 211 using GitHub to manage other material is out of scope for this 212 document. 214 1.5. Notational Conventions 216 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 217 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 218 "OPTIONAL" in this document are to be interpreted as described in BCP 219 14 [RFC2119] [RFC8174] when, and only when, they appear in all 220 capitals, as shown here. 222 This document uses a lot of terms related to git and GitHub; see 223 [GLOSSARY] for information on these terms. 225 2. Administrative Policies 227 The following administrative rules provide the necessary oversight 228 and transparency. 230 2.1. Organizations 232 Organizations are a way of forming groups of contributors on GitHub. 233 The Working Group SHOULD create a new organization for its work. A 234 Working Group organization SHOULD be named consistently so that it 235 can be found. For instance, the name could be ietf-wg-, as 236 recommended in [GH-CONFIG]. 238 A single organization SHOULD NOT be used for all IETF activity, or 239 all activity within an area. Large organizations create too much 240 overhead for general management tasks. 242 GitHub requires that each organization have at least one owner. The 243 owners for a Working Group repository MUST include responsible Area 244 Directors and the IETF Secretariat. Working Group chairs SHOULD also 245 be included as owners. Area Directors MAY also designate a delegate 246 that becomes an owner, such as another Area Director from the same 247 area. An organization MUST have at least 2 owners. 249 Within an organization, members can be grouped into teams. A team 250 with "Admin" access to repositories SHOULD be created for the Working 251 Group Chairs and any Working Group Secretary. 253 Details about creating organizations adhering to these guidelines can 254 be found in [GH-CONFIG]. 256 2.2. Communicating Policies 258 Each Working Group MAY set its own policy as to whether and how it 259 uses GitHub. It is important that occasional participants in the WG 260 and others accustomed to IETF tools be able to determine this and 261 easily find the policy and GitHub organization. 263 A simple example of how to do this is to include a link to the GitHub 264 organization on the WG Charter page in the datatracker. Similarly, 265 if there are additional resources, such as mailing lists, links to 266 those resources could also be added. 268 Repositories MUST include a copy of or reference to the policy that 269 applies to managing any documents they contain. Updating the README 270 or CONTRIBUTING file in the repository with details of the process 271 ensures that the process is recorded in a stable location other than 272 the mailing list archive. This also makes Working Group policies 273 available to casual contributors who might only interact with the 274 GitHub repository. 276 GitHub prominently links to the CONTRIBUTING file on certain pages. 277 This file SHOULD be used in preference to the README for information 278 that new contributors need. The README SHOULD contain a link to the 279 CONTRIBUTING file. 281 In addition to Working Group policies, notices on repositories MUST 282 include citations for the IETF Note Well (https://www.ietf.org/about/ 283 note-well/). 285 3. Deciding to Use GitHub 287 Working Group Chairs are responsible for determining how to best 288 accomplish the charter objectives in an open and transparent fashion. 289 The Working Group Chairs are responsible for determining if there is 290 interest in using GitHub and making a consensus call to determine if 291 the proposed policy and use is acceptable. 293 Chairs SHOULD involve Area Directors in any decision to use GitHub, 294 especially where substantive discussion of issues is permitted as 295 described in Section 5.3. 297 3.1. What to Use GitHub For 299 Working Group Chairs decide what GitHub features the Working Group 300 will rely upon. Section 4 contains a more thorough discussion on the 301 different features that can be used. 303 Working Group Chairs who decide to use GitHub MUST inform the Working 304 Group of their decision on the Working Group mailing list. An email 305 detailing how the Working Group intends to use GitHub is sufficient, 306 though it might be helpful to occasionally remind new contributors of 307 these guidelines. 309 Working Group Chairs are responsible for ensuring that any policy 310 they adopt is enforced and maintained. 312 The set of GitHub features (Section 4) that the Working Group relies 313 upon need to be clearly documented in policies. This document 314 provides some guidance on potential policies and how those might be 315 applied. 317 Features that the Working Group does not rely upon can be made 318 available to document editors. Editors are then able to use these 319 features for their own purposes. For example, though the Working 320 Group might not formally use issues to track items that require 321 further discussion in order to reach consensus, keeping the issue 322 tracker available to editors can be valuable. 324 Working Group policies need to be set with the goal of improving 325 transparency, participation, and ultimately the quality of documents. 327 At times, it might be appropriate to impose some limitations on what 328 document editors are able to do in order to serve these goals. 329 Chairs are encouraged to periodically consult with document editors 330 to ensure that policies are effective. 332 A document editor can still use GitHub independently for documents 333 that they edit, even if the Working Group does not expressly choose 334 to use GitHub. Any such public repository MUST follow the IETF Note 335 Well and bear notices; see Section 2.2. This recognizes that editors 336 have traditionally chosen their own methods for managing the 337 documents they edit but preserves the need for contributors to 338 understand their obligations with respect to IETF processes. 340 Work done in GitHub has no special status. The output of any 341 activity using GitHub needs to be taken to the Working Group and is 342 subject to approval, rejection, or modification by the Working Group 343 as with any other input. 345 3.2. Repositories 347 New repositories can be created within the Working Group organization 348 at the discretion of the chairs. Chairs could decide to only create 349 new repositories for adopted Working Group items, or they might 350 create repositories for individual documents on request. 352 Maintaining private repositories for Working Group products is not 353 recommended without specific cause. For instance, a document that 354 details a security vulnerability might be kept private prior to its 355 initial publication as an Internet-Draft. Once an Internet-Draft is 356 published, repositories for Working Group documents MUST be made 357 public. 359 The adoption status of any document MUST be clear from the contents 360 of the repository. This can be achieved by having the name of the 361 document reflect status (that is, draft-ietf--... indicates 362 that the document was adopted), or through a prominent notice (such 363 as in the README). 365 Experience has shown that maintaining separate repositories for 366 independent documents is most manageable. This allows the work in 367 that repository to be focused on a single item. 369 Closely related documents, such as those that together address a 370 single milestone, might be placed in a single repository. This 371 allows editors to more easily manage changes and issues that affect 372 multiple documents. 374 Maintaining multiple documents in the same repository can add 375 overhead that negatively affects individual documents. For instance, 376 issues might require additional markings to identify the document 377 that they affect. Also, because editors all have write access to the 378 repository, managing the set of people with write access to a larger 379 repository is more difficult (Section 3.3). 381 3.3. Editors and Contributors 383 Working Group chairs MUST give document editors write access to 384 document repositories. This can be done by creating teams with write 385 access and allocating editors to those teams, or by making editors 386 collaborators on the repository. 388 Working Group chairs MAY also grant other individuals write access 389 for other reasons, such as maintaining supporting code or build 390 configurations. Working Group chairs, as administrators or owners of 391 the organization might also have write access to repositories. Users 392 other than document editors, including chairs, SHOULD NOT write to 393 Working Group documents without prior coordination with document 394 editors. 396 A Working Group MAY create a team for regular contributors that is 397 only given read access to a repository. This does not confer 398 additional privileges on these contributors, it instead allows for 399 issues and pull requests to be assigned to those people. This can be 400 used to manage the assignment of editorial or review tasks to 401 individuals outside of the editor team. 403 3.4. Document Formats 405 In addition to the canonical XML format [RFC7991], document editors 406 might choose to use a different input form for editing documents, 407 such as Markdown. Markdown-based formats are more accessible for new 408 contributors, though ultimately decisions about format are left to 409 document editors. 411 Formats that are not text-based SHOULD NOT be used, as these are ill- 412 disposed to the sorts of interaction that revision control enables. 414 4. Contribution Methods 416 Contributions to documents come in many forms. GitHub provides a 417 range of options in addition to email. Input on GitHub can take the 418 form of new issues and pull requests, comments on issues and pull 419 requests, and comments on commits. 421 4.1. Issue Tracker 423 The GitHub issue tracker can be an effective way of managing the set 424 of open issues on a document. Issues - both open and closed - can be 425 a useful way of recording decisions made by a Working Group. 427 Issues can be given arbitrary labels, assigned to contributors, and 428 assembled into milestones. The issue tracker is integrated into the 429 repository; an issue can be closed using a special marker in a commit 430 message. 432 When deciding to use GitHub, Working Group Chairs MUST decide how the 433 GitHub issue tracker is used. Use of the issue tracker could be 434 limited to recording the existence of issues, or it might be used as 435 the venue for substantial technical discussion between contributors. 437 A Working Group policy MAY require that all substantive changes be 438 tracked using issues. Suggested policies for the use of the GitHub 439 issue tracker are the primary subject of Section 5. 441 4.1.1. Issue Labels 443 A system of labeling issues can be effective in managing issues. For 444 instance, marking substantive issues separately from editorial can be 445 helpful at guiding discussion. Using labels can also be helpful in 446 identifying issues for which consensus has been achieved, but that 447 require editors to integrate the changes into a document. 449 Labels can be used to identify particular categories of issues or to 450 mark specific issues for discussion at an upcoming session. 452 Chairs communicate any process that specifically relates to the use 453 of labels to the Working Group. This includes the semantics of 454 labels, and who can apply and remove these labels. Section 5.4 455 describes some basic strategies that might be adopted to manage 456 decision-making processes. 458 4.1.2. Closing Issues 460 Editors have write access to repositories, which also allows them to 461 close issues. The user that opens an issue is also able to close the 462 issue. Chairs MUST provide guidance on who is permitted to close an 463 issue and under what conditions. 465 Restrictions on who can close an issue and under what circumstances 466 are generally not advisable until a document has reached a certain 467 degree of maturity. 469 4.1.3. Reopening Issues 471 Issues that have reached a resolution that has Working Group 472 consensus MUST NOT be reopened unless new information is presented. 474 For long-running work items, new contributors often raise issues that 475 have already been resolved. Moreover, there could be temptation to 476 reopen contentious issues resolved with rough consensus. Determining 477 whether arguments presented in favor of reopening an issue represents 478 new information might require some discussion in the Working Group. 480 Chairs are empowered to exercise discretion in determining whether to 481 reopen issues. For more difficult matters, the chairs MAY insist 482 that the Working Group reach consensus on whether an issue should be 483 reopened. Note however that any product of this process still needs 484 to have the support of rough consensus in the Working Group, which 485 could justify reopening issues. 487 4.2. Pull Requests 489 A pull request is a GitHub feature that allows a user to request a 490 change to a repository. A user does not need to have write access to 491 a repository to create a pull request. A user can create a "fork", 492 or copy, of any public repository. The user has write access to 493 their own fork, allowing them to make local changes. A pull request 494 asks the owner of a repository to merge a specific set of changes 495 from a fork (or any branch) into their copy. 497 Editors are encouraged to make pull requests for all substantial 498 changes rather than committing directly to the "master" branch of the 499 repository. See Section 5.3.2 for discussion on what constitutes a 500 substantial change. A pull request creates an artifact that records 501 the reasons for changes and provides other contributors with an 502 opportunity to review the change. Ideally, pull requests that 503 address substantive issues mention the issue they address in the 504 opening comment. A Working Group policy could require that pull 505 requests are used in this fashion. 507 Note: This document assumes that there is a unified effort on a 508 document, all concentrated on a git "master" branch. More 509 advanced usage of git is not in the scope of this document. 511 Pull requests have many of the same properties as issues, including 512 the ability to host discussion and bear labels. Critically, using 513 pull requests creates a record of actions taken. 515 For significant changes, leaving a pull request open until discussion 516 of the issue within the Working Group concludes allows the pull 517 request to track the discussion and properly capture the outcome of 518 discussions. Pull requests can be updated as discussions continue or 519 in response to feedback. 521 Groups of editors could adopt a practice of having one editor create 522 a pull request and another merge it. This ensures that changes are 523 reviewed by editors. Editors are given discretion in how they manage 524 changes amongst themselves. 526 4.2.1. Discussion on Pull Requests 528 In addition to the features that pull requests share with issues, 529 users can also review the changes in a pull request. This is a 530 valuable feature, but presents some challenges. 532 Comments in a review other than a summary are attached to specific 533 lines of the proposed change. Such comments can be hard or 534 impossible to find if changes are subsequently made to the pull 535 request. This is problematic for contributors who do not track 536 discussions closely. 538 For this reason, Working Group chairs SHOULD discourage the use of 539 inline comments for substantial technical discussion of issues. 541 4.2.2. Merging Pull Requests 543 A Working Group MUST determine who is permitted to merge pull 544 requests. Document editors SHOULD be permitted to merge pull 545 requests at their discretion. This requires that editors exercise 546 some judgment. Working Group chairs MAY occasionally identify a pull 547 request and request that editors withhold merging until Working Group 548 consensus has been assessed. 550 Note that the copy of a document that is maintained on GitHub does 551 not need to be a perfect reflection of Working Group consensus at 552 every point in time. Document editors need some flexibility in how 553 they manage a document. 555 4.3. Monitoring Activity 557 GitHub produces individualized email notifications of activity that 558 each user can adjust to their preferences. In addition to these, 559 some Working Groups have created read-only mailing lists that receive 560 notifications about activity on Working Group repositories. The 561 volume of information on these lists can be too high to monitor 562 actively, but access to an archive of actions can be useful. 564 An alternative is to rely on periodic email summaries of activity, 565 such as those produced by a notification tool like github-notify-ml 566 (https://github.com/dontcallmedom/github-notify-ml). This tool has 567 been used effectively in several Working Groups, though it requires 568 server infrastructure. 570 Additionally, clear reporting about the changes that were included in 571 each revision of an Internet-Draft helps ensure that contributors can 572 follow activity. This might be achieved by requesting that editors 573 provide a change log that captures substantive changes to the 574 document in each revision. 576 5. Typical Working Group Policies 578 Current experience with use of GitHub suggests a few different 579 approaches to greater use of the tool in Working Groups. 581 This section describes some basic modes for interacting with GitHub, 582 each progressively more involved. This starts with a very 583 lightweight interaction where document management is the only feature 584 that is formally used, then progressively more intensive use of the 585 GitHub issue tracking capabilities are described. These approaches 586 differ primarily in how discussion of substantive matters is managed. 587 Most of the advice in this document applies equally to all models. 589 A Working Group can adjust these policies to suit their needs, but 590 are advised to avoid gratuitous changes for the sake of consistency 591 across the IETF as a whole. It is possible to use different 592 processes for different documents in the Working Group. 594 Working Group chairs are responsible for confirming that the Working 595 Group has consensus to adopt any process. In particular, the 596 introduction of a more tightly-controlled process can have the effect 597 of privileging positions already captured in documents, which might 598 disadvantage alternative viewpoints. 600 5.1. Document Management Mode 602 In this mode of interaction, GitHub repositories are used to manage 603 changes to documents, but the bulk of the work is conducted using 604 email, face-to-face meetings, and other more traditional 605 interactions. The intent of this policy is to enable document and 606 issue management using GitHub while minimizing the complexity of the 607 process. 609 In the version of this mode with the least interaction with GitHub, a 610 repository is created for the purposes of document management by 611 editors. Editors might maintain issues and pull requests for their 612 own benefit, but these have no formal standing in the Working Group 613 process. 615 5.2. Issue Tracking Mode 617 In addition to managing documents, the Working Group might choose to 618 use GitHub for tracking outstanding issues. In this mode of 619 interaction, a record of the existence of substantive technical 620 discussions is tracked using issues in the issue tracker. However, 621 discussion of any substantial matters is always conducted on mailing 622 lists. 624 Under this mode, issues and pull requests can be opened by anyone, 625 but anything deemed substantive MUST be resolved exclusively on the 626 mailing list. Discussion on GitHub is limited to recording the state 627 of issues. Only editorial matters can be resolved using the issue 628 tracker. 630 Chairs and editors are given discretion in determining what issues 631 are substantive. As documents mature, it is generally prudent to 632 prefer consulting the mailing list where there is doubt. As with 633 other Working Group decisions, chairs are the arbiters in case of 634 dispute. 636 A recurrent problem with this mode of interaction is the tendency for 637 discussions to spontaneously develop in the issue tracker. This 638 requires a degree of discipline from chairs and editors to ensure 639 that any substantive matters are taken to the mailing list. 641 Retaining mailing lists as the primary venue for discussion of 642 substantive matters ensures that this mode - along with the document 643 management mode - is most compatible with existing work practices for 644 Working Groups. Participants in a Working Group that operates under 645 either model can reasonably be expected to receive all relevant 646 communication about the work of the group from the Working Group 647 mailing list. 649 Though the mailing list is used for making decisions, the issue 650 tracker can still be a useful record of the state of issues. It is 651 often useful if chairs or editors record details of decisions in 652 issue comments when closing issues as resolved. 654 5.3. Issue Discussion Mode 656 This GitHub interaction mode differs from the other modes in that 657 discussion relating to substantive technical matters is allowed to 658 occur on GitHub issues. Though decisions are always subject to 659 confirmation on the mailing list, participants are permitted to 660 conduct substantive discussions on the issue tracker. In some cases, 661 this can include making some decisions without involving the Working 662 Group mailing list. 664 A Working Group mailing list remains a critical venue for decision 665 making, even where issue discussion occurs elsewhere. Working Group 666 mailing lists generally include a wider audience than those who 667 follow issue discussion, so difficult issues always benefit from list 668 discussion. 670 Decisions about Working Group consensus MUST always be confirmed 671 using the Working Group mailing list. However, depending on the 672 maturity of documents, this might be a more lightweight interaction, 673 such as sending an email confirmation for an initial set of 674 resolutions arising from discussions on the issue tracker. 676 Using the mailing list to resolve difficult or controversial issues 677 is strongly encouraged. In those cases, the issue tracker might be 678 used to more fully develop an understanding of problems before 679 initiating a discussion on the mailing list, along lines similar to 680 the design team process (see Section 6.5 of [RFC2418]). 682 As a more involved process, adopting this mode can require changes in 683 policies as documents become more mature. 685 5.3.1. Early Design Phases 687 During early phases of the design of a protocol, chairs MAY allow 688 editors to manage all aspects of issues. Editors are permitted to 689 make decisions about how to both identify and resolve technical 690 issues, including making any changes that editors feel necessary. 692 Chairs need to explicitly decide that this sort of process is needed 693 and announce the decision to the Working Group. In many cases, 694 documents that are adopted by a Working Group are already 695 sufficiently mature that a looser process is not beneficial. The 696 primary reason to grant editors more discretionary power is to 697 improve the speed with which changes can be made. The risk is from 698 integrating changes including substantive decisions that don't 699 reflect the consensus of the Working Group or that the need for 700 consensus on an issue is not identified. 702 Changes made by editors under this process do not lack options for 703 identifying and correcting problems. GitHub and git provide tools 704 for ensuring that changes are tracked and can be audited. Within the 705 usual Working Group process it is expected that Internet-Drafts will 706 receive regular review. Finally, process checkpoints like Working 707 Group Last Call (WGLC; Section 7.4 of [RFC2418]) provide additional 708 safeguards against abuse. 710 Working Groups are advised against allowing editors this degree of 711 flexibility for the entirety of a document lifecycle. Once a 712 document is more stable and mature, it could be useful to move to a 713 more tightly controlled process. 715 5.3.2. Managing Mature Documents 717 As a document matures, it becomes more important to understand not 718 just that the document as a whole retains the support of the Working 719 Group, but that changes are not made without wider consultation. 721 Chairs MAY choose to manage the process of deciding which issues are 722 substantive. For instance, chairs might reserve the ability to use 723 the "design" label to new issues (see Section 5.4.1) and to close 724 issues marked as "design". Chairs SHOULD always allow document 725 editors to identify and address editorial issues as they see fit. 727 As documents mature further, explicit confirmation of technical 728 decisions with the Working Group mailing list becomes more important. 730 Chairs can declare Working Group consensus about the resolution of 731 issues in the abstract, allowing editors discretion on how to capture 732 the decisions in documents. 734 More mature documents require not only consensus, but consensus about 735 specific text. Ideally, substantive changes to documents that have 736 passed WGLC are proposed as pull requests, and MUST be discussed on 737 the mailing list. Having chairs explicitly confirm consensus on 738 changes ensures that previous consensus decisions are not overturned 739 without cause. Chairs MAY institute this stricter process prior to 740 WGLC. 742 Note: It is generally sufficient to trust editors to manage 743 adherence with these policies, aided by the transparency provided 744 by the version control system. There are tools that can be used 745 to more tightly control access to repositories, but they can be 746 overly constraining. 748 5.4. Issue Labelling Schemes 750 Several schemes for use of issue labels in managing issues have been 751 used successfully. This section outlines these strategies and how 752 they might be applied. 754 A design/editorial split (see Section 5.4.1) is useful in all cases 755 that the issue tracking capability is used. A Working Groups that 756 only uses GitHub for issue tracking might find that distinction 757 sufficient for their needs. 759 Working Groups or editors might use additional labels as they choose. 760 Any label that is used as part of a process requires that the process 761 be documented and announced by Working Group chairs. Editors SHOULD 762 be permitted to use labels to manage issues without any formal 763 process significance being attached to those issues. 765 5.4.1. Editorial/Design Labelling 767 The most important distinction about an issue is whether it is 768 substantive. The labels of "editorial" and "design" are used to 769 represent this distinction. 771 An issue labeled as "editorial" has no substantive effect on a 772 document, except to the extent that addressing the issue might make 773 understanding the specification easier. Resolution of "editorial" 774 issues can be left to the discretion of editors. 776 An issue labeled as "design" has or might have a substantive effect 777 on a document. For protocol specifications, a "design" issue is one 778 that might affect implementations or interoperability requirements. 779 Addressing a "design" issue ultimately requires Working Group 780 consensus, even if the resolution is to make no change. 782 This distinction can be applied to all types of document. For 783 instance, a "design" issue for an Informational document might be 784 raised to discuss possible changes to important concepts in the 785 document. 787 5.4.2. Decision Labelling 789 Labels can be used to manage processes. As documents mature and 790 issues become more numerous, labels can be used to clearly mark the 791 status of issues. In particular, labelling of issues can be used to 792 help in managing Working Group decisions. 794 For documents that are less mature, issues with resolutions but no 795 specific proposals for changes to text might be marked "editor-ready" 796 as a way of signaling that there is consensus about an approach, but 797 no specific proposal. Chairs might use this to signal that 798 discussion is complete and that editors are to be given discretion in 799 the construction of text. 801 In contrast, if specific text is a prerequisite for resolving issues, 802 as might be the case for more mature documents, a "proposal-ready" 803 label might be used by editors to mark issues that they believe to 804 have acceptable resolutions. 806 For resolved issues, a "has-consensus" label might be used by chairs 807 to mark issues for which formal Working Group decisions have been 808 made (Section 6.1 of [RFC2418]). 810 A "future" or "next-version" label might be used to mark and thereby 811 save issues for a future version of or extension to a protocol, 812 particularly where a resolution is made to take no action. 814 5.4.3. Component Labelling 816 Repositories with multiple interrelated documents or a complex 817 document with multiple logical components might benefit from labels 818 that identify different aspects of the work. The choice of 819 appropriate labels for components will depend on the structure of 820 specific documents. 822 5.4.4. Other Labels 824 Other labels can be used depending on the needs of editors and 825 Working Group processes. For example, 827 * An "invalid" label might be used for issues that were raised in 828 error. 830 * A "blocked" label might indicate an issue is awaiting resolution 831 of an external process or related issue. 833 * A "parked" label might be used to indicate issues that do not 834 require immediate Working Group attention. 836 6. Internet-Draft Publication 838 During the development of a document, individual revisions of the 839 document can be built and formally submitted as an Internet-Draft. 840 This creates a stable snapshot and makes the content of the in- 841 progress document available to a wider audience. Documents submitted 842 as Internet-Drafts are not expected to address all open issues or 843 merge outstanding pull requests. 845 Section 7.1 of [RFC2418] recommends that editors create a new 846 Internet-Draft submission two weeks prior to every session, which 847 includes IETF meetings, other in-person meetings, and telephone or 848 video conferences. Though discussion could use the current version 849 of a document from version control, participants in a session cannot 850 be expected to monitor changes to documents in real-time; a published 851 Internet-Draft ensures that there is a common, stable state that is 852 known to all participants. 854 Internet-Drafts that use a GitHub repository SHOULD include a notice 855 that includes a reference to the repository. This notice might also 856 include information about where to discuss the draft. 858 Revisions used to generate documents that are submitted as Internet- 859 Drafts SHOULD be tagged in repositories to provide a record of 860 submissions. 862 Working Group chairs MAY request a revision of an Internet-Draft 863 being managed on Github at any time, in consultation with document 864 editors. 866 7. Assessing Consensus 868 The work that occurs on GitHub could be part of the consensus 869 process, but the ultimate decision on consensus regarding a document 870 is made by the chairs [RFC2026]. 872 GitHub facilitates more involved interactions, which can result in a 873 much higher level of activity than a typical Working Group mailing 874 list. Participants who wish to limit their time commitment might 875 follow GitHub activity selectively, either by following only specific 876 issues or by occasionally reviewing the state of the document. Other 877 participants might not use GitHub at all. Chairs are reminded that 878 assessing consensus based on GitHub content alone cannot be assumed 879 to reach all interested participants. 881 As described in [RFC2418], chairs consider input from all discussion 882 venues when assessing consensus. These include mailing lists, IETF 883 meetings, and interim meetings in addition to discussion on GitHub. 884 Each venue has different selection biases that might need to be 885 considered. 887 A Working Group chair MUST consult the Working Group mailing list for 888 any issue that is potentially contentious. Relying on input provided 889 through GitHub alone might result in gaining input from a narrower 890 set of participants. This includes important milestones like Working 891 Group Last-Call, where review from the widest possible audience 892 ensures a higher quality document. 894 If permitted, GitHub will be used for technical discussion and 895 decisions, especially during early stages of development of a 896 document. Any decisions are confirmed through review within the 897 Working Group, and ultimately, through Working Group Last Call; see 898 Section 7.4 of [RFC2418]. 900 The use of issues and labels has been effective in managing 901 contentious issues. Explicitly labeling closed issues to identify 902 those with formal consensus means that there is no confusion about 903 the status of issues. 905 8. Continuous Integration 907 Various third-party services offer the ability to run tests and other 908 work when changes are made to a repository. 910 One common practice is to use these continuous integration services 911 to build a text or HTML version of a document. This is then 912 published to GitHub Pages, which allows users to view a version of 913 the most recent revision of a document. Including a prominent link 914 to this version of the document (such as in the README) makes it 915 easier for new contributors to find a readable copy of the most 916 recent version of a draft. In addition, including links to 917 differences between this generated version and any published document 918 helps contributors identify recent changes. 920 Continuous integration can also validate pull requests and other 921 changes for errors. The most basic check is whether the source file 922 can be transformed successfully into a valid Internet-Draft. For 923 example, this might include checking that XML source is syntactically 924 correct. 926 For a document that uses formal languages as part of the 927 specification, such as schema or source code, a continuous 928 integration system might also be used to validate any formal language 929 that the document contains. Tests for any source code that the 930 document contains might be run, or examples might be checked for 931 correctness. 933 9. Advice to Editors 935 Document editors are primarily responsible for maintaining documents. 936 Taking on a few additional tasks can greatly improve the process for 937 the Working Group. 939 Using GitHub means that it is more likely that a contribution is made 940 by users who are not very familiar with the work. Pull requests from 941 new contributors can contain errors or omissions. Duplicate issues 942 are commonplace. Proposed changes might have grammatical errors or 943 they might diverge from existing style. If a change is generally 944 sound, rather than rejecting the pull request or requesting changes, 945 editors could instead accept the change and then make any necessary 946 corrections. 948 Editors SHOULD NOT close a pull request or issue without first 949 understanding why the item was created. Editors and chairs SHOULD 950 try to explain every action clearly and concisely. Even if a 951 contributor seems rude, being courteous in response is always best. 953 If a contributor makes a comment that raises a new issue, editors can 954 create an issue or - if there is an obvious solution - a pull 955 request. It does not matter what venue the issue was raised in 956 (e.g., email, issue discussion, a pull request review); capturing 957 issues quickly ensures that problems become visible and can be 958 tracked. 960 This takes a little more effort, but these simple steps can help 961 encourage contributions, which will ultimately improve the quality of 962 documents. 964 10. Security Considerations 966 Continuity of operations is always a consideration when taking a 967 dependency on an external service. If GitHub were to fail in some 968 way, anyone relying upon its services would be seriously affected. 970 Widespread use of git reduces the exposure to a system failure 971 because the primary repository is replicated in multiple locations. 972 This includes hosted web pages; the content of web pages is 973 maintained as a branch in the main repository. 975 However, other information maintained on GitHub is more vulnerable to 976 loss. This includes issues and discussion on those issues, 977 discussion and reviews of commits and pull requests, and any content 978 hosted on the wiki. Tools exist for extracting this information for 979 backup. 981 As specified in [GH-CONFIG], backup copies of repositories and other 982 important data SHOULD be maintained. 984 The potential for malicious actions by compromised or malcontent 985 editors, chairs and area directors is relevant in maintaining the 986 integrity of the content that GitHub hosts. Backups allow for 987 recovery of content, and regular submissions as Internet-Drafts 988 ensure that work is not lost completely. 990 A compromise of GitHub does not pose a significant threat to Working 991 Group operations as it is expected that most data, aside from 992 individual credentials, is made public. 994 Compromise of credentials could mean loss of control for repositories 995 and organizations. All contributors, especially those with commit or 996 admin privileges SHOULD use current best practices for protection of 997 credentials, such as multi-factor authentication. 999 11. IANA Considerations 1001 This document has no IANA actions. 1003 12. References 1005 12.1. Normative References 1007 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 1008 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 1009 . 1011 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1012 Requirement Levels", BCP 14, RFC 2119, 1013 DOI 10.17487/RFC2119, March 1997, 1014 . 1016 [RFC2418] Bradner, S., "IETF Working Group Guidelines and 1017 Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418, 1018 September 1998, . 1020 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1021 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1022 May 2017, . 1024 12.2. Informative References 1026 [GH-CONFIG] 1027 Cooper, A. and P. Hoffman, "Working Group GitHub 1028 Administration", Work in Progress, Internet-Draft, draft- 1029 ietf-git-github-wg-configuration-06, 13 February 2020, 1030 . 1033 [GLOSSARY] GitHub, "GitHub glossary", March 2020, 1034 . 1037 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 1038 RFC 7991, DOI 10.17487/RFC7991, December 2016, 1039 . 1041 Acknowledgments 1043 This work would not have been possible without the hard work of those 1044 people who have trialled use of GitHub at the IETF. Alia Atlas 1045 contributed significant text to an earlier version of this document. 1046 Tommy Pauly, Rich Salz, and Christopher Wood all provided significant 1047 input. 1049 Authors' Addresses 1051 Martin Thomson 1052 Mozilla 1054 Email: mt@lowentropy.net 1056 Barbara Stark 1057 AT&T 1059 Email: barbara.stark@att.com