idnits 2.17.1 draft-ietf-git-using-github-04.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (16 February 2020) is 1531 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-07) exists of draft-ietf-git-github-wg-configuration-06 ** Downref: Normative reference to an Informational draft: draft-ietf-git-github-wg-configuration (ref. 'GH-CONFIG') Summary: 1 error (**), 0 flaws (~~), 3 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: Best Current Practice B. Stark 5 Expires: 19 August 2020 AT&T 6 16 February 2020 8 Working Group GitHub Usage Guidance 9 draft-ietf-git-using-github-04 11 Abstract 13 This document describes best practices for Working Groups that use 14 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 21 (https://mailarchive.ietf.org/arch/search?email_list=ietf-and- 22 github). 24 Source for this draft and an issue tracker can be found at 25 https://github.com/ietf-gitwg/using-github (https://github.com/ietf- 26 gitwg/using-github). 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on 19 August 2020. 45 Copyright Notice 47 Copyright (c) 2020 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 52 license-info) in effect on the date of publication of this document. 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. Code Components 55 extracted from this document must include Simplified BSD License text 56 as described in Section 4.e of the Trust Legal Provisions and are 57 provided without warranty as described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. Distributed Version Control Systems . . . . . . . . . . . 4 63 1.2. GitHub . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 1.3. Other Services . . . . . . . . . . . . . . . . . . . . . 4 65 1.4. Document Goals . . . . . . . . . . . . . . . . . . . . . 5 66 1.5. Notational Conventions . . . . . . . . . . . . . . . . . 5 67 2. Administrative Policies . . . . . . . . . . . . . . . . . . . 5 68 2.1. Organizations . . . . . . . . . . . . . . . . . . . . . . 5 69 2.2. Communicating Policies . . . . . . . . . . . . . . . . . 6 70 3. Deciding to Use GitHub . . . . . . . . . . . . . . . . . . . 7 71 3.1. What to Use GitHub For . . . . . . . . . . . . . . . . . 7 72 3.2. Repositories . . . . . . . . . . . . . . . . . . . . . . 8 73 3.3. Editors and Contributors . . . . . . . . . . . . . . . . 9 74 3.4. Document Formats . . . . . . . . . . . . . . . . . . . . 9 75 4. Contribution Methods . . . . . . . . . . . . . . . . . . . . 9 76 4.1. Issue Tracker . . . . . . . . . . . . . . . . . . . . . . 9 77 4.1.1. Issue Labels . . . . . . . . . . . . . . . . . . . . 10 78 4.1.2. Closing Issues . . . . . . . . . . . . . . . . . . . 10 79 4.1.3. Reopening Issues . . . . . . . . . . . . . . . . . . 10 80 4.2. Pull Requests . . . . . . . . . . . . . . . . . . . . . . 11 81 4.2.1. Discussion on Pull Requests . . . . . . . . . . . . . 11 82 4.2.2. Merging Pull Requests . . . . . . . . . . . . . . . . 12 83 4.3. Monitoring Activity . . . . . . . . . . . . . . . . . . . 12 84 5. Typical Working Group Policies . . . . . . . . . . . . . . . 12 85 5.1. Document Management Mode . . . . . . . . . . . . . . . . 13 86 5.2. Issue Tracking Mode . . . . . . . . . . . . . . . . . . . 13 87 5.3. Issue Discussion Mode . . . . . . . . . . . . . . . . . . 14 88 5.3.1. Early Design Phases . . . . . . . . . . . . . . . . . 15 89 5.3.2. Managing Mature Documents . . . . . . . . . . . . . . 15 90 5.4. Issue Labelling Schemes . . . . . . . . . . . . . . . . . 16 91 5.4.1. Editorial/Design Labelling . . . . . . . . . . . . . 16 92 5.4.2. Decision Labelling . . . . . . . . . . . . . . . . . 17 93 5.4.3. Component Labelling . . . . . . . . . . . . . . . . . 17 94 5.4.4. Other Labels . . . . . . . . . . . . . . . . . . . . 17 95 6. Internet-Draft Publication . . . . . . . . . . . . . . . . . 18 96 7. Assessing Consensus . . . . . . . . . . . . . . . . . . . . . 18 97 8. Continuous Integration . . . . . . . . . . . . . . . . . . . 19 98 9. Advice to Editors . . . . . . . . . . . . . . . . . . . . . . 20 99 10. Security Considerations . . . . . . . . . . . . . . . . . . . 20 100 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 101 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 102 12.1. Normative References . . . . . . . . . . . . . . . . . . 21 103 12.2. Informative References . . . . . . . . . . . . . . . . . 21 104 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 22 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 107 1. Introduction 109 The IETF has an open and transparent process for developing 110 standards. The use of GitHub (https://github.com/) or similar tools, 111 when used as part of this process, can have several objectives. 112 GitHub provides tools that can be helpful in editing documents. Use 113 of this service has been found to reduce the time that Working Groups 114 need to produce documents and to improve the quality of the final 115 result. 117 The use of version control improves traceability and visibility of 118 changes. Issue tracking can be used to manage open issues and 119 provide a record of their resolution. Pull requests allow for better 120 engagement on technical and editorial changes, and encourage 121 contributions from a larger set of contributors. Using GitHub can 122 also broaden the community of contributors for a specification. 124 The main purpose of this document is providing guidelines for how 125 Working Groups might integrate the capabilities provided by GitHub 126 into their processes for developing Internet-Drafts. 128 This document is meant as a supplement to existing Working Group 129 practices. It provides guidance to Working Group chairs and 130 participants on how they can best use GitHub within the framework 131 established by RFC 2418 [RFC2418]. This document aims to establish 132 norms that reduce the variation in usage patterns between different 133 Working Groups and to help avoid issues that have been encountered in 134 the past. 136 A companion document, [GH-CONFIG], describes administrative processes 137 that support the practices described in this document. 139 Although similar, guidance for IRTF Research Groups is out of scope 140 for this document. However, such groups may draw inspiration for 141 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/ 158 (https://github.com/). GitHub provides centralized storage for git 159 repositories. GitHub is freely accessible on the open Internet, 160 albeit currently only via IPv4. 162 GitHub provides a simplified and integrated interface to not only 163 git, but also provides basic user management, an issue tracker, 164 associated wikis, project hosting, and other features. 166 There are a large number of projects at GitHub and a very large 167 community of contributors. One way in which some IETF Working Groups 168 have benefited is through increased numbers of reviews and associated 169 issues, along with other improvements that come from broader 170 participation by facilitating those in the community to participate. 172 1.3. Other Services 174 Git is not the only version control system available, nor is GitHub 175 the only possible choice for hosting. There are other services that 176 host revision control repositories and provide similar additional 177 features to GitHub. For instance, BitBucket (https://bitbucket.org/) 178 and GitLab (https://about.gitlab.com/) provide similar feature sets. 179 In addition to a hosted service, software for custom installations 180 exists. 182 This document concentrates primarily on GitHub as it has a large and 183 active community of contributors. As a result, some content might 184 not be applicable to other similar services. A Working Group that 185 decides to adopt an alternative tool or service can still benefit 186 from the general guidance in this document. 188 1.4. Document Goals 190 This document aims to describe how a Working Group might best apply 191 GitHub to their work. The intent is to allow each Working Group 192 considerable flexibility in how they use GitHub. 194 This document requires that policies for use of GitHub are agreed and 195 clearly communicated within the Working Group (see Section 2). The 196 remainder of the document contains guidelines and advice on how to 197 construct a workable policy. 199 The requirements here apply to the case where Working Groups decide 200 to use GitHub as a primary means of interaction. Individuals can set 201 their own policies when using GitHub for managing their own drafts, 202 or for managing drafts that they edit on behalf of a Working Group 203 that has not explicitly adopted GitHub. 205 For both sets of users, this document aims to provide some amount of 206 advice on practices that have been effective. 208 This document only aims to address use of GitHub in developing 209 documents. Working Groups could choose to use the tool to aid in 210 managing their charter or session materials such as agendas, minutes, 211 and presentations. Though the advice here might apply more broadly, 212 using GitHub to manage other material is out of scope for this 213 document. 215 1.5. Notational Conventions 217 The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are 218 used in this document. It's not shouting; when they are capitalized, 219 they have the special meaning defined in BCP 14 [RFC2119] [RFC8174]. 221 2. Administrative Policies 223 The following administrative rules provide the necessary oversight 224 and transparency. 226 2.1. Organizations 228 Organizations are a way of forming groups of contributors on GitHub. 229 Each Working Group SHOULD create a new organization for the Working 230 Group. A Working Group organization SHOULD be named consistently so 231 that it can be found. For instance, the name could be ietf- 232 wg-, as recommended in [GH-CONFIG]. 234 A single organization SHOULD NOT be used for all IETF activity, or 235 all activity within an area. Large organizations create too much 236 overhead for general management tasks, particularly when there is a 237 need to maintain membership. 239 Each organization requires owners. The owner team for a Working 240 Group repository MUST include responsible Area Directors. Area 241 Directors MAY also designate a delegate that becomes an owner and 242 Working Group chairs MAY also be owners. 244 A team with administrator access SHOULD be created for the Working 245 Group Chairs and any Working Group Secretary. Administrator access 246 is preferable, since this does not also include the ability to push 247 to all repositories and ownership does not grant any other 248 significant privileges. 250 Details about creating organizations adhering to these guidelines can 251 be found in [GH-CONFIG]. 253 2.2. Communicating Policies 255 Each Working Group MAY set its own policy as to whether and how it 256 uses GitHub. It is important that occasional participants in the WG 257 and others accustomed to IETF tools be able to determine this and 258 easily find the policy and GitHub organization. 260 A simple example of how to do this is to include a link to the GitHub 261 organization on the WG Charter page in the datatracker. Similarly, 262 if there are multiple mailing list options, links to those mailing 263 lists should be given. 265 Repositories MUST include a copy or reference to the policy that 266 applies to managing any documents they contain. Updating the README 267 or CONTRIBUTING file in the repository with details of the process 268 ensures that the process is recorded in a stable location other than 269 the mailing list archive. This also makes Working Group policies 270 available to casual contributors who might only interact with the 271 GitHub repository. 273 GitHub prominently links to the CONTRIBUTING file on certain pages. 274 This file SHOULD be used in preference to the README for information 275 that new contributors need. The README SHOULD contain a link to the 276 CONTRIBUTING file. 278 In addition to Working Group policies, notices on repositories MUST 279 include citations for the IETF Note Well (https://www.ietf.org/about/ 280 note-well/). 282 3. Deciding to Use GitHub 284 Working Group Chairs are responsible for determining how to best 285 accomplish the charter objectives in an open and transparent fashion. 286 The Working Group Chairs are responsible for determining if there is 287 interest in using GitHub and making a consensus call to determine if 288 the proposed policy and use is acceptable. 290 Chairs MUST involve Area Directors in any decision to use GitHub for 291 anything more than managing drafts. 293 3.1. What to Use GitHub For 295 Working Group Chairs decide what GitHub features the Working Group 296 will rely upon. Section 4 contains a more thorough discussion on the 297 different features that can be used. 299 Working Group Chairs who decide to use GitHub MUST inform their 300 Working Groups of their decision on the Working Group mailing list. 301 An email detailing how the Working Group intends to use GitHub is 302 sufficient, though it might be helpful to occasionally remind new 303 contributors of these guidelines. 305 Working Group Chairs are responsible for ensuring that any policy 306 they adopt is enforced and maintained. 308 The set of GitHub features (Section 4) that the Working Group relies 309 upon need to be clearly documented in policies. This document 310 provides some guidance on potential policies and how those might be 311 applied. 313 Features that the Working Group does not rely upon SHOULD be made 314 available to document editors. Editors are then able to use these 315 features for their own purposes. For example, though the Working 316 Group might not formally use issues to track items that require 317 further discussion in order to reach consensus, keeping the issue 318 tracker available to editors can be valuable. 320 Working Group policies need to be set with the goal of improving 321 transparency, participation, and ultimately the quality of the 322 consensus behind documents. At times, it might be appropriate to 323 impose some limitations on what document editors are able to do in 324 order to serve these goals. Chairs SHOULD periodically consult with 325 document editors to ensure that policies are effective. 327 A document editor can still use GitHub independently for documents 328 that they edit, even if the Working Group does not expressly choose 329 to use GitHub. Any such public repository MUST follow the IETF Note 330 Well and bear notices; see Section 2.2. This recognizes that editors 331 have traditionally chosen their own methods for managing the 332 documents they edit but preserves the need for contributors to 333 understand their obligations with respect to IETF processes. 335 Work done in GitHub has no special status. The output of any 336 activity using GitHub needs to be taken to the Working Group and is 337 subject to approval, rejection, or modification by the Working Group 338 as with any other input. 340 3.2. Repositories 342 New repositories can be created within the Working Group organization 343 at the discretion of the chairs. Chairs could decide to only create 344 new repositories for adopted Working Group items, or they might 345 create repositories for individual documents on request. 347 All repositories for Working Group documents within the Working Group 348 organization MUST be public. Repositories for private documents MAY 349 be kept private, but only where there is a specific reason for doing 350 so. For instance, a document that details a security vulnerability 351 might be kept private prior to its initial publication as an 352 Internet-Draft. Once an Internet-Draft is published, repositories 353 SHOULD be made public. 355 The adoption status of any document MUST be clear from the contents 356 of the repository. This can be achieved by having the name of the 357 document reflect status (that is, draft-ietf--... indicates 358 that the document was adopted), or through a prominent notice (such 359 as in the README). 361 Experience has shown that maintaining separate repositories for 362 independent documents is most manageable. This allows the work in 363 that repository to be focused on a single item. 365 Closely related documents, such as those that together address a 366 single milestone, might be placed in a single repository. This 367 allows editors to more easily manage changes and issues that affect 368 multiple documents. 370 Maintaining multiple documents in the same repository can add 371 overhead that negatively affects individual documents. For instance, 372 issues might require additional markings to identify the document 373 that they affect. Also, because editors all have write access to the 374 repository, managing the set of people with write access to a larger 375 repository is more difficult (Section 3.3). 377 3.3. Editors and Contributors 379 Working Group chairs MUST give document editors write access to 380 document repositories. This can be done by creating teams with write 381 access and allocating editors to those teams, or by making editors 382 collaborators on the repository. 384 Working Group chairs MAY also grant other individuals write access 385 for other reasons, such as maintaining supporting code or build 386 configurations. Working Group chairs, as administrators or owners of 387 the organization might also have write access to repositories. Users 388 other than document editors, including chairs, SHOULD NOT write to 389 Working Group documents without prior coordination with document 390 editors. 392 Working Groups MAY create a team for regular contributors that is 393 only given read access to a repository. This does not confer 394 additional privileges on these contributors, it instead allows for 395 issues and pull requests to be assigned to those people. This can be 396 used to manage the assignment of editorial or review tasks to 397 individuals outside of the editor team. 399 3.4. Document Formats 401 In addition to the canonical XML format [RFC7991], document editors 402 might choose to use a different input form for editing documents, 403 such as Markdown. Markdown-based formats are more accessible for new 404 contributors, though ultimately decisions about format is left to 405 document editors. 407 Formats that are not text-based SHOULD NOT be used, as these are ill- 408 disposed to the sorts of interaction that revision control enables. 410 4. Contribution Methods 412 Contributions to documents come in many forms. GitHub provides a 413 range of options in addition to email. Input on GitHub can take the 414 form of new issues and pull requests, comments on issues and pull 415 requests, and comments on commits. 417 4.1. Issue Tracker 419 The GitHub issue tracker can be an effective way of managing the set 420 of open issues on a document. Issues - both open and closed - can be 421 a useful way of recording decisions made by a Working Group. 423 Issues can be given arbitrary labels, assigned to contributors, and 424 assembled into milestones. The issue tracker is integrated into the 425 repository; an issue can be closed using a special marker in a commit 426 message. 428 When deciding to use GitHub, Working Group Chairs MUST decide how the 429 GitHub issue tracker is used. Use of the issue tracker could be 430 limited to recording the existence of issues, or it might be used as 431 the venue for substantial technical discussion between contributors. 433 A Working Group policy MAY require that all substantive changes be 434 tracked using issues. Suggested policies for the use of the GitHub 435 issue tracker are the primary subject of Section 5. 437 4.1.1. Issue Labels 439 A system of labeling issues can be effective in managing issues. For 440 instance, marking substantive issues separately from editorial can be 441 helpful at guiding discussion. Using labels can also be helpful in 442 identifying issues for which consensus has been achieved, but that 443 require editors to integrate the changes into a document. 445 Labels can be used to identify particular categories of issues or to 446 mark specific issues for discussion at an upcoming session. 448 If labels are a core part of Working Group process, chairs MUST 449 communicate any process to the Working Group. This includes the 450 semantics of labels, and who can apply and remove these labels. 451 Section 5.4 describes some basic strategies that might be adopted to 452 manage decision-making processes. 454 4.1.2. Closing Issues 456 Editors have write access to repositories, which also allows them to 457 close issues. The user that opens an issue is also able to close the 458 issue. Chairs MUST provide guidance on who is permitted to close an 459 issue and under what conditions. 461 Restrictions on who can close an issue and under what circumstances 462 are generally not advisable until a document has reached a certain 463 degree of maturity. 465 4.1.3. Reopening Issues 467 Issues that have reached a resolution that has Working Group 468 consensus MUST NOT be reopened unless new information is presented. 470 For long-running work items, new contributors often raise issues that 471 have already been resolved. Chairs need to assess whether the 472 arguments offered represent new information or not. This can require 473 some discussion to determine accurately. Resolved issues MUST remain 474 closed unless there is consensus to reopen an issue. 476 4.2. Pull Requests 478 Pull requests are the GitHub feature that allow users to request 479 changes to a repository. A user does not need to have write access 480 to a repository to create a pull request. A user can create a 481 "fork", or copy, of any public repository. The user has write access 482 to their own fork, allowing them to make local changes. A pull 483 request asks the owner of a repository to merge a specific set of 484 changes from a fork (or any branch) into their copy. 486 Editors SHOULD make pull requests for all substantial changes rather 487 than committing directly to the "master" branch of the repository. 488 See Section 5.3.2 for discussion on what constitutes a substantial 489 change. A pull request creates an artifact that records the reasons 490 for changes and provides other contributors with an opportunity to 491 review the change. Pull requests that address substantive issues 492 SHOULD mention the issue they address in the opening comment. 494 Note: This document assumes that there is a unified effort on a 495 document, all concentrated on a git "master" branch. More 496 advanced usage of git is not in the scope of this document. 498 Pull requests have many of the same properties as issues, including 499 the ability to host discussion and bear labels. Critically, using 500 pull requests creates a record of actions taken. 502 For significant changes, leaving a pull request open until discussion 503 of the issue within the Working Group concludes allows the pull 504 request to track the discussion and properly capture the outcome of 505 discussions. Pull requests can be updated as discussions continue or 506 in response to feedback. 508 Groups of editors could adopt a practice of having one editor create 509 a pull request and another merge it. This ensures that changes are 510 reviewed by editors. Editors are given discretion in how they manage 511 changes amongst themselves. 513 4.2.1. Discussion on Pull Requests 515 In addition to the features that pull requests share with issues, 516 users can also review the changes in a pull request. This is a 517 valuable feature, but it has some issues. 519 Comments in a review other than a summary are attached to specific 520 lines of the proposed change. Such comments can be hard or 521 impossible to find if changes are subsequently made to the pull 522 request. This is problematic for contributors who do not track 523 discussion closely. 525 For this reason, Working Group chairs SHOULD discourage the use of 526 inline comments for substantial technical discussion of issues. 528 4.2.2. Merging Pull Requests 530 Working Groups MUST determine who is permitted to merge pull 531 requests. Document editors SHOULD be permitted to merge pull 532 requests at their discretion. This requires that editors exercise 533 some judgment. Working Group chairs MAY occasionally identify a pull 534 request and request that editors withhold merging until Working Group 535 consensus has been assessed. 537 Note that the copy of a document that is maintained on GitHub does 538 not need to be a perfect reflection of Working Group consensus at 539 every point in time. Document editors need some flexibility in how 540 they manage a document. 542 4.3. Monitoring Activity 544 GitHub produces individualized email notifications of activity that 545 each user can adjust to their preferences. In addition to these, 546 some Working Groups have created read-only mailing lists that receive 547 notifications about activity on Working Group repositories. The 548 volume of information on these lists can be too high to monitor 549 actively, but access to an archive of actions can be useful. 551 An alternative is to rely on periodic email summaries of activity, 552 such as those produced by a notification tool like github-notify-ml 553 (https://github.com/dontcallmedom/github-notify-ml). This tool has 554 been used effectively in several Working Groups, though it requires 555 server infrastructure. 557 5. Typical Working Group Policies 559 Current experience with use of GitHub suggests a few different 560 approaches to greater use of the tool in Working Groups. 562 This section describes some basic modes for interacting with GitHub, 563 each progressively more involved. This starts with a very 564 lightweight interaction where document management is the only feature 565 that is formally used, then progressively more intensive use of the 566 GitHub issue tracking capabilities are described. These approaches 567 differ primarily in how discussion of substantive matters is managed. 568 Most of the advice in this document applies equally to all models. 570 Working Groups can adjust these policies to suit their needs, but are 571 advised to avoid gratuitous changes for the sake of consistency 572 across the IETF as a whole. 574 5.1. Document Management Mode 576 In this mode of interaction, GitHub repositories are used to manage 577 changes to documents, but the bulk of the work is conducted using 578 email, face-to-face meetings, and other more traditional 579 interactions. The intent of this policy is to enable document and 580 issue management using GitHub while minimizing the complexity of the 581 process. 583 In the version of this mode with the least interaction with GitHub, a 584 repository is created for the purposes of document management by 585 editors. Editors might maintain issues and pull requests for their 586 own benefit, but these have no formal standing in the Working Group 587 process. 589 5.2. Issue Tracking Mode 591 In addition to managing documents, the Working Group might choose to 592 use GitHub for tracking outstanding issues. In this mode of 593 interaction, all substantive technical discussions are tracked as 594 issues in the issue tracker. However, discussion of any substantial 595 matters is always conducted on mailing lists. 597 Under this mode, issues and pull requests can be opened by anyone, 598 but anything deemed substantive MUST be resolved exclusively on the 599 mailing list. Discussion on GitHub is kept to a minimum. Only 600 editorial matters can be resolved using the issue tracker. 602 Chairs and editors are given discretion in determining what issues 603 are substantive. As documents mature, it is generally prudent to err 604 more toward consulting the mailing list where there is doubt. As 605 with other Working Group decisions, chairs are the arbiters in case 606 of dispute. 608 A recurrent problem with this mode of interaction is the tendency for 609 discussions to spontaneously develop in the issue tracker. This 610 requires a degree of discipline from chairs and editors to ensure 611 that any substantive matters are taken to the mailing list. 613 As mailing lists remain the primary venue for discussion of 614 substantive matters, this mode and the document management only modes 615 remain those most compatible with existing work practices for Working 616 Groups. Participants in a Working Group that operates under either 617 model can reasonably be expected to receive all relevant 618 communication about the work of the group from the Working Group 619 mailing list. 621 Though the mailing list is used for making decisions, the issue 622 tracker can still be a useful record of the state of issues. It is 623 often useful if chairs or editors record details of decisions in 624 issue comments when closing issues as resolved. 626 5.3. Issue Discussion Mode 628 This GitHub interaction mode differs from the other modes in that 629 discussion relating to substantive technical matters is allowed to 630 occur on GitHub issues. Though decisions are always subject to 631 confirmation on the mailing list, participants are permitted to 632 conduct substantive discussions on the issue tracker. In some cases, 633 this can include making some decisions without involving the Working 634 Group mailing list. 636 A Working Group mailing list remains a critical venue for decision 637 making, even where issue discussion occurs elsewhere. Working Group 638 mailing lists generally include a wider audience than those who 639 follow issue discussion, so difficult issues always benefit from list 640 discussion. 642 Decisions about Working Group consensus MUST always be confirmed 643 using the Working Group mailing list. However, depending on the 644 maturity of documents, this might be a more lightweight interaction, 645 such as sending an email confirmation for a set of resolutions made 646 using GitHub. 648 Using the mailing list to resolve difficult or controversial issues 649 is strongly encouraged. In those cases, the issue tracker might be 650 used to more fully develop an understanding of problems before 651 initiating a discussion on the mailing list, along lines similar to 652 the design team process (see Section 6.5 of [RFC2418]). 654 As a more involved process, adopting this mode can require changes in 655 policies as documents become more mature. It is possible to use 656 different processes for different documents in the Working Group. 658 Working Group chairs SHOULD confirm that the Working Group has 659 consensus to adopt any process. In particular, the introduction of a 660 more tightly-controlled process can have the effect of privileging 661 positions already captured in documents, which might disadvantage 662 alternative viewpoints. 664 5.3.1. Early Design Phases 666 During early phases of the design of a protocol, chairs MAY allow 667 editors to manage all aspects of issues. Editors are permitted to 668 make decisions about how to both identify and resolve technical 669 issues, including making any changes that editors feel necessary. 671 Chairs need to explicitly decide that this sort of process is needed 672 and announce the decision to the Working Group. In many cases, 673 documents that are adopted by a Working Group are already 674 sufficiently mature that a looser process is not beneficial. The 675 primary reason to grant editors more discretionary power is to 676 improve the speed with which changes can be made. The risk is that 677 design changes might not always reflect the consensus of the Working 678 Group. 680 Changes made by editors under this process do not completely lack 681 oversight. GitHub and git provide tools for ensuring that changes 682 are tracked and can be audited. Within the usual Working Group 683 process it is expected that Internet-Drafts will receive regular 684 review. Finally, process checkpoints like Working Group Last Call 685 (WGLC; Section 7.4 of [RFC2418]) provides additional safeguards 686 against abuse. 688 Working Groups are advised against allowing editors this degree of 689 flexibility for the entirety of a document lifecycle. Once a 690 document is more stable and mature, it is likely appropriate to move 691 to a more tightly controlled process. 693 5.3.2. Managing Mature Documents 695 As a document matures, it becomes more important to understand not 696 just that the document as a whole retains the support of the Working 697 Group, but that changes are not made without wider consultation. 699 Chairs might choose to manage the process of deciding which issues 700 are substantive. For instance, chairs might reserve the ability to 701 use the "design" label to new issues (see Section 5.4.1) and to close 702 issues marked as "design". Chairs should always allow document 703 editors to identify and address editorial issues as they see fit. 705 As documents mature further, explicit confirmation of technical 706 decisions with the Working Group mailing list becomes more important. 708 Gaining Working Group consensus about the resolution of issues can be 709 done in the abstract, with editors being permitted to capture the 710 outcome of discussions as they see fit. 712 More mature documents require not only consensus, but consensus about 713 specific text. All substantive changes to documents that have passed 714 WGLC SHOULD be proposed as pull requests, and MUST be discussed on 715 the mailing list, and MUST have chairs explicitly confirm consensus. 716 Chairs MAY institute this stricter process prior to WGLC. 718 Note: It is generally sufficient to trust editors to manage 719 adherence with these policies, aided by the transparency provided 720 by the version control system. There are tools that can be used 721 to more tightly control access to repositories, but they can be 722 overly constraining. 724 5.4. Issue Labelling Schemes 726 Several schemes for use of issue labels in managing issues have been 727 used successfully. This section outlines these strategies and how 728 they might be applied. 730 A design/editorial split (see Section 5.4.1) is useful in all cases 731 that the issue tracking capability is used. Working Groups that only 732 use GitHub for issue tracking might find that distinction sufficient 733 for their needs. 735 Working Groups or editors might use additional labels as they choose. 736 Any label that is used as part of a process requires that the process 737 be documented and announced by Working Group chairs. Editors SHOULD 738 be permitted to use labels to manage issues without any formal 739 process significance being attached to those issues. 741 5.4.1. Editorial/Design Labelling 743 The most important distinction about an issue is whether it is 744 substantive. The labels of "editorial" and "design" are used to 745 represent this distinction. 747 An issue labeled as "editorial" has no substantive effect on a 748 document, except to the extent that addressing the issue might make 749 understanding the specification easier. Resolution of "editorial" 750 issues can be left to the discretion of editors. 752 An issue labeled as "design" has or might have a substantive effect 753 on a document. For protocol specifications, a "design" issue is one 754 that might affect implementations or interoperability requirements. 755 Addressing a "design" issue ultimately requires Working Group 756 consensus, even if the resolution is to make no change. 758 This distinction can be applied to all types of document. For 759 instance, a "design" issue for an Informational document might be 760 raised to discuss possible changes to important concepts in the 761 document. 763 5.4.2. Decision Labelling 765 Labels can be used to manage processes. As documents mature and 766 issues become more numerous, labels can be used to clearly mark the 767 status of issues. In particular, labelling of issues can be used to 768 help in managing Working Group decisions. 770 For documents that are less mature, issues with resolutions but no 771 specific proposals for changes to text might be marked "editor-ready" 772 as a way of signaling that there is consensus about an approach, but 773 no specific proposal. Chairs might use this to signal that 774 discussion is complete and that editors are to be given discretion in 775 the construction of text. 777 In contrast, if specific text is a prerequisite for resolving issues, 778 as might be the case for more mature documents, a "proposal-ready" 779 label might be used by editors to mark issues that they believe to 780 have acceptable resolutions. 782 For resolved issues, a "has-consensus" label might be used by chairs 783 to mark issues for which formal Working Group decisions have been 784 made (Section 6.1 of [RFC2418]). 786 A "v2" or "next-version" label might be used to mark and thereby save 787 issues for a future version of or extension to a protocol, 788 particularly where a resolution is made to take no action. 790 5.4.3. Component Labelling 792 Repositories with multiple interrelated documents or a complex 793 document with multiple logical components might benefit from labels 794 that identify different aspects of the work. The choice of 795 appropriate labels for components will depend on the structure of 796 specific documents. 798 5.4.4. Other Labels 800 Other labels can be used depending on the needs of editors and 801 Working Group processes. For example, 803 * An "invalid" label might be used for issues that were raised in 804 error. 806 * A "blocked" label might indicate an issue is awaiting resolution 807 of an external process or related issue. 809 * A "parked" label might be used to indicate issues that do not 810 require immediate Working Group attention. 812 6. Internet-Draft Publication 814 During the development of a document, individual revisions of a 815 document can be built and formally submitted as an Internet-Draft. 816 This creates a stable snapshot and makes the content of the in- 817 progress document available to a wider audience. Documents submitted 818 as Internet-Drafts are not expected to address all open issues or 819 merge outstanding pull requests. 821 Editors SHOULD create a new Internet-Draft submission two weeks prior 822 to every session, which includes IETF meetings, other in-person 823 meetings, and telephone or video conferences (see Section 7.1 of 824 [RFC2418]). Though discussion could use the current version of a 825 document from version control, participants in a session cannot be 826 expected to monitor changes to documents in real-time; a published 827 Internet-Draft ensures that there is a common, stable state that is 828 known to all participants. 830 Internet-Drafts that use a GitHub repository SHOULD include a notice 831 that includes a reference to the repository. This notice might also 832 include information about where to discuss the draft. 834 Revisions used to generate documents that are submitted as Internet- 835 Drafts SHOULD be tagged in repositories to provide a record of 836 submissions. 838 Working Group chairs MAY request a revision of an Internet-Draft 839 being managed on Github at any time, in consultation with document 840 editors. 842 7. Assessing Consensus 844 The work that occurs on GitHub could be part of the consensus 845 process, but the ultimate decision on consensus regarding a document 846 is made by the chairs [RFC2026]. 848 GitHub facilitates more involved interactions, which can result in a 849 much higher level of activity than a typical Working Group mailing 850 list. Participants who wish to limit their time commitment might 851 follow GitHub activity selectively, either by following only specific 852 issues or by occasionally reviewing the state of the document. Other 853 participants might not use GitHub at all. Chairs are reminded that 854 assessing consensus based on GitHub content alone cannot be assumed 855 to reach all interested participants. 857 Chairs MUST consider input from all discussion venues when assessing 858 consensus including GitHub, mailing lists, interim meetings, and IETF 859 meetings. Each venue has different selection biases that might need 860 to be considered. 862 A Working Group chair MUST consult the Working Group mailing list for 863 any issue that is potentially contentious. Relying on input provided 864 through GitHub alone might result in gaining input from a narrower 865 set of participants. This includes important milestones like Working 866 Group Last-Call, where review from the widest possible audience 867 ensures a higher quality document. 869 If permitted, GitHub will be used for technical discussion and 870 decisions, especially during early stages of development of a 871 document. Any decisions are ultimately confirmed through review, and 872 ultimately, through Working Group Last Call (see Section 7.4 of 873 [RFC2418]). 875 The use of issues and labels has been effective in managing 876 contentious issues. Explicitly labeling closed issues to identify 877 those with formal consensus means that there is no confusion about 878 the status of issues. 880 8. Continuous Integration 882 Various third-party services offer the ability to run tests and other 883 work when changes are made to a repository. 885 One common practice is to use these continuous integration services 886 to build a text or HTML version of a document. This is then 887 published to GitHub Pages, which allows users to view a version of 888 the most recent revision of a document. Including a prominent link 889 to this version of the document (such as in the README) makes it 890 easier for new contributors to find a readable copy of the most 891 recent version of a draft. In addition, including links to 892 differences between this generated version and any published document 893 helps contributors identify recent changes. 895 Continuous integration can also validate pull requests and other 896 changes for errors. The most basic check is whether the source file 897 can be transformed successfully into a valid Internet-Draft. For 898 example, this might include checking that XML source is syntactically 899 correct. 901 For a document that uses formal languages as part of the 902 specification, such as schema or source code, a continuous 903 integration system might also be used to validate any formal language 904 that the document contains. Tests for any source code that the 905 document contains might be run, or examples might be checked for 906 correctness. 908 9. Advice to Editors 910 Document editors are primarily responsible for maintaining documents. 911 Taking on a few additional tasks can greatly improve the process for 912 the Working Group. 914 Using GitHub means that it is more likely that a contribution is made 915 by users who are not very familiar with the work. Pull requests from 916 new contributors can contain errors or omissions. Duplicate issues 917 are commonplace. Proposed changes might have grammatical errors or 918 they might diverge from existing style. If a change is generally 919 sound, rather than rejecting the pull request or requesting changes, 920 editors could instead accept the change and then make any necessary 921 corrections. 923 Editors SHOULD NOT close a pull request or issue without first 924 understanding why the item was created. Editors and chairs SHOULD 925 try to explain every action clearly and concisely. Even if a 926 contributor seems rude, being courteous in response is always best. 928 If a contributor makes a comment that raises a new issue, editors can 929 create an issue or - if there is an obvious solution - a pull 930 request. It does not matter what venue the issue was raised in 931 (e.g., email, issue discussion, a pull request review); capturing 932 issues quickly ensures that problems become visible and can be 933 tracked. 935 This takes a little more effort, but these simple steps can help 936 encourage contributions, which will ultimately improve the quality of 937 documents. 939 10. Security Considerations 941 Continuity of operations is always a consideration when taking a 942 dependency on an external service. If GitHub were to fail in some 943 way, anyone relying upon its services would be seriously affected. 945 Widespread use of git reduces the exposure to a system failure 946 because the primary repository is replicated in multiple locations. 947 This includes hosted web pages; the content of web pages is 948 maintained as a branch in the main repository. As specified in 949 [GH-CONFIG], maintaining a mirror of a repository hosted on GitHub 950 provides IETF-hosted backups for WG repositories. 952 However, other information maintained on GitHub is more vulnerable to 953 loss. This includes issues and discussion on those issues, 954 discussion and reviews of commits and pull requests, and any content 955 hosted on the wiki. Tools exist for extracting this information for 956 backup. 958 The potential for malicious actions by compromised or malcontent 959 editors, chairs and area directors is relevant in maintaining the 960 integrity of the content that GitHub hosts. Backups allow for 961 recovery of content, and regular submissions as Internet-Drafts 962 ensure that work is not lost completely. 964 11. IANA Considerations 966 This document has no IANA actions. 968 12. References 970 12.1. Normative References 972 [GH-CONFIG] 973 Cooper, A. and P. Hoffman, "Working Group GitHub 974 Administration", Work in Progress, Internet-Draft, draft- 975 ietf-git-github-wg-configuration-06, 13 February 2020, 976 . 979 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 980 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 981 . 983 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 984 Requirement Levels", BCP 14, RFC 2119, 985 DOI 10.17487/RFC2119, March 1997, 986 . 988 [RFC2418] Bradner, S., "IETF Working Group Guidelines and 989 Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418, 990 September 1998, . 992 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 993 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 994 May 2017, . 996 12.2. Informative References 998 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 999 RFC 7991, DOI 10.17487/RFC7991, December 2016, 1000 . 1002 Acknowledgments 1004 This work would not have been possible without the hard work of those 1005 people who have trialled use of GitHub at the IETF. Alia Atlas 1006 contributed significant text to an earlier version of this document. 1007 Tommy Pauly, Rich Salz, and Christopher Wood all provided significant 1008 input. 1010 Authors' Addresses 1012 Martin Thomson 1013 Mozilla 1015 Email: mt@lowentropy.net 1017 Barbara Stark 1018 AT&T 1020 Email: barbara.stark@att.com