idnits 2.17.1 draft-ietf-git-using-github-01.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 ([2], [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 (October 11, 2019) is 1659 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 991 -- Looks like a reference, but probably isn't: '2' on line 994 -- Looks like a reference, but probably isn't: '3' on line 996 -- Looks like a reference, but probably isn't: '4' on line 998 -- Looks like a reference, but probably isn't: '5' on line 1000 -- Looks like a reference, but probably isn't: '6' on line 1002 -- Looks like a reference, but probably isn't: '7' on line 1042 -- Looks like a reference, but probably isn't: '8' on line 1057 -- Looks like a reference, but probably isn't: '9' on line 1060 -- Looks like a reference, but probably isn't: '10' on line 1071 -- Looks like a reference, but probably isn't: '11' on line 1074 -- Looks like a reference, but probably isn't: '12' on line 1076 -- Looks like a reference, but probably isn't: '13' on line 1076 -- Looks like a reference, but probably isn't: '14' on line 1086 -- Looks like a reference, but probably isn't: '15' on line 1086 -- Looks like a reference, but probably isn't: '16' on line 1132 -- Looks like a reference, but probably isn't: '17' on line 1144 -- Looks like a reference, but probably isn't: '18' on line 1168 -- Looks like a reference, but probably isn't: '19' on line 1200 == Outdated reference: A later version (-07) exists of draft-ietf-git-github-wg-configuration-02 ** Downref: Normative reference to an Informational draft: draft-ietf-git-github-wg-configuration (ref. 'GIT-CONFIG') == Outdated reference: A later version (-07) exists of draft-ietf-git-github-wg-configuration-02 -- Duplicate reference: draft-ietf-git-github-wg-configuration, mentioned in 'GH-CONFIG', was also mentioned in 'GIT-CONFIG'. Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 21 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 B. Stark 5 Expires: April 13, 2020 AT&T 6 October 11, 2019 8 Using GitHub at the IETF 9 draft-ietf-git-using-github-01 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 [1]. 23 Source for this draft and an issue tracker can be found at 24 https://github.com/ietf-gitwg/using-github [2]. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on April 13, 2020. 43 Copyright Notice 45 Copyright (c) 2019 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Distributed Version Control Systems . . . . . . . . . . . 4 62 1.2. GitHub . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 1.3. Other Services . . . . . . . . . . . . . . . . . . . . . 4 64 1.4. Document Goals . . . . . . . . . . . . . . . . . . . . . 4 65 1.5. Notational Conventions . . . . . . . . . . . . . . . . . 5 66 2. Administrative Policies . . . . . . . . . . . . . . . . . . . 5 67 2.1. Organizations . . . . . . . . . . . . . . . . . . . . . . 5 68 2.2. Communicating Policies . . . . . . . . . . . . . . . . . 6 69 3. Deciding to Use GitHub . . . . . . . . . . . . . . . . . . . 6 70 3.1. What to Use GitHub For . . . . . . . . . . . . . . . . . 6 71 3.2. Working Group Policies . . . . . . . . . . . . . . . . . 7 72 3.3. Repositories . . . . . . . . . . . . . . . . . . . . . . 7 73 3.4. Editors and Contributors . . . . . . . . . . . . . . . . 8 74 3.5. Document Formats . . . . . . . . . . . . . . . . . . . . 8 75 4. Contribution Methods . . . . . . . . . . . . . . . . . . . . 9 76 4.1. Issue Tracker . . . . . . . . . . . . . . . . . . . . . . 9 77 4.1.1. Issue Labels . . . . . . . . . . . . . . . . . . . . 9 78 4.1.2. Closing Issues . . . . . . . . . . . . . . . . . . . 10 79 4.1.3. Reopening Issues . . . . . . . . . . . . . . . . . . 10 80 4.2. Pull Requests . . . . . . . . . . . . . . . . . . . . . . 10 81 4.2.1. Discussion on Pull Requests . . . . . . . . . . . . . 11 82 4.2.2. Merging Pull Requests . . . . . . . . . . . . . . . . 11 83 4.3. Monitoring Activity . . . . . . . . . . . . . . . . . . . 11 84 5. Typical Working Group Policies . . . . . . . . . . . . . . . 12 85 5.1. Document Management Mode . . . . . . . . . . . . . . . . 12 86 5.2. Issue Tracking Mode . . . . . . . . . . . . . . . . . . . 12 87 5.3. Issue Discussion Mode . . . . . . . . . . . . . . . . . . 13 88 5.3.1. Early Design Phases . . . . . . . . . . . . . . . . . 14 89 5.3.2. Managing Mature Documents . . . . . . . . . . . . . . 14 90 5.4. Issue Labelling Schemes . . . . . . . . . . . . . . . . . 15 91 5.4.1. Design/Editorial Labelling . . . . . . . . . . . . . 15 92 5.4.2. Decision Labelling . . . . . . . . . . . . . . . . . 16 93 5.4.3. Component Labelling . . . . . . . . . . . . . . . . . 16 94 5.4.4. Other Labels . . . . . . . . . . . . . . . . . . . . 17 95 6. Internet-Draft Publication . . . . . . . . . . . . . . . . . 17 96 7. Assessing Consensus . . . . . . . . . . . . . . . . . . . . . 17 97 8. Continuous Integration . . . . . . . . . . . . . . . . . . . 18 98 9. Advice to Editors . . . . . . . . . . . . . . . . . . . . . . 19 99 10. GitHub Limitations . . . . . . . . . . . . . . . . . . . . . 19 100 11. Security Considerations . . . . . . . . . . . . . . . . . . . 20 101 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 102 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 103 13.1. Normative References . . . . . . . . . . . . . . . . . . 20 104 13.2. Informative References . . . . . . . . . . . . . . . . . 21 105 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 21 106 Appendix A. Experiences from Working Groups . . . . . . . . . . 22 107 A.1. CORE . . . . . . . . . . . . . . . . . . . . . . . . . . 22 108 A.2. QUIC . . . . . . . . . . . . . . . . . . . . . . . . . . 23 109 A.3. HOMENET . . . . . . . . . . . . . . . . . . . . . . . . . 25 110 A.4. BABEL . . . . . . . . . . . . . . . . . . . . . . . . . . 26 111 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 26 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 114 1. Introduction 116 The IETF has an open and transparent process for developing 117 standards. The use of GitHub or similar tools, when used as part of 118 this process, can have several objectives. GitHub provides tools 119 that can be helpful in editing documents. Use of this service has 120 proven to reduce the time that Working Groups need to produce 121 documents and to improve the quality of the final result. 123 The use of source control improves traceability and visibility of 124 changes. Issue tracking can be used to manage open issues and 125 provide a record of their resolution. Pull requests allow for better 126 engagement on technical and editorial changes, and encourage 127 contributions from a larger set of contributors. Using GitHub can 128 also broaden the community of contributors for a specification. 130 The main purpose of this document is providing guidelines for how 131 Working Groups might integrate the capabilities provided by GitHub 132 into their processes for developing Internet-Drafts. 134 This document is meant as a supplement to existing Working Group 135 practices. It provides guidance to Working Group chairs and 136 participants on how they can best use GitHub within the framework 137 established by RFC 2418 [RFC2418]. The small number of rules in this 138 document are there to ensure common usage patterns between Working 139 Groups and to avoid issues that have been encountered in the past. 141 A companion document, [GH-CONFIG], describes administrative processes 142 that support the practices described in this document. 144 1.1. Distributed Version Control Systems 146 Version control systems are a critical component of software 147 engineering and are quite useful also for document editing. 149 Git is a distributed version control system. 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/ [3]. GitHub 158 provides centralized storage for git repositories. GitHub is freely 159 accessible on the open Internet (see Section 10), albeit currently 160 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 [4], or GitLab [5] 178 provide a similar feature set. In addition to a hosted service, 179 software for custom installations exists. 181 This document concentrates primarily on GitHub as it has a large and 182 active community of contributors. As a result, some content might 183 not be applicable to other similar services. A Working Group that 184 decides to adopt an alternative tool or service can still benefit 185 from the general guidance in this document. 187 1.4. Document Goals 189 This document aims to describe how a Working Group might best apply 190 GitHub to their work. The intent is to allow each Working Group 191 considerable flexibility in how they use GitHub. 193 This document does require that policies for use of GitHub are agreed 194 and clearly communicated within the Working Group (see Section 2). 195 The remainder of the document contains guidelines and advice on how 196 to construct a workable policy. 198 The requirements here apply to the case where Working Groups decide 199 to use GitHub as a primary means of interaction. Individuals can set 200 their own policies when using GitHub for managing their own drafts, 201 or for managing drafts that they edit on behalf of a Working Group 202 that has not explicitly adopted GitHub. 204 For both sets of users, this document aims to provide some amount of 205 advice on practices that have proven to be effective. 207 1.5. Notational Conventions 209 The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are 210 used in this document. It's not shouting; when they are capitalized, 211 they have the special meaning defined in BCP 14 [RFC2119] [RFC8174]. 213 2. Administrative Policies 215 The following administrative rules provide the necessary oversight 216 and transparency. 218 2.1. Organizations 220 Organizations are a way of forming groups of contributors on GitHub. 221 Each Working Group SHOULD create a new organization for the Working 222 Group. A Working Group organization SHOULD be named consistently so 223 that it can be found. For instance, the name could be ietf- 224 or ietf--wg. 226 A single organization SHOULD NOT be used for all IETF activity, or 227 all activity within an area. Large organizations create too much 228 overhead for general management tasks, particularly when there is a 229 need to maintain membership. 231 Each organization requires owners. The owner team for a Working 232 Group repository MUST include responsible Area Directors. Area 233 Directors MAY also designate a delegate that becomes an owner and 234 Working Group chairs MAY also be owners. 236 A team with administrator access SHOULD be created for the Working 237 Group Chairs and any Working Group Secretary. Administrator access 238 is preferable, since this does not also include the ability to push 239 to all repositories and ownership does not grant any other 240 significant privileges. 242 Details about creating organizations adhering to these guidelines can 243 be found in [GIT-CONFIG]. 245 2.2. Communicating Policies 247 Each Working Group MAY set its own policy as to whether and how it 248 uses GitHub. It is important that occasional participants in the WG 249 and others accustomed to IETF tools be able to determine this and 250 easily find the policy and GitHub organization. 252 A simple example of how to do this is to include a link to the GitHub 253 organization on the WG Charter page in the datatracker under More 254 Info. Similarly, if there are multiple mailing list options, links 255 to those mailing lists should be given. An example of this is at 256 https://datatracker.ietf.org/wg/quic/charter/. 258 3. Deciding to Use GitHub 260 Working Group Chairs are responsible for determining how to best 261 accomplish the Charter in an open and transparent fashion. The 262 Working Group Chairs are responsible for determining if there is 263 interest in using GitHub and making a consensus call to determine if 264 the proposed policy and use is acceptable. 266 Chairs MUST involve Area Directors in any decision to use GitHub for 267 anything more than managing drafts. 269 While a document editor can still use GitHub independently for 270 documents that they edit, even if the Working Group does not 271 expressly choose to use GitHub, any such public repository MUST 272 follow the guidelines in BCPs 78 and 79 ([COPYRIGHT], [IPR]). This 273 recognizes that editors have traditionally chosen their own methods 274 for managing the documents they edit but preserves the need for 275 transparent contributions with awareness of IPR considerations. 277 3.1. What to Use GitHub For 279 Working Group Chairs have to decide what GitHub features the Working 280 Group will rely upon. Section 4 contains a more thorough discussion 281 on the different features that can be used. 283 Once a document is published in a repository on GitHub, many features 284 like pull requests, issue tracking or the wiki can be individually 285 disabled. If specific features are not used by the Working Group in 286 the development of the document, disabling those features avoids 287 creating confusion in the wider community about what can be used. 289 3.2. Working Group Policies 291 Working Group Chairs that decide to use GitHub MUST inform their 292 Working Groups of their decision on the Working Group mailing list. 293 An email detailing how the Working Group intends to use GitHub is 294 sufficient, though it might be helpful to occasionally remind new 295 contributors of these guidelines. 297 Working Group Chairs are responsible for ensuring that any policy 298 they adopt is enforced and maintained. 300 Repositories MUST include a copy or reference to the policy that 301 applies to managing any documents they contain. Updating the README 302 or CONTRIBUTING file in the repository with details of the process 303 ensures that the process is recorded in a stable location other than 304 the mailing list archive. This also makes Working Group policies 305 available to casual contributors who might only interact with the 306 GitHub repository. 308 GitHub prominently links to the CONTRIBUTING file on certain pages. 309 This file SHOULD be used in preference to the README for information 310 that new contributors need. A link to the CONTRIBUTING file from the 311 README is advised. 313 3.3. Repositories 315 New repositories can be created within the Working Group organization 316 at the discretion of the chairs. Chairs could decide to only create 317 new repositories for adopted Working Group items, or they might 318 create repositories for individual documents on request. 320 All repositories for Working Group documents within the Working Group 321 organization MUST be public. Repositories for private documents MAY 322 be kept private, but only where there is a specific reason for doing 323 so. For instance, a document that details a security vulnerability 324 might be kept private prior to its initial publication as an 325 Internet-Draft. Once an Internet-Draft is published, repositories 326 SHOULD be made public. 328 The adoption status of any document MUST be clear from the contents 329 of the repository. This can be achieved by having the name of the 330 document reflect status (that is, draft-ietf--... indicates that 331 the document was adopted), or through a prominent notice (such as in 332 the README). 334 Experience has shown that maintaining separate repositories for 335 independent documents is most manageable. This allows the work in 336 that repository to be focused on a single item. 338 Closely related documents, such as those that together address a 339 single milestone, might be placed in a single repository. This 340 allows editors to more easily manage changes and issues that affect 341 multiple documents. 343 Maintaining multiple documents in the same repository can add 344 overhead that negatively affects individual documents. For instance, 345 issues might require additional markings to identify the document 346 that they affect. Also, because editors all have write access to the 347 repository, managing the set of people with write access to a larger 348 repository is more difficult (Section 3.4). 350 3.4. Editors and Contributors 352 Working group chairs MUST give document editors write access to 353 document repositories. This can be done by creating teams with write 354 access and allocating editors to those teams, or by making editors 355 collaborators on the repository. 357 Working group chairs MAY also grant other individuals write access 358 for other reasons, such as maintaining supporting code or build 359 configurations. Working group chairs, as administrators or owners of 360 the organization might also have write access to repositories. Users 361 other than document editors, including chairs, SHOULD NOT write to 362 Working Group documents unless with prior coordination with document 363 editors. 365 Working groups MAY create a team for regular contributors that is 366 only given read access to a repository. This does not confer 367 additional privileges on these contributors, it instead allows for 368 issues and pull requests to be assigned to those people. This can be 369 used to manage the assignment of editorial or review tasks to 370 individuals outside of the editor team. 372 3.5. Document Formats 374 In addition to the canonical XML format [RFC7991], document editors 375 might choose to use a different input form for editing documents, 376 such as markdown. Markdown-based formats have proven to be more 377 accessible for new contributors, though ultimately decisions about 378 format is left to document editors. 380 Formats that are not text-based SHOULD NOT be used, as these are ill- 381 disposed to the sorts of interaction that revision control enables. 383 4. Contribution Methods 385 Contributions to documents come in many forms. GitHub provides a 386 range of options in addition to email. Input on GitHub can take the 387 form of new issues and pull requests, comments on issues and pull 388 requests, and comments on commits. 390 4.1. Issue Tracker 392 The GitHub issue tracker can be an effective way of managing the set 393 of open issues on a document. Issues - both open and closed - can be 394 a useful way of recording decisions made by a Working Group. 396 Issues can be given arbitrary labels, assigned to contributors, and 397 assembled into milestones. The issue tracker is integrated into the 398 repository; an issue can be closed using a special marker in a commit 399 message. 401 When deciding to use GitHub, Working Group Chairs MUST decide how the 402 GitHub issue tracker is used. Use of the issue tracker could be 403 limited to recording the existence of issues, or it might be used as 404 the venue for substantial technical discussion between contributors. 406 A Working Group policy MAY require that all substantive changes be 407 tracked using issues. Suggested policies for the use of the GitHub 408 issue tracker are the primary subject of Section 5. 410 4.1.1. Issue Labels 412 A system of labeling issues can be effective in managing issues. For 413 instance, marking substantive issues separately from editorial can be 414 helpful at guiding discussion. Using labels can also be helpful in 415 identifying issues for which consensus has been achieved, but that 416 require editors to integrate the changes into a document. 418 Labels can be used to identify particular categories of issues or to 419 mark specific issues for discussion at an upcoming session. 421 If labels are a core part of Working Group process, chairs MUST 422 communicate any process to the Working Group. This includes the 423 semantics of labels, and who can apply and remove these labels. 424 Section 5.4 describes some basic strategies that might be adopted to 425 manage decision-making processes. 427 4.1.2. Closing Issues 429 Editors have write access to repositories, which also allows them to 430 close issues. The user that opens an issue is also able to close the 431 issue. Chairs MUST provide guidance on who is permitted to close an 432 issue and under what conditions. 434 Restrictions on closing issues are generally not advisable until a 435 document has reached a certain degree of maturity. 437 4.1.3. Reopening Issues 439 Issues that have reached a resolution that has Working Group 440 consensus MUST NOT be reopened unless new information is presented. 442 For long-running work items, new contributors often raise issues that 443 have already been resolved. Chairs need to assess whether the 444 arguments offered represent new information or not. This can require 445 some discussion to determine accurately. Resolved issues MUST remain 446 closed unless there is consensus to reopen an issue. 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. 460 Pull requests that address substantive issues SHOULD mention the 461 issue they address in the opening comment. 463 Note: This document assumes that there is a unified effort on a 464 document, all concentrated on a git "master" branch. More 465 advanced usage of git is not in the scope of this document. 467 Pull requests have many of the same properties as issues, including 468 the ability to host discussion and bear labels. Critically, using 469 pull requests creates a record of actions taken. 471 For significant changes, leaving a pull request open until discussion 472 of the issue within the Working Group concludes allows the pull 473 request to track the discussion and properly capture the outcome of 474 discussions. 476 Groups of editors could adopt a practice of having one editor create 477 a pull request and another merge it. This ensures that changes are 478 reviewed by editors. Editors are given discretion in how they manage 479 changes. 481 4.2.1. Discussion on Pull Requests 483 In addition to the features that pull requests share with issues, 484 users can also review the changes in a pull request. This is a 485 valuable feature, but it has some issues. 487 Comments in a review other than a summary are attached to specific 488 lines of the proposed change. Such comments can be hard or 489 impossible to find if changes are subsequently made to the pull 490 request. This is problematic for contributors who don't track 491 discussion closely. 493 For this reason, Working Group chairs SHOULD discourage the use of 494 inline comments for substantial technical discussion of issues. 496 4.2.2. Merging Pull Requests 498 Working groups MUST determine who is permitted to merge pull 499 requests. Document editors SHOULD be permitted to merge pull 500 requests at their discretion. This requires that editors exercise 501 some judgment. Working group chairs MAY occasionally identify a pull 502 request and request that editors withhold merging until Working Group 503 consensus has been assessed. 505 Note that the copy of a document that is maintained on GitHub does 506 not need to be a perfect reflection of Working Group consensus at 507 every point in time. Document editors need some flexibility in how 508 they manage a document. 510 4.3. Monitoring Activity 512 GitHub produces individualized email notifications of activity that 513 each user can adjust to their preferences. In addition to these, 514 some Working Groups have created read-only mailing lists that receive 515 notifications about activity on Working Group repositories. The 516 volume of information on these lists can be too high to monitor 517 actively, but access to an archive of actions can be useful. 519 An alternative is to rely on periodic email summaries of activity, 520 such as those produced by a notification tool like github-notify-ml 521 [6]. This tool has been used effectively in several Working Groups, 522 though it requires server infrastructure. 524 A Working Group that uses GitHub MAY provide either facility at the 525 request of the chairs. 527 5. Typical Working Group Policies 529 Current experience with use of GitHub suggests a few different 530 approaches to greater use of the tool in Working Groups. 532 This section describes some basic modes for interacting with GitHub, 533 each progressively more involved. This starts with a very 534 lightweight interaction where document management is the only feature 535 that is formally used, then progressively more intensive use of the 536 GitHub issue tracking capabilities are described. These approaches 537 differ primarily in how discussion of substantive matters is managed. 538 Most of the advice in this document applies equally to all models. 540 Working Groups can adjust these policies to suit their needs, but are 541 advised to avoid gratuitous changes for the sake of consistency 542 across the IETF as a whole. 544 5.1. Document Management Mode 546 In this mode of interaction, GitHub repositories are used to manage 547 changes to documents, but the bulk of the work is conducted using 548 email, face-to-face meetings, and other more traditional 549 interactions. The intent of this policy is to enable document and 550 issue management using GitHub while minimizing the complexity of the 551 process. 553 In the version of this mode with the least interaction with GitHub, 554 only the document repository is created and that is used by editors. 555 Editors might manage issues for their own benefit, or they might 556 choose to just use the respository to manage document revisions. 558 5.2. Issue Tracking Mode 560 In addition to managing documents, the Working Group might choose to 561 use GitHub for tracking outstanding issues. In this mode of 562 interaction, all substantive technical discussions are tracked as 563 issues in the issue tracker. However, discussion of any substantial 564 matters is always conducted on mailing lists. 566 Under this mode, issues and pull requests can be opened by anyone, 567 but anything deemed substantive MUST be resolved exclusively on the 568 mailing list. Discussion on GitHub is kept to a minimum. Only 569 editorial matters can be resolved using the issue tracker. 571 Chairs and editors are given discretion in determining what issues 572 are substantive. As documents mature, it is generally prudent to err 573 more toward consulting the mailing list where there is doubt. As 574 with other Working Group decisions, chairs are the arbiters in case 575 of dispute. 577 A recurrent problem with this mode of interaction is the tendency for 578 discussions to spontaneously develop in the issue tracker. This 579 requires a degree of discipline from chairs and editors to ensure 580 that any substantive matters are taken to the mailing list. 582 As mailing lists remain the primary venue for discussion of 583 substantive matters, this mode and the document management only modes 584 remain those most compatible with existing work practices for Working 585 Groups. Participants in a Working Group that operates under either 586 model can reasonably be expected to receive all relevant 587 communication about the work of the group from the mailing list. 589 Though the mailing list is used for making decisions, the issue 590 tracker can still be a useful record of the state of issues. It is 591 often useful if chairs or editors record details of decisions in 592 issue comments when closing issues as resolved. 594 5.3. Issue Discussion Mode 596 This GitHub interaction mode differs from the other modes in that 597 discussion relating to substantive technical matters is allowed to 598 occur on GitHub issues. Though decisions are always subject to 599 confirmation on the mailing list, participants are permitted to 600 conduct substantive discussions on the issue tracker. In some cases, 601 this can include making some decisions without involving the Working 602 Group mailing list. 604 A Working Group mailing list remains a critical venue for decision 605 making, even where issue discussion occurs elsewhere. Working Group 606 mailing lists generally include a wider audience than those who 607 follow issue discussion, so difficult issues always benefit from list 608 discussion. 610 Decisions about Working Group consensus MUST always be confirmed 611 using the Working Group mailing list. However, depending on the 612 maturity of documents, this might be a more lightweight interaction, 613 such as sending an email confirmation for a set of resolutions made 614 using GitHub. 616 Using the mailing list to resolve difficult or controversial issues 617 is strongly encouraged. In those cases, the issue tracker might be 618 used to more fully develop an understanding of problems before 619 initiating a discussion on the mailing list, along lines similar to 620 the design team process (see Section 6.5 of [RFC2418]). 622 As a more involved process, adopting this mode can require changes in 623 policies as documents become more mature. It is possible to use 624 different processes for different documents in the Working Group. 626 Working Group chairs SHOULD confirm that the Working Group has 627 consensus to adopt any process. In particular, the introduction of a 628 more tightly-controlled process can have the effect of privileging 629 positions already captured in documents, which might disadvantage 630 alternative viewpoints. 632 5.3.1. Early Design Phases 634 During early phases of the design of a protocol, chairs MAY allow 635 editors to manage all aspects of issues. Editors are permitted to 636 make decisions about how to both identify and resolve technical 637 issues, including making any changes that editors feel necessary. 639 Chairs need to explicitly decide that this sort of process is needed 640 and announce the decision to the Working Group. In many cases, 641 documents that are adopted by a Working Group are already 642 sufficiently mature that a looser process is not beneficial. The 643 primary reason to grant editors more discretionary power is to 644 improve the speed with which changes can be made. The risk is that 645 design changes might not always reflect the consensus of the Working 646 Group. 648 Changes made by editors under this process do not completely lack 649 oversight. GitHub and git provide tools for ensuring that changes 650 are tracked and can be audited. Within the usual Working Group 651 process it is expected that Internet-Drafts will receive regular 652 review. Finally, process checkpoints like Working Group Last Call 653 (WGLC; Section 7.4 of [RFC2418]) provides additional safeguards 654 against abuse. 656 Working Groups are advised against allowing editors this degree of 657 flexibility for the entirety of a document lifecycle. Once a 658 document is more stable and mature, it is likely appropriate to move 659 to a more tightly controlled process. 661 5.3.2. Managing Mature Documents 663 As a document matures, it becomes more important to understand not 664 just that the document as a whole retains the support of the Working 665 Group, but that changes are not made without wider consultation. 667 Chairs might choose to manage the process of deciding which issues 668 are substantive. For instance, chairs might reserve the ability to 669 use the "design" label to new issues (see Section 5.4.1) and to close 670 issues marked as "design". Chairs should always allow document 671 editors to identify and address editorial issues as they see fit. 673 As documents mature further, explicit confirmation of technical 674 decisions with the Working Group mailing list becomes more important. 676 Gaining Working Group consensus about the resolution of issues can be 677 done in the abstract, with editors being permitted to capture the 678 outcome of discussions as they see fit. 680 More mature documents require not only consensus, but consensus about 681 specific text. All substantive changes to documents that have passed 682 WGLC SHOULD be proposed as pull requests, and MUST be discussed on 683 the mailing list, and MUST have chairs explicitly confirm consensus. 684 Chairs MAY institute this stricter process prior to WGLC. 686 Note: It is generally sufficient to trust editors to manage 687 adherence with these policies, aided by the transparency provided 688 by the version control system. There are tools that can be used 689 to more tightly control access to repositories, but they can be 690 overly constraining. 692 5.4. Issue Labelling Schemes 694 Several schemes for use of issue labels in managing issues have been 695 used successfully. This section outlines these strategies and how 696 they might be applied. 698 A design/editorial split (see Section 5.4.1) is useful in all cases 699 that the issue tracking capability is used. Working Groups that only 700 use GitHub for issue tracking might find that distinction sufficient 701 for their needs. 703 Working Groups or editors might use additional labels as they choose. 704 Any label that is used as part of a process requires that the process 705 be documented and announced by Working Group chairs. Editors SHOULD 706 be permitted to use labels to manage issues without any formal 707 process significance being attached to those issues. 709 5.4.1. Design/Editorial Labelling 711 The most important distinction about an issue is whether it is 712 substantive. The labels of "design" and "editorial" are used to 713 represent this distinction. 715 An issue labeled as "design" has or might have a substantive effect 716 on a document. For protocol specifications, a "design" issue is one 717 that might affect implementations or interoperability requirements. 718 Addressing a "design" issue ultimately requires Working Group 719 consensus, even if the resolution is to make no change. 721 An issue labeled as "editorial" has no substantive effect on a 722 document, except to the extent that addressing the issue might make 723 understanding the specification easier. Resolution of "editorial" 724 issues can be left to the discretion of editors. 726 This distinction can be applied to all types of document. For 727 instance, a "design" issue for an Informational document might be 728 raised to discuss possible changes to important concepts in the 729 document. 731 5.4.2. Decision Labelling 733 Labels can be used to manage processes. As documents mature and 734 issues become more numerous, labels can be used to clearly mark the 735 status of issues. In particular, labelling of issues can be used to 736 help in managing Working Group decisions. 738 For documents that are less mature, issues with resolutions but no 739 specific proposals for changes to text might be marked "editor-ready" 740 as a way of signaling that there is consensus about an approach, but 741 no specific proposal. Chairs might use this to signal that 742 discussion is complete and that editors are to be given discretion in 743 the construction of text. 745 In contrast, if specific text is a prerequisite for resolving issues, 746 as might be the case for more mature documents, a "proposal-ready" 747 label might be used by editors to mark issues that they believe to 748 have acceptable resolutions. 750 For resolved issues, a "has-consensus" label might be used by chairs 751 to mark issues for which formal Working Group decisions have been 752 made (Section 6.1 of [RFC2418]). 754 A "v2" or "next-version" label might be used to mark and thereby save 755 issues for a future version of or extension to a protocol, 756 particularly where a resolution is made to take no action. 758 5.4.3. Component Labelling 760 Repositories with multiple interrelated documents or a complex 761 document with multiple logical components might benefit from labels 762 that identify different aspects of the work. The choice of 763 appropriate labels for components will depend on the structure of 764 specific documents. 766 5.4.4. Other Labels 768 Other labels can be used depending on the needs of editors and 769 Working Group processes. For example, 771 o An "invalid" label might be used for issues that were raised in 772 error. 774 o A "blocked" label might indicate an issue is awaiting resolution 775 of an external process or related issue. 777 o A "parked" label might be used to indicate issues that do not 778 require immediate Working Group attention. 780 6. Internet-Draft Publication 782 During the development of a document, individual revisions of a 783 document can be built and formally submitted as an Internet-Draft. 784 This creates a stable snapshot and makes the content of the in- 785 progress document available to a wider audience. Documents submitted 786 as Internet-Drafts are not expected to address all open issues or 787 merge outstanding pull requests. 789 Editors SHOULD create a new Internet-Draft submission two weeks prior 790 to every session (see Section 7.1 of [RFC2418]). Though discussion 791 could use the current version of a document from version control, 792 participants in a session can't be expected to monitor changes to 793 documents in real-time; a published Internet-Draft ensures that there 794 is a common, stable state that is known to all participants. 796 Revisions used to generate documents that are submitted as Internet- 797 Drafts SHOULD be tagged in repositories to provide a record of 798 submissions. 800 Working group chairs MAY request the creation of an Internet-Draft at 801 any time, in consultation with document editors. 803 7. Assessing Consensus 805 The work that occurs on GitHub could be part of the consensus 806 process, but the ultimate decision on consensus regarding a document 807 is made by the chairs [RFC2026]. 809 Monitoring activity on GitHub can require a greater time commitment 810 than following a mailing list. This is because there is an increased 811 volume of activity to follow. Participants who wish to limit this 812 time commitment might follow GitHub activity selectively, either by 813 following only specific issues or by occasionally reviewing the state 814 of the document. Chairs are reminded that assessing consensus based 815 on GitHub content alone cannot be assumed to reach all interested 816 participants. 818 A Working Group chair MUST consult the Working Group mailing list for 819 any issue that is potentially contentious. Relying on input provided 820 through GitHub alone might result in gaining input from a narrower 821 set of participants. This includes important milestones like Working 822 Group Last-Call, where review from the widest possible audience 823 ensures a higher quality document. Managing input from multiple 824 sources in assessing consensus is similar to what is needed when 825 balancing mailing list discussion versus in-person meeting 826 discussion. 828 It is expected that technical decisions will be made based on 829 discussion and interaction on GitHub. This is especially the case 830 during early stages of development of a document. Any decisions are 831 ultimately confirmed through review, and ultimately, through Working 832 Group Last Call (see Section 7.4 of [RFC2418]). 834 The use of issues and labels has proven to be effective in managing 835 contentious issues. Explicitly labeling closed issues to explicitly 836 identify those with formal consensus means that there is no confusion 837 about the status of issues. 839 8. Continuous Integration 841 Various third-party services offer the ability to run tests and other 842 work when changes are made to a document. 844 One common practice is to use these continuous integration services 845 to build a text or HTML version of a document. This is then 846 published to GitHub Pages, which allows users to view a version of 847 the most recent revision of a document. Including a prominent link 848 to this version of the document (such as in the README) makes it 849 easier for new contributors to find a readable copy of the most 850 recent version of a draft. 852 Continuous integration can also validate pull requests and other 853 changes for errors. The most basic check is whether the source file 854 can be transformed successfully into a valid Internet-Draft. For 855 example, this might include checking that XML source is syntactically 856 correct. 858 For a document that use formal languages as part of the 859 specification, such as schema or source code, a continuous 860 integration system might also be used to validate any formal language 861 that the document contains. Tests for any source code that the 862 document contains might be run, or examples might be checked for 863 correctness. 865 9. Advice to Editors 867 Document editors are primarily responsible for maintaining documents. 868 Taking on a few additional tasks can greatly improve the process for 869 the Working Group. 871 Using GitHub means that it is more likely that a contribution is made 872 by users who aren't very familiar with the work. If a duplicate 873 issue is raised, point the user to the existing issue before closing 874 the issue. If a contributor seems rude in a comment, be courteous in 875 response. 877 Pull requests from new contributors can contain errors or omissions. 878 Some contributors won't natively speak English, so changes might have 879 grammatical errors. If a change is generally sound, rather than 880 rejecting the pull request or requesting changes, accept the change 881 and then make any minor corrections yourself. 883 Never close a pull request or issue without first understanding why 884 it was made and then explaining why you aren't accepting it. If you 885 are uncertain, ask a chair for guidance. 887 If a contributor makes a comment that raises what you believe to be a 888 new issue, create an issue for them. If the issue has an obvious 889 solution, consider creating a pull request. It doesn't matter what 890 venue the issue was raised in (e.g., email, issue discussion, a pull 891 request review); capturing issues quickly ensures that problems 892 become visible and can be tracked. 894 This takes a little more effort, but these simple steps can help 895 encourage contributions, which will ultimately improve the quality of 896 your document. 898 10. GitHub Limitations 900 At the time of writing, github.com is not reachable using IPv6. This 901 is an affront to all that the IETF stands for and a slap in the face 902 to all the people who worked so hard to design and deploy the latest 903 version of the Internet Protocol. While we can collectively be 904 ashamed and disappointed that this is the situation, that doesn't 905 necessarily make the service any less useful. 907 11. Security Considerations 909 Continuity of operations is always a consideration when taking a 910 dependency on an external service. If GitHub were to fail in some 911 way, anyone relying upon its services would be seriously affected. 913 Widespread use of git reduces the exposure to a system failure 914 because the primary repository is replicated in multiple locations. 915 This includes hosted web pages; the content of web pages is 916 maintained as a branch in the main repository. Maintaining a mirror 917 of a repository that is hosted on GitHub is relatively simple and 918 might be considered as a way to provide a backup for the primary 919 repository. 921 However, other information maintained on GitHub is more vulnerable to 922 loss. This includes issues and discussion on those issues, 923 discussion and reviews of commits and pull requests, and any content 924 hosted on the wiki. Tools exist for extracting this information for 925 backup. 927 The potential for malicious actions by compromised or malcontent 928 editors, chairs and area directors is relevant in maintaining the 929 integrity of the content that GitHub hosts. Backups allow for 930 recovery of content, and regular submissions as Internet-Drafts 931 ensure that work is not lost completely. 933 12. IANA Considerations 935 This document has no IANA actions. 937 13. References 939 13.1. Normative References 941 [COPYRIGHT] 942 Bradner, S., Ed. and J. Contreras, Ed., "Rights 943 Contributors Provide to the IETF Trust", BCP 78, RFC 5378, 944 DOI 10.17487/RFC5378, November 2008, 945 . 947 [GIT-CONFIG] 948 Cooper, A. and P. Hoffman, "GitHub Configuration for IETF 949 Working Groups", draft-ietf-git-github-wg-configuration-02 950 (work in progress), September 2019. 952 [IPR] Bradner, S. and J. Contreras, "Intellectual Property 953 Rights in IETF Technology", BCP 79, RFC 8179, 954 DOI 10.17487/RFC8179, May 2017, 955 . 957 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 958 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 959 . 961 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 962 Requirement Levels", BCP 14, RFC 2119, 963 DOI 10.17487/RFC2119, March 1997, 964 . 966 [RFC2418] Bradner, S., "IETF Working Group Guidelines and 967 Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418, 968 September 1998, . 970 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 971 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 972 May 2017, . 974 13.2. Informative References 976 [GH-CONFIG] 977 Cooper, A. and P. Hoffman, "GitHub Configuration for IETF 978 Working Groups", draft-ietf-git-github-wg-configuration-02 979 (work in progress), September 2019. 981 [ID-TEMPLATE] 982 Thomson, M., "martinthomson/i-d-template", n.d., 983 . 985 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 986 RFC 7991, DOI 10.17487/RFC7991, December 2016, 987 . 989 13.3. URIs 991 [1] https://mailarchive.ietf.org/arch/search?email_list=ietf-and- 992 github 994 [2] https://github.com/ietf-gitwg/using-github 996 [3] https://github.com/ 998 [4] https://bitbucket.org/ 1000 [5] https://about.gitlab.com/ 1002 [6] https://github.com/dontcallmedom/github-notify-ml 1004 [7] https://github.com/martinthomson/i-d-template 1006 [8] https://trac.ietf.org/trac/core/wiki 1008 [9] http://httpwg.org/ 1010 [10] https://datatracker.ietf.org/wg/quic/charter/ 1012 [11] https://github.com/quicwg 1014 [12] https://github.com/orgs/quicwg/teams/editors 1016 [13] https://github.com/orgs/quicwg/teams/contributors 1018 [14] https://github.com/quicwg/wg-materials 1020 [15] https://github.com/quicwg/base-drafts 1022 [16] https://www.ietf.org/mailman/listinfo/quic-issues 1024 [17] https://github.com/orgs/quicwg/people/quic-issues 1026 [18] https://github.com/martinthomson/i-d-template 1028 [19] https://github.com/martinthomson/i-d-template 1030 Appendix A. Experiences from Working Groups 1032 A.1. CORE 1034 The CoRE WG (Constrained RESTful Environments) has been actively 1035 using the Trac/SVN combination offered by the Tools Team for its 1036 older drafts. 1038 Some newer drafts (including some drafts that are not yet WG drafts 1039 but could be considered candidates for that) are now being worked on 1040 in the "core-wg" GitHub organization. 1042 These drafts generally use Martin Thomson's template [7], except 1043 where the build process (examples, grammars) is much more complicated 1044 than can easily be supported by this template. 1046 For most repos, a CI (continuous integration) process is set up that 1047 generates a readable editor's copy (in HTML form) as well as a diff 1048 from the most recent submitted version (tools TXT diff), linked from 1049 the README; both have turned out to be very valuable. 1050 (Unfortunately, the travis-based CI process is somewhat brittle, so 1051 there is an appreciable failure rate.) 1053 We try to keep discussion on the mailing list (as opposed to getting 1054 them entirely in the GitHub issues), but may not have been very 1055 successful in that; it definitely requires constant vigilance. 1057 The WG Wiki [8] says: 1059 With respect to the mode of operation of the repository, the CoRE 1060 WG follows the lead of the HTTPBIS WG [9]. Specifically that 1061 means that GitHub issues are welcome to record editorial issues as 1062 well as technical ones; as are "pull requests" (forks of the 1063 repository with fixes for an issue). However, technical 1064 discussion should not happen in the forums implicitly created by 1065 the issues, but on the WG mailing list. 1067 We currently do not have an active backup regime. 1069 A.2. QUIC 1071 The QUIC WG [10] was chartered in October 2016, and has been using 1072 GitHub very intensively. 1074 We created a GitHub organization called "quicwg" [11], which the WG 1075 chairs administer. Under that organization, we set up two teams, one 1076 for WG document editors [12] and one for regular contributors [13]. 1077 Membership in the former team is contingent on being chosen as an 1078 editor for a WG deliverable. The latter team is more open, and 1079 consists of people that the chairs and editors want to assign reviews 1080 or issues to. Obviously, anyone can raise issues, comment on them, 1081 submit pull requests, etc. The benefit of the "contributors" team 1082 really lies in allowing the assignment of tasks to individuals, which 1083 is otherwise not possible. 1085 Underneath the "quicwg" organization, we created two repositories, 1086 one for WG materials [14] and one for our base WG drafts [15]. Only 1087 the chairs have commit permissions to the WG materials repo, which is 1088 mostly used to hold presentations and other materials from our 1089 various meetings. This repo is configured to not allow issues to be 1090 raised or have a wiki (we instead store Markdown files inside the 1091 repo.) 1093 Our second repo, for "base drafts", is where most of the work occurs. 1094 The decision to use a common repo for several drafts was deliberate. 1095 QUIC is a complex protocol with a complex specification, text moves 1096 between different documents and issues can affect several. 1097 Maintaining each draft in a separate repo, while "cleaner" on first 1098 impression, actually complicates this workflow. When the WG adopts 1099 additional drafts, we will decide on a case-by-case basis whether 1100 they will be made part of the "base drafts" or if we create a new 1101 repo underneath the organization. Since Martin Thomson is an editor, 1102 we use his setup template [ID-TEMPLATE] to rapidly publish HTML 1103 editor copies of the specs. 1105 The "base drafts" repo is configured to allow issues to be raised, 1106 and its wiki is enabled (but rarely used.) Editors (and chairs) have 1107 commit rights to this repo. 1109 We use sets of labels to tag issues that are raised. One set simply 1110 indicates which draft(s) an issue applies to, or whether it is 1111 potentially of broad "design" impact, or "editorial" in nature so 1112 that an editor can use his or her own discretion to resolve it 1113 without WG consensus. A second set is used to track the WG consensus 1114 on each issue (with states that currently include "needs-discussion", 1115 "confirm-consensus", "notify-consensus" and "editor-ready"). Issues 1116 progress from "needs-discussion" to either "confirm-consensus" or 1117 "notify-consensus". The former is entered when consensus amongst the 1118 participants in the discussion has emerged, and the WG needs to 1119 confirm this consensus on the list. The latter is entered when a 1120 consensus call happened at a WG meeting, and the mailing list needs 1121 to confirm this consensus. (It is not clear if two separate labels 1122 actually make all that much sense here.) Once WG consensus has been 1123 established, an issue is labeled "editor-ready". 1125 Within only a few months of being chartered, QUIG WG had ~250 issues 1126 raised, many of which attracted dozens of comments. Good issue 1127 topics and actively searching for prior issues before opening new 1128 ones is essential to manage the workflow. 1130 In order to allow WG participants to follow the activity on GitHub 1131 without needing to check the GitHub web site, we have set up a 1132 separate "quic-issues" [16] mailing list at the IETF. It was a 1133 deliberate decision to use a list other than the regular WG mailing 1134 list. First, because we are intensively using GitHub, a lot of 1135 notifications get generated (dozens per day), which would drown out 1136 other list traffic, Second, the issues list is configured as a read- 1137 only list, where all incoming email is rejected, except for some 1138 whitelisted senders. The intent is to keep all discussion on the 1139 regular WG mailing list, or on GitHub tickets. (While GitHub will 1140 correctly reflect email replies to issue notifications, they seem to 1141 loose sender information, which is useless.) 1142 Getting GitHub notifications to go to this list was mildly painful, 1143 and involved creating a dummy "IETF QUIC WG" GitHub user account 1144 [17], whose subscription email address is the quic-issues list 1145 address. The dummy user was made a member of the QUIC GitHub 1146 organization, and will therefore by default "track" all repo 1147 activity. This will cause GitHub to create the desired stream of 1148 notification emails to an IETF list. One caveat here is that GitHub 1149 uses the email address associated with the user who is interacting 1150 with the web site as the sender address of notification emails, which 1151 requires regular whitelisting in mailman. It also means that these 1152 users are allowed to otherwise email the issues list; we trust they 1153 don't. This email integration is rather dissatisfyingly complex; 1154 we'd be interested to learn of a better way. 1156 A.3. HOMENET 1158 After Martin Thomson's presentation on using GitHub (presented at the 1159 WG Chairs lunch), the homenet chairs (one of the chairs to be 1160 precise) set up https://github.com/ietf-homenet-wg. WG draft authors 1161 were asked if they wanted to use it. All draft authors agreed to 1162 try, so copies of the current drafts were converted to Markdown 1163 (which seemed to be the recommended format) and separate repositories 1164 created for each draft. GitHub teams (comprised of authors) were 1165 created for the drafts, as per available instructions. 1167 The repositories were created using instructions from Martin 1168 Thomson's template [18]. But since instructions for gh-pages proved 1169 too confusing, the gh-pages were created by manually uploading (using 1170 the GitHub UI) the .html and .txt files output by "make gh-pages" to 1171 the gh-pages branch. README.md was then edited to point to the 1172 uploaded .html file. However, one of the authors decided it was 1173 easier to use Google docs to receive comments and maintain an 1174 Editor's copy of the draft (in Markdown). He is able to give 1175 permission (on request) to other WG group members to comment directly 1176 on Google docs. Therefore the copy on GitHub is out-dated and has 1177 effectively been abandoned. 1179 The main authors of the other two drafts decided not to use the 1180 repositories created for them, but wanted a new repository for one of 1181 the drafts. The authors have collaborated on GitHub in this new 1182 repository, but the WG has not been invited to look, comment, or 1183 contribute there. This is probably for the best, since the draft 1184 pointed to by the README.md is the version in the gh-pages of the old 1185 repository for the same draft. 1187 In short, the use of GitHub has been highly experimental, and no 1188 formal WG activities have taken place there. The GitHub organization 1189 has effectively been a playground area for the chairs and authors to 1190 stumble around to figure out how to use this tool. 1192 A.4. BABEL 1194 After Martin Thomson's presentation on using GitHub (presented at the 1195 WG Chairs lunch), one of the authors of a draft in the babel WG asked 1196 the chairs if they might consider setting up a GitHub organization. 1197 In the absence of a response (and the absence of follow-up to the 1198 absent response), the draft was put in a personal GitHub repository. 1199 The repository was created using instructions (as best as they could 1200 be understood) from Martin Thomson's template [19]. The gh-pages, 1201 continuous integration (CI), and such proved beyond comprehension to 1202 someone who had only rudimentary (almost non-existent) experience 1203 with makefiles, CI, and the inner workings of any of the tools 1204 involved; but who, fortunately, did have a laptop running Linux, 1205 experience with vi, and had formed a very basic understanding of git 1206 (mostly in the context of Bitbucket) over the past year. 1208 Carsten Bormann was kind enough to convert the existing XML to 1209 Markdown (since the recommendation was to use markdown). This turned 1210 out to be an excellent recommendation. Writing drafts using Markdown 1211 is likely to be significantly easier for many people. The rules are 1212 easier and it's so much simpler to figure out what's wrong. 1214 The repository was used by the two draft authors to have discussions 1215 using Issues. These were useful to track agreements between the 1216 authors and to create to-do lists. 1218 The repository has also been used to ask WG members to look at the 1219 Editor's draft (manually pushed to gh-pages) and see if comments had 1220 been handled to their liking. WG members were not asked to use 1221 Issues to make comments. Comments from WG members were all discussed 1222 on the WG list. 1224 Updates to the draft have been pushed directly to the master branch. 1225 There was one attempt to first create a separate branch and then a 1226 pull request to the master. This proved to be too much effort in the 1227 context of this draft. 1229 Appendix B. Acknowledgments 1231 This work wouldn't have been possible without the hard work of those 1232 people who have trialled use of GitHub at the IETF. Alia Atlas 1233 contributed significant text to an earlier version of this document. 1235 The experiences of the CORE WG in Appendix A.1 were contributed by 1236 Carsten Bormann. The experiences of the QUIC WG in Appendix A.2 were 1237 contributed by Lars Eggert. 1239 Authors' Addresses 1241 Martin Thomson 1242 Mozilla 1244 Email: mt@lowentropy.net 1246 Barbara Stark 1247 AT&T 1249 Email: barbara.stark@att.com