idnits 2.17.1 draft-cooper-wugh-github-wg-configuration-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 14, 2018) is 2041 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 wugh A. Cooper 3 Internet-Draft Cisco 4 Intended status: Informational P. Hoffman 5 Expires: March 18, 2019 ICANN 6 September 14, 2018 8 GitHub Configuration for IETF Working Groups 9 draft-cooper-wugh-github-wg-configuration-00 11 Abstract 13 The use of GitHub in IETF working group processes is increasing. 14 This document describes possible uses and conventions for working 15 groups which are considering starting to use GitHub. It does not 16 mandate any processes, and does not intend to change the processes 17 used by current working groups. 19 Discussion of this document takes place on the ietf-and-github 20 mailing list (ietf-and-github@ietf.org), which is archived at 21 . 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on March 18, 2019. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Administrative Process and Conventions . . . . . . . . . . . 3 60 2.1. Creation of GitHub Organizations . . . . . . . . . . . . 3 61 2.2. Personnel Changes . . . . . . . . . . . . . . . . . . . . 4 62 2.3. Working Group Closing . . . . . . . . . . . . . . . . . . 4 63 2.4. Creation of Document Repository . . . . . . . . . . . . . 4 64 3. Working Group Process . . . . . . . . . . . . . . . . . . . . 5 65 3.1. Contributions . . . . . . . . . . . . . . . . . . . . . . 5 66 3.2. Backing Up and Archiving GitHub Content . . . . . . . . . 5 67 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 68 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 69 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 70 6.1. Normative References . . . . . . . . . . . . . . . . . . 6 71 6.2. Informative References . . . . . . . . . . . . . . . . . 6 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 74 1. Introduction 76 Many IETF working groups and participants make use of GitHub in 77 different ways as part of their work on IETF documents. Some others 78 are interested in having their working groups use GitHub to 79 facilitate the development of working group documents, but they are 80 unfamiliar with how to get started or they are unclear about which 81 conventions to follow. 83 This document proposes a set of administrative processes and 84 conventions for IETF working groups to use if they chose as a working 85 group to use GitHub to facilitate their work. The proposals in this 86 document are not directed at working groups or individuals that are 87 already using GitHub to do IETF work. Practices vary among existing 88 working groups and some of them are not consistent with the 89 conventions proposed here: that is fine. The goal of the proposals 90 in this document is not to require uniformity in current practice, 91 but to help working groups to get started using GitHub in a uniform 92 way if they want to. 94 The document is meant to spur discussion in the IETF community. If 95 there proves to be rough consensus in the community in support of the 96 proposals in this document, the functional requirements would need to 97 be discussed with the IETF Tools Team, and the IETF Secretariat who 98 would need to support various pieces of what is proposed here. 100 2. Administrative Process and Conventions 102 This section specifies a proposal for an administrative process and 103 conventions to support the creation and management of GitHub 104 organizations for working groups and single-document repositories in 105 a uniform way. The steps could be done manually by the IETF 106 Secretariat or they could be automated. For example, see 107 and 108 for working examples 109 of automation that is in use in some working groups. 111 In this document the question of whether processes should be manual 112 or automated is deliberately left ambiguous since the first question 113 that should be asked is whether this is functionality the community 114 would want to have supported at all. 116 Most of the conventions below are drawn from 117 [I-D.thomson-github-bcp]. 119 2.1. Creation of GitHub Organizations 121 This document proposes that there be a facility in the IETF 122 Datatracker () interface to allow an 123 area director or working group chair to request the creation of a 124 GitHub organization for a particular working group. Ideally, this 125 facility would appear both as part of the working group chartering UI 126 as well as the working group page UI. 128 When an area director or working group chair makes a request to 129 create a GitHub organization, the following process would be 130 initiated: 132 1. Create a GitHub organization for the working group. 134 2. Name the organization as ietf--wg 136 3. Initialize the organization by designating the IETF Secretariat 137 and the area directors in the working group's area as owners. If 138 the responsible AD for the working group is from another area, 139 that AD will be an owner as well. 141 4. Initialize the organization with a team that has administrator 142 access. This team will consist of the working group chairs and 143 working group secretary, if one exists. 145 After the organization is created, the URL for the organization would 146 be added to the working group's page in the datatracker. 148 Steps 3 and 4 above imply that the GitHub identities of the 149 organization owners and administrators are known. Recording GitHub 150 identities in the datatracker (see 151 ) would 152 facilitate this. The person requesting the organization would need 153 to be notified if the GitHub identities of any of the people meant to 154 be owners or administrators were not available. 156 2.2. Personnel Changes 158 When there are personnel changes in the area or the working group, 159 those changes would be reflected in the GitHub organization. [[ Need 160 to do a bit of research on how to do this automatically. ]] 162 2.3. Working Group Closing 164 When a working group is closed, the team with administrative access 165 would be removed and the owner list would be returned to its initial 166 composition. The organization summary and the repositories within 167 the organization would be updated to indicate that they are no longer 168 under development. 170 2.4. Creation of Document Repository 172 There are many different scenarios and configurations where it might 173 be useful to have automation and/or established administrative 174 conventions for repositories within WG organizations, such as: 176 o Creating a new repository for an individual draft 178 o Creating a new repository for an adopted working group draft 180 o Migrating an existing document repository into the WG organization 182 o Creating a new repository that contains multiple drafts 184 As an incremental step, this document proposes that there be a 185 facility in the Datatracker interface to allow an administrator of an 186 ietf--wg organization to request the creation of a new 187 repository within that organization for a single document. The 188 document authors would be identified as collaborators. The 189 repository name would be the draft name. Ideally, the repository 190 would be configured with an skeleton draft file, default 191 CONTRIBUTING, LICENSE, and README files, and continuous integration 192 support, in the vein of . 195 3. Working Group Process 197 [I-D.thomson-github-bcp] contains discussion of the different 198 possible ways that a working group can use GitHub and the large 199 number of decisions associated with doing so. This section proposes 200 a basic set of administrative policies for working groups to follow 201 and the administrative support needed to carry out those policies. 203 3.1. Contributions 205 At a minimum, every repository created in a working group 206 organization needs to incorporate into its CONTRIBUTING file the 207 boilerplate text at from the IETF license file for open source 209 repositories. The CONTRIBUTING file can contain other information as 210 well (see for examples). 213 3.2. Backing Up and Archiving GitHub Content 215 IETF working group mailing lists are automatically backed up by the 216 IETF Secretariat, and the archives are publicly available. It would 217 be good for working group GitHub content to also be backed up and 218 publicly archived. This document proposes using the git protocol 219 [git-protocol] itself for both of these tasks. 221 Every IETF working group repository on GitHub will have a mirror 222 repository of the same name on a server maintained by the IETF 223 Secretariat. Every hour, a service will use the "git fetch" command 224 on every GitHub repository that is being tracked. The mirror 225 repository will allow anyone to read the repository. 227 Note that this system will not back up GitHub issues or pull 228 requests. It is very likely that these should be backed up as well. 229 The GitHub API possibly allows this; if so, the IETF Secretariat 230 should bac up those at the same time as it is backing up the GitHub 231 repositories. 233 4. Security Considerations 235 An attacker who can change the contents of Internet Drafts, 236 particularly late in a working group's process, can possibly cause 237 unnoticed changes in protocols that are eventually adopted. 239 5. IANA Considerations 241 This document has no IANA actions. 243 6. References 245 6.1. Normative References 247 [git-protocol] 248 "Git on the Server - The Protocols", n.d., . 252 6.2. Informative References 254 [I-D.thomson-github-bcp] 255 Thomson, M. and A. Atlas, "Using GitHub at the IETF", 256 draft-thomson-github-bcp-00 (work in progress), February 257 2017. 259 Authors' Addresses 261 Alissa Cooper 262 Cisco 264 Email: alcoop@cisco.com 266 Paul Hoffman 267 ICANN 269 Email: paul.hoffman@icann.org