idnits 2.17.1 draft-thomson-git-using-github-00.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. 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 (February 15, 2019) is 1895 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) -- Looks like a reference, but probably isn't: '1' on line 709 -- Looks like a reference, but probably isn't: '2' on line 712 -- Looks like a reference, but probably isn't: '3' on line 714 -- Looks like a reference, but probably isn't: '4' on line 716 -- Looks like a reference, but probably isn't: '5' on line 718 -- Looks like a reference, but probably isn't: '6' on line 721 -- Looks like a reference, but probably isn't: '7' on line 757 -- Looks like a reference, but probably isn't: '8' on line 772 -- Looks like a reference, but probably isn't: '9' on line 775 -- Looks like a reference, but probably isn't: '10' on line 786 -- Looks like a reference, but probably isn't: '11' on line 789 -- Looks like a reference, but probably isn't: '12' on line 791 -- Looks like a reference, but probably isn't: '13' on line 791 -- Looks like a reference, but probably isn't: '14' on line 801 -- Looks like a reference, but probably isn't: '15' on line 801 -- Looks like a reference, but probably isn't: '16' on line 848 -- Looks like a reference, but probably isn't: '17' on line 861 ** Obsolete normative reference: RFC 3979 (Obsoleted by RFC 8179) ** Obsolete normative reference: RFC 4879 (Obsoleted by RFC 8179) == Outdated reference: A later version (-07) exists of draft-ietf-git-github-wg-configuration-00 Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 18 comments (--). 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 February 15, 2019 5 Expires: August 19, 2019 7 Using GitHub at the IETF 8 draft-thomson-git-using-github-00 10 Abstract 12 This document describes best practices for working groups that use 13 GitHub for their work. 15 Note to Readers 17 Discussion of this document takes place on the GitHub@ietf mailing 18 list (ietf-and-github@ietf.org), which is archived at 19 https://mailarchive.ietf.org/arch/search?email_list=ietf-and-github 20 [1]. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on August 19, 2019. 39 Copyright Notice 41 Copyright (c) 2019 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Distributed Version Control Systems . . . . . . . . . . . 3 58 1.2. GitHub . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.3. Other Services . . . . . . . . . . . . . . . . . . . . . 4 60 1.4. Document Goals . . . . . . . . . . . . . . . . . . . . . 4 61 1.5. Notational Conventions . . . . . . . . . . . . . . . . . 5 62 2. Administrative Policies . . . . . . . . . . . . . . . . . . . 5 63 2.1. Organizations . . . . . . . . . . . . . . . . . . . . . . 5 64 2.2. Backup and Archive Requirements . . . . . . . . . . . . . 6 65 2.3. Communicating Policies . . . . . . . . . . . . . . . . . 6 66 2.3.1. Contribution Policies on Repositories . . . . . . . . 6 67 3. Deciding to Use GitHub . . . . . . . . . . . . . . . . . . . 7 68 3.1. What to Use GitHub For . . . . . . . . . . . . . . . . . 7 69 3.2. Working Group Policies . . . . . . . . . . . . . . . . . 7 70 3.3. Repositories . . . . . . . . . . . . . . . . . . . . . . 8 71 3.4. Editors and Contributors . . . . . . . . . . . . . . . . 8 72 3.5. Document Formats . . . . . . . . . . . . . . . . . . . . 9 73 4. Contribution Methods . . . . . . . . . . . . . . . . . . . . 9 74 4.1. Issues . . . . . . . . . . . . . . . . . . . . . . . . . 9 75 4.1.1. Issue Labelling . . . . . . . . . . . . . . . . . . . 10 76 4.1.2. Closing Issues . . . . . . . . . . . . . . . . . . . 10 77 4.2. Pull Requests . . . . . . . . . . . . . . . . . . . . . . 10 78 4.2.1. Discussion on Pull Requests . . . . . . . . . . . . . 11 79 4.2.2. Merging Pull Requests . . . . . . . . . . . . . . . . 11 80 4.3. Monitoring Activity . . . . . . . . . . . . . . . . . . . 11 81 5. Internet-Draft Publication . . . . . . . . . . . . . . . . . 12 82 6. Assessing Consensus . . . . . . . . . . . . . . . . . . . . . 12 83 7. Continuous Integration . . . . . . . . . . . . . . . . . . . 13 84 8. Advice to Editors . . . . . . . . . . . . . . . . . . . . . . 13 85 9. GitHub Limitations . . . . . . . . . . . . . . . . . . . . . 14 86 10. Security Considerations . . . . . . . . . . . . . . . . . . . 14 87 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 88 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 89 12.1. Normative References . . . . . . . . . . . . . . . . . . 15 90 12.2. Informative References . . . . . . . . . . . . . . . . . 15 91 12.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 16 92 Appendix A. Experiences from Working Groups . . . . . . . . . . 16 93 A.1. CORE . . . . . . . . . . . . . . . . . . . . . . . . . . 16 94 A.2. QUIC . . . . . . . . . . . . . . . . . . . . . . . . . . 17 95 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 19 96 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 98 1. Introduction 100 The IETF has an open and transparent process for developing 101 standards. The use of GitHub or similar tools, when used as part of 102 this process, can have several objectives. GitHub provides tools 103 that can be helpful in editing documents. Use of this service has 104 proven to reduce the time that working groups need to produce 105 documents and to improve the quality of the final result. 107 The use of source control improves traceability and visibility of 108 changes. Issue tracking can be used to manage open issues and 109 provide a record of their resolution. Pull requests allow for better 110 engagement on technical and edditorial changes, and encourage 111 contributions from a larger set of contributors. Using GitHub can 112 also broaden the community of contributors for a specification. 114 This document describes how the IETF uses GitHub through the 115 development of Internet-Drafts. This concentrates on the work that 116 occurs within IETF working groups. Recommendations for working 117 groups and their chairs are made for integrating these tools with 118 their processes. 120 This document is meant as an enhancement to RFC 2418 [RFC2418]. It 121 provides guidance to working group chairs and participants on how 122 they can best use GitHub. The small number of rules in this document 123 are there to ensure common usage patterns between working groups and 124 to avoid issues that have been encountered in the past. 126 A companion document, [GH-CONFIG], describes administrative processes 127 that supports the practices described in this document. 129 1.1. Distributed Version Control Systems 131 Different version control systems are a critical component of 132 software engineering and are quite useful also for document editing. 134 Git is a distributed version control system . Each instance of a 135 repository contains a number of revisions. Each revision stores the 136 complete state of a set of files. Users are able to create new 137 revisions in their copy of a repository and share revisions between 138 copies of repositories. 140 1.2. GitHub 142 GitHub is a service operated at https://github.com/ [2]. GitHub 143 provides a centralized store for git repositories. GitHub is freely 144 accessible on the open Internet (see Section 9), albeit currently 145 only via IPv4. 147 GitHub provides a simplified and integrated interface to not only 148 git, but also provides basic user management, an issue tracker, 149 associated wiki, project hosting, and other features. 151 There are a large number of projects at GitHub and a very large 152 community of contributors. One way in which some IETF Working Groups 153 have seen benefit is in the increased reviews and associated issues 154 and improvements that come from broader participation by facilitating 155 those in this community to participate. 157 1.3. Other Services 159 Git is not the only version control system available, nor is GitHub 160 the only possible choice for hosting. There are other services that 161 host revision control repositories and provide similar additional 162 features to GitHub. For instance, BitBucket [3], or GitLab [4] 163 provide a similar feature set. In additional to a hosted service, 164 software for custom installations exists. 166 This document concentrates primarily on GitHub as it has a large and 167 active community of contributors. As a result, some content might 168 not be applicable to other similar services. A working group that 169 decides to adopt an alternative tool or service can still benefit 170 from the general guidance in this document. 172 1.4. Document Goals 174 This document aims to describe how a working group might best apply 175 GitHub to their work. The intent is to allow each working group 176 considerable flexibility in how they use GitHub. 178 This document does require that policies for use of GitHub are agreed 179 and clearly communicated within the working group (see Section 2). 180 The remainder of the document contains guidelines and advice on how 181 to construct a workable policy. 183 The requirements here apply to the case where working groups decide 184 to use GitHub as a primary means of interaction. Individuals can set 185 their own policies when using GitHub for managing their own drafts, 186 or for managing drafts that they edit on behalf of a working group 187 that has not explicitly adopted GitHub. 189 For both sets of users, this document aims to provide some amount of 190 advice on practices that have proven to be effective. 192 1.5. Notational Conventions 194 The words "MUST", "MUST NOT", "SHOULD", and "MAY" are used in this 195 document. It's not shouting; when they are capitalized, they have 196 the special meaning defined in [RFC2119]. 198 2. Administrative Policies 200 The following administrative rules provide the necessary oversight 201 and transparency. 203 2.1. Organizations 205 Organizations are a way of forming groups of contributors on GitHub. 206 Each Working Group SHOULD create a new organization for the working 207 group. 209 A working group organization SHOULD be named consistently so that it 210 can be found. For instance, the name could be ietf- or ietf- 211 -wg. 213 A single organization SHOULD NOT be used for all IETF activity, or 214 all activity within an area. Large organizations create too much 215 overhead for general management tasks, particularly when there is a 216 need to maintain membership. 218 Each organization requires owners. The owner team for a working 219 group repository MUST include responsible Area Directors. Area 220 Directors MAY also designate a delegate that becomes an owner and 221 working group chairs MAY also be owners. 223 A team with administrator access SHOULD be created for the Working 224 Group Chairs and any Working Group Secretary. Administrator access 225 is preferable, since this does not also include the ability to push 226 to all repositories and ownership does not grant any other 227 significant privileges. 229 When Area Directors or Working Group Chairs change, teams MUST be 230 updated to reflect the new membership status. 232 When a Working Group is closed, the responsible Area Director is 233 responsible for removing existing members from teams in the 234 organization. Repositories MUST be updated along to indicate that 235 they are no longer under development. 237 2.2. Backup and Archive Requirements 239 When an IETF Working Group is closed or when associated mailing lists 240 are closed, mail archives and datatracker information from that work 241 is backed up and accessible. The same applies to GitHub 242 repositories. 244 Any repositories including issues and discussion SHOULD be backed up 245 on IETF resources. It is desirable for those to be accessible via 246 the Working Group's datatracker page. For example, this might be via 247 URLs listed in the More Info section on the Working Group Charter 248 page. 250 The IETF MAY decide to backup information associated with a Working 251 Group's organization periodically. This decision can be made 252 differently per Working Group in consultation with the responsible 253 Area Director. 255 2.3. Communicating Policies 257 Each Working Group MAY set its own policy as to whether and how it 258 uses GitHub or GitLab. It is important that occasional participants 259 in the WG and others accustomed to IETF tools be able to determine 260 this and easily find the policy and GitHub or GitLab organization. 262 A simple example of how to do this is to include a link to the GitHub 263 organization on the WG Charter page in the datatracker under More 264 Info. Similarly, if there are multiple mailing list options, links 265 to those mailing lists should be given. An example of this is at 266 https://datatracker.ietf.org/wg/quic/charter/. 268 2.3.1. Contribution Policies on Repositories 270 One important policy is the IETF IPR policy (see [RFC5378], 271 [RFC3979], and [RFC4879]). Part of this policy requires making 272 contributors aware of the policy. 274 The IETF Trust license file for open source repositories [5] MUST be 275 included prominently in any document repository. 277 Including this information in the CONTRIBUTING file is sufficient. 279 In addition to the boilerplate text there can be a benefit to 280 including pointers to other working group materials, the IETF 281 datatracker, specific drafts, or websites. Adding such text is at 282 the discretion of the Working Group Chairs. 284 3. Deciding to Use GitHub 286 A Working Group Chairs are responsible for determining how to best 287 accomplish the Charter in an open and transparent fashion. The 288 Working Group Chairs are responsible for determining if there is 289 interest in using GitHub and making a consensus call to determine if 290 a the proposed policy and use is acceptable. 292 Chairs SHOULD involve Area Directors in this decision if they intend 293 to use GitHub for anything more than managing of drafts. 295 While a document editor can still use GitHub independently for 296 documents that they edit, even if the working group does not 297 expressly choose to use GitHub, any such public repository MUST 298 follow the guidelines in Section 2.3.1. This recognizes that editors 299 have traditionally chosen their own methods for managing the 300 documents they edit but preserves the need for transparent 301 contributions with awareness of IPR considerations. 303 3.1. What to Use GitHub For 305 Working Group Chairs have to decide what GitHub features the working 306 group will rely upon. Section 4 contains a more thorough discussion 307 on the different features that can be used. 309 Once a document is published in a repository on GitHub, many features 310 like pull requests, issue tracking or the wiki can be individually 311 disabled. If specific features are not used by the working group in 312 the development of the document, disabling those features avoids 313 creating confusion in the wider community about what can be used. 315 3.2. Working Group Policies 317 Working Group Chairs that decide to use GitHub MUST inform their 318 working groups of their decision on the working group mailing list. 319 An email detailing how the working group intends to use GitHub is 320 sufficient, though it might be helpful to occasionally remind new 321 contributors of these guidelines. 323 Working Group Chairs are responsible for ensuring that any policy 324 they adopt is enforced and maintained. 326 Updating the README or CONTRIBUTING file in the repository with 327 details of the process ensures that the process is recorded in a 328 stable location other than the mailing list archive. This also makes 329 any working group policies available to casual contributors who might 330 only interact with the GitHub repository. 332 GitHub prominently links to the CONTRIBUTING on certain pages. This 333 file SHOULD be used in preference to the README for information that 334 new contributors need. A link to the CONTRIBUTING file from the 335 README is advised. 337 3.3. Repositories 339 New repositories can be created within the working group organization 340 at the discretion of the chairs. Chairs could decide to only create 341 new repositories for adopted working group items, or they might 342 create repositories for individual documents on request. 344 All repositories for working group documents MUST be public. 345 Repositories for private documents MAY be kept private, but only 346 where there is a specific reason for doing so. For instance, a 347 document that details a security vulnerability might be kept private 348 prior to its initial publication as an Internet-Draft. Once an 349 Internet-Draft is published, repositories SHOULD be made public. 351 The adoption status of any document MUST be clear from the contents 352 of the repository. This can be achieved by having the name of the 353 document reflect status (that is, draft-ietf--... indicates that 354 the document was adopted), or through a prominent notice (such as in 355 the README). 357 Experience has shown that maintaining separate repositories for 358 independent documents is most manageable. This allows the work in 359 that repository to be focused on a single item. 361 Closely related documents, such as those that together address a 362 single milestone, might be placed in a single repository. This 363 allows editors to more easily manage changes and issues that affect 364 multiple documents. 366 Maintaining multiple documents in the same repository can add 367 overheads that negatively affect individual documents. For instance, 368 issues might require additional markings to identify the document 369 that they affect. Also, because editors all have write access to the 370 repository, managing the set of people with write access to a larger 371 repository is more difficult. 373 3.4. Editors and Contributors 375 Working group chairs MUST give document editors write access to 376 document repositories. This can be done by creating teams with write 377 access and allocating editors to those teams, or by making editors 378 collaborators on the repository. 380 Working group chairs MAY also grant other individuals write access 381 for other reasons, such as maintaining supporting code or build 382 configurations. Working group chairs, as administrators or owners of 383 the organization might also have write access to repositories. Users 384 other than document editors, including chairs, SHOULD NOT write to 385 working group documents unless with prior coordination with document 386 editors. 388 Working groups MAY create a team for regular contributors that is 389 only given read access to a repository. This does not confer 390 additional privileges on these contributors, it instead allows for 391 issues and pull requests to be assigned to those people. This can be 392 used to manage the assignment of editorial or review tasks to 393 individuals outside of the editor team. 395 3.5. Document Formats 397 In addition to the canonical XML format [RFC7991], document editors 398 might choose to use a different input form for editing documents, 399 such as markdown. The choice of input format is left to document 400 editors. 402 4. Contribution Methods 404 Contributions to documents come in many forms. GitHub provides a 405 range of options in addition to email. Input on GitHub can take the 406 form of new issues and pull requests, comments on issues and pull 407 requests, and comments on commits. 409 4.1. Issues 411 The GitHub issue tracker can be an effective way of managing the set 412 of open issues on a document. The record of issues - both open and 413 closed - can be a useful way of recording decisions made by a working 414 group. 416 Issues can be given arbitrary labels, assigned to contributors, and 417 assembled into milestones. The issue tracker is integrated into the 418 repository; an issue can be closed using a special marker in a commit 419 message. 421 When deciding to use GitHub, Working Group Chairs MUST decide how the 422 GitHub issue tracker are used. Use of the issue tracker could be 423 limited to recording the existence of issues, or it might be used as 424 the venue for substantial technical discussion between contributors. 426 4.1.1. Issue Labelling 428 A system of labeling issues can be effective in managing issues. For 429 instance, marking substantive issues separately from editorial can be 430 helpful at guiding discussion. Using labels can also be helpful in 431 identifying issues for which consensus has been achieved, but that 432 require editors to integrate the changes into a document. 434 Labels can be used to identify particular categories of issues or to 435 mark specific issues for discussion at an upcoming session. 437 If labels are a core part of working group process, chairs MUST 438 communicate any process to the working group. This includes the 439 semantics of labels, and who can apply and remove these labels. 441 4.1.2. Closing Issues 443 Editors have write access to repositories, which also allows them to 444 close issues. The user that opens an issue is also able to close the 445 issue. Chairs MUST provide guidance on who is permitted to close an 446 issue and under what conditions. 448 4.2. Pull Requests 450 Pull requests are the GitHub feature that allow users to request 451 changes to a repository. A user does not need to have write access 452 to a repository to create a pull request. A user can create a 453 "fork", or copy, of any public repository. The user has write access 454 to their own fork, allowing them to make local changes. A pull 455 request asks the owner of a repository to merge a specific set of 456 changes from a fork (or any branch) into their copy. 458 Editors SHOULD make pull requests for all substantial changes rather 459 than committing directly to the "master" branch of the repository. 461 Pull requests have many of the same properties as issues, including 462 the ability to host discussion and bear labels. Critically, using 463 pull requests creates a record of actions taken. 465 For significant changes, leaving a pull request open until discussion 466 of the issue within the working group concludes allows the pull 467 request to track the discussion and properly capture the outcome of 468 discussions. 470 Groups of editors could adopt a practice of having one editor create 471 a pull request and another merge it. This ensures that changes are 472 reviewed by editors. Editors are given discretion in how they manage 473 changes. 475 4.2.1. Discussion on Pull Requests 477 In addition to the features that pull requests share with issues, 478 users can also review the changes in a pull request. This is a 479 valuable feature, but it has some issues. 481 Comments in a review other than a summary are attached to specific 482 lines of the proposed change. Such comments can be hard or 483 impossible to find if changes are subsequently made to the pull 484 request. This is problematic for contributors who don't track 485 discussion closely. 487 For this reason, working group chairs SHOULD discourage the use of 488 inline comments for substantial technical discussion of issues. 490 4.2.2. Merging Pull Requests 492 Working groups MUST determine who is permitted to merge pull 493 requests. Document editors SHOULD be permitted to merge pull 494 requests at their discretion. This requires that editors exercise 495 some judgment. Working group chairs MAY occasionally identify a pull 496 request and request that editors withhold merging until working group 497 consensus has been assessed. 499 Note that the copy of a document that is maintained on GitHub does 500 not need to be a perfect reflection of working group consensus at 501 every point in time. Document editors need some flexibility in how 502 they manage a document. 504 4.3. Monitoring Activity 506 Several working groups have created read-only mailing lists that 507 subscribe to activity notifications on repositories. The volume of 508 information on these lists can be too high to monitor actively, but 509 access to an archive of actions can be useful. 511 An alternative is to rely on periodic email summaries of activity, 512 such as those produced by a notification tool like github-notify-ml 513 [6]. This tool has been used effectively in several working groups, 514 though it requires server infrastructure. 516 A working group that uses GitHub MAY provide either facility at the 517 request of the chairs. 519 5. Internet-Draft Publication 521 During the development of a document, individual revisions of a 522 document can be built and formally submitted as an Internet-Draft. 523 This creates a stable snapshot and makes the content of the in- 524 progress document available to a wider audience. 526 Editors SHOULD create a new Internet-Draft submission two weeks prior 527 to every session (see Section 7.1 of [RFC2418]). Participants in a 528 session can't be expected to monitor changes to documents in real- 529 time; an Internet-Draft ensures that there is a common, stable state 530 that is known to all participants. 532 Working group chairs MAY request the creation of an Internet-Draft at 533 any time, in consultation with document editors. 535 6. Assessing Consensus 537 The work that occurs on GitHub could be part of the consensus 538 process, but the ultimate decision on consensus regarding a document 539 is made by the chairs [RFC2026]. 541 Monitoring activity on GitHub can require a greater time commitment 542 than following a mailing list. This is because there is an increased 543 volume of activity to follow. Participants who wish to limit this 544 time commitment might follow GitHub activity selectively, either by 545 following only specific issues or by occasionally reviewing the state 546 of the document. Chairs are reminded that assessing consensus based 547 on GitHub content alone cannot be assumed to reach all interested 548 participants. 550 A working group chair SHOULD consult the working group mailing list 551 for any issue that is potentially contentious. Relying on input 552 provided through GitHub alone might result in gaining input from a 553 narrower set of participants. This includes important milestones 554 like Working Group Last-Call, where review from the widest possible 555 audience ensures a higher quality document. Managing input from 556 multiple sources in assessing consensus is similar to what is needed 557 when balancing mailing list discussion versus in-person meeting 558 discussion. 560 The use of issues and labels has proven to be effective in managing 561 contentious issues. Explicitly labeling closed issues so that those 562 with formal consensus means that there is no confusion about the 563 status of issues. 565 7. Continuous Integration 567 Various third-party services offer the ability to run tests and other 568 work when changes are made to a document. 570 One common practice is to use these continuous integration services 571 to build a text or HTML version of a document. This is then 572 published to GitHub Pages, which allows users to view a version of 573 the most recent revision of a document. Including prominent link to 574 this version of the document (such as in the README) makes it easier 575 for new contributors to find a readable copy of the most recent 576 version of a draft. 578 Continuous integration can also validate pull requests and other 579 changes for errors. The most basic check is whether the source file 580 can be transformed successful into a valid Internet-Draft. For 581 example, this might include checking that XML source is syntactically 582 correct. 584 For documents that use formal languages a part of specifications, 585 such as schema or source code, a continuous integration system might 586 also be used to validate any formal language that the document 587 contains. Tests for any source code that the document contains might 588 be run, or examples might be checked for correctness. 590 8. Advice to Editors 592 Document editors are primarily responsible for maintaining documents. 593 Taking on a few additional tasks can greatly improve the process for 594 the working group. 596 Using GitHub means that it is more likely that a contribution is made 597 by users who aren't very familiar with the work. If a duplicate 598 issue is raised, point the user to the existing issue before closing 599 the issue. If a contributor seems rude in a comment, be courteous in 600 response. 602 Pull requests from new contributors can contain errors or omissions. 603 Some contributors won't natively speak English, so changes might have 604 grammatical errors. If a change is generally sound, rather than 605 rejecting the pull request or requesting changes, accept the change 606 and then make any minor corrections yourself. 608 Never close a pull request or issue without first understanding why 609 it was made and then explaining why you aren't accepting it. If you 610 are uncertain, ask a chair for guidance. 612 If a contributor makes a comment that raises what you believe to be a 613 new issue, create an issue for them. If the issue has an obvious 614 solution, consider creating a pull request. It doesn't matter what 615 venue the issue was raised in, email, issue discussion, a pull 616 request review, capturing issues quickly ensures that problems become 617 visible and can be tracked. 619 This takes a little more effort, but these simple steps can help 620 encourage contributions, which will ultimately improve the quality of 621 your document. 623 9. GitHub Limitations 625 At the time of writing, github.com is not reachable using IPv6. This 626 is an affront to all that the IETF stands for and a slap in the face 627 to all the people who worked so hard to design and deploy the latest 628 version of the Internet Protocol. While we can collectively be 629 ashamed and disappointed that this is the situation, that doesn't 630 necessarily make the service any less useful. 632 10. Security Considerations 634 Continuity of operations is always a consideration when taking a 635 dependency on an external service. If GitHub were to fail in some 636 way, anyone relying upon its services would be seriously affected. 638 Widespread use of git reduces the exposure to a system failure 639 because the primary repository is replicated in multiple locations. 640 This includes hosted web pages; the content of web pages is 641 maintained as a branch in the main repository. Maintaining a mirror 642 of a repository that is hosted on GitHub is relatively simple and 643 might be considered as a way to provide a backup for the primary 644 repository. 646 However, other information maintained on GitHub is more vulnerable to 647 loss. This includes issues and discussion on those issues, 648 discussion and reviews of commits and pull requests, and any content 649 hosted on the wiki. Tools exist for extracting this information for 650 backup. 652 The potential for malicious actions by compromised or malcontent 653 editors, chairs and area directors is relevant in maintaining the 654 integrity of the content that GitHub hosts. Backups allow for 655 recovery of content, and regular submissions as Internet-Drafts 656 ensure that work is not lost completely. 658 11. IANA Considerations 660 This document has no IANA actions. 662 12. References 664 12.1. Normative References 666 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 667 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 668 . 670 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 671 Requirement Levels", BCP 14, RFC 2119, 672 DOI 10.17487/RFC2119, March 1997, 673 . 675 [RFC3979] Bradner, S., Ed., "Intellectual Property Rights in IETF 676 Technology", RFC 3979, DOI 10.17487/RFC3979, March 2005, 677 . 679 [RFC4879] Narten, T., "Clarification of the Third Party Disclosure 680 Procedure in RFC 3979", RFC 4879, DOI 10.17487/RFC4879, 681 April 2007, . 683 [RFC5378] Bradner, S., Ed. and J. Contreras, Ed., "Rights 684 Contributors Provide to the IETF Trust", BCP 78, RFC 5378, 685 DOI 10.17487/RFC5378, November 2008, 686 . 688 12.2. Informative References 690 [GH-CONFIG] 691 Cooper, A. and P. Hoffman, "GitHub Configuration for IETF 692 Working Groups", draft-ietf-git-github-wg-configuration-00 693 (work in progress), February 2019. 695 [ID-TEMPLATE] 696 Thomson, M., "martinthomson/i-d-template", n.d., 697 . 699 [RFC2418] Bradner, S., "IETF Working Group Guidelines and 700 Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418, 701 September 1998, . 703 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 704 RFC 7991, DOI 10.17487/RFC7991, December 2016, 705 . 707 12.3. URIs 709 [1] https://mailarchive.ietf.org/arch/search?email_list=ietf-and- 710 github 712 [2] https://github.com/ 714 [3] https://bitbucket.org/ 716 [4] https://about.gitlab.com/ 718 [5] https://trustee.ietf.org/license-for-open-source- 719 repositories.html 721 [6] https://github.com/dontcallmedom/github-notify-ml 723 [7] https://github.com/martinthomson/i-d-template 725 [8] https://trac.ietf.org/trac/core/wiki 727 [9] http://httpwg.org/ 729 [10] https://datatracker.ietf.org/wg/quic/charter/ 731 [11] https://github.com/quicwg 733 [12] https://github.com/orgs/quicwg/teams/editors 735 [13] https://github.com/orgs/quicwg/teams/contributors 737 [14] https://github.com/quicwg/wg-materials 739 [15] https://github.com/quicwg/base-drafts 741 [16] https://www.ietf.org/mailman/listinfo/quic-issues 743 [17] https://github.com/orgs/quicwg/people/quic-issues 745 Appendix A. Experiences from Working Groups 747 A.1. CORE 749 The CoRE WG (Constrained RESTful Environments) has been actively 750 using the Trac/SVN combination offered by the Tools Team for its 751 older drafts. 753 Some newer drafts (including some drafts that are not yet WG drafts 754 but could be considered candidates for that) are now being worked on 755 in the "core-wg" GitHub organization. 757 These drafts generally use Martin Thomson's template [7], except 758 where the build process (examples, grammars) is much more complicated 759 than can easily be supported by this template. 761 For most repos, a CI (continuous integration) process is set up that 762 generates a readable editor's copy (in HTML form) as well as a diff 763 from the most recent submitted version (tools TXT diff), linked from 764 the README; both have turned out to be very valuable. 765 (Unfortunately, the travis-based CI process is somewhat brittle, so 766 there is an appreciable failure rate.) 768 We try to keep discussion on the mailing list (as opposed to getting 769 them entirely in the GitHub issues), but may not have been very 770 successful in that; it definitely requires constant vigilance. 772 The WG Wiki [8] says: 774 With respect to the mode of operation of the repository, the CoRE 775 WG follows the lead of the HTTPBIS WG [9]. Specifically that 776 means that GitHub issues are welcome to record editorial issues as 777 well as technical ones; as are "pull requests" (forks of the 778 repository with fixes for an issue). However, technical 779 discussion should not happen in the forums implicitly created by 780 the issues, but on the WG mailing list. 782 We currently do not have an active backup regime. 784 A.2. QUIC 786 The QUIC WG [10] was chartered in October 2016, and has been using 787 GitHub very intensively. 789 We created a GitHub organization called "quicwg" [11], which the WG 790 chairs administer. Under than organization, we set up two teams, one 791 for WG document editors [12] and one for regular contributors [13]. 792 Membership in the former team is contingent on being chosen as an 793 editor for a WG deliverable. The latter team is more open, and 794 consists of people that the chairs and editors want to assign reviews 795 or issues to. Obviously, anyone can raise issues, comment on them, 796 submit pull requests, etc. The benefit of the "contributors" team 797 really lies in allowing the assignment of tasks to individuals, which 798 is otherwise not possible. 800 Underneath the "quicwg" organization, we created two repositories, 801 one for WG materials [14] and one for our base WG drafts [15]. Only 802 the chairs have commit permissions to the WG materials repo, which is 803 mostly used to hold presentations and other materials from our 804 various meetings. This repo is configured to not allow issues to be 805 raised or have a wiki (we instead store Markdown files inside the 806 repo.) 808 Our second repo, for "base drafts", is where most of the work occurs. 809 The decision to use a common repo for several drafts was deliberate. 810 QUIC is a complex protocol with a complex specification, text moves 811 between different documents and issues can affect several. 812 Maintaining each draft in a separate repo, while "cleaner" on first 813 impression, actually complicates this workflow. When the WG adopts 814 additional drafts, we will decide on a case-by-case basis whether 815 they will be made part of the "base drafts" or if we create a new 816 repo underneath the organization. Since Martin Thomson is an editor, 817 we use his setup template [ID-TEMPLATE] to rapidly publish HTML 818 editor copies of the specs. 820 The "base drafts" repo is configured to allow issues to be raised, 821 and its wiki is enabled (but rarely used.) Editors (and chairs) have 822 commit rights to this repo. 824 We use sets of labels to tag issues that are raised. One set simply 825 indicates which draft(s) an issue applies to, or whether it is 826 potentially of broad "design" impact, or "editorial" in nature so 827 that an editor can use his or her own discretion to resolve it 828 without WG consensus. A second set is used to track the WG consensus 829 on each issue (with states that currently include "needs-discussion", 830 "confirm-consensus", "notify-consensus" and "editor-ready"). Issues 831 progress from "needs-discussion" to either "confirm-consensus" or 832 "notify-consensus". The former is entered when consensus amongst the 833 participants in the discussion has emerged, and the WG needs to 834 confirm this consensus on the list. The latter is entered when a 835 consensus call happened at a WG meeting, and the mailing list needs 836 to confirm this consensus. (It is not clear if two separate labels 837 actually make all that much sense here.) Once WG consensus has been 838 established, an issue is labeled "editor-ready". 840 Although the QUIC WG has only been chartered for a few months, we 841 have already had ~250 issues raised, many of which have attracted 842 dozens of comments. Good issue topics and actively searching for 843 prior issues before opening new ones is essential to manage the 844 workflow. 846 In order to allow WG participants to follow the activity on GitHub 847 without needing to check the GitHub web site, we have set up a 848 separate "quic-issues" [16] mailing list at the IETF. It was a 849 deliberate decision to use a list other than the regular WG mailing 850 list. First, because we are intensively using GitHub, a lot of 851 notifications get generated (dozens per day), which would drown out 852 other list traffic, Second, the issues list is configured as a read- 853 only list, where all incoming email is rejected, except for some 854 whitelisted senders. The intent is to keep all discussion on the 855 regular WG mailing list, or on GitHub tickets. (While GitHub will 856 correctly reflect email replies to issue notifications, they seem to 857 loose sender information, which is useless.) 859 Getting GitHub notifications to go to this list was mildly painful, 860 and involved creating a dummy "IETF QUIC WG" GitHub user account 861 [17], whose subscription email address is the quic-issues list 862 address. The dummy user was made a member of the QUIC GitHub 863 organization, and will therefore by default "track" all repo 864 activity. This will cause GitHub to create the desired stream of 865 notification emails to an IETF list. One caveat here is that GitHub 866 uses the email address associated with the user who is interacting 867 with the web site as the sender address of notification emails, which 868 requires regular whitelisting in mailman. It also means that these 869 users are allowed to otherwise email the issues list; we trust they 870 don't. This email integration is rather dissatisfyingly complex; 871 we'd be interested to learn of a better way. 873 Appendix B. Acknowledgments 875 This work wouldn't have been possible without the hard work of those 876 people who have trialled use of GitHub at the IETF. Alia Atlas 877 contributed significant text to an earlier version of this document. 879 The experiences of the CORE WG in Appendix A.1 were contributed by 880 Carsten Bormann. The experiences of the QUIC WG in Appendix A.2 were 881 contributed by Lars Eggert. 883 Author's Address 885 Martin Thomson 886 Mozilla 888 Email: mt@lowentropy.net