idnits 2.17.1 draft-cooper-wugh-github-wg-configuration-02.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 (December 17, 2018) is 1955 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: June 20, 2019 ICANN 6 December 17, 2018 8 GitHub Configuration for IETF Working Groups 9 draft-cooper-wugh-github-wg-configuration-02 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 June 20, 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. Migration of an Existing Organization . . . . . . . . . . 4 62 2.3. Personnel Changes . . . . . . . . . . . . . . . . . . . . 4 63 2.4. Working Group Closing . . . . . . . . . . . . . . . . . . 4 64 2.5. Creation of Document Repository . . . . . . . . . . . . . 4 65 3. Working Group Process . . . . . . . . . . . . . . . . . . . . 5 66 3.1. Contributions . . . . . . . . . . . . . . . . . . . . . . 5 67 3.2. Backing Up and Archiving GitHub Content . . . . . . . . . 5 68 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 70 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 71 6.1. Normative References . . . . . . . . . . . . . . . . . . 6 72 6.2. Informative References . . . . . . . . . . . . . . . . . 6 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 75 1. Introduction 77 Many IETF working groups and participants make use of GitHub in 78 different ways as part of their work on IETF documents. Some others 79 are interested in having their working groups use GitHub to 80 facilitate the development of working group documents, but they are 81 unfamiliar with how to get started or they are unclear about which 82 conventions to follow. 84 This document proposes a set of administrative processes and 85 conventions for IETF working groups to use if they chose as a working 86 group to use GitHub to facilitate their work. The proposals in this 87 document are not directed at working groups or individuals that are 88 already using GitHub to do IETF work. Practices vary among existing 89 working groups and some of them are not consistent with the 90 conventions proposed here: that is fine. The goal of the proposals 91 in this document is not to require uniformity in current practice, 92 but to help working groups to get started using GitHub in a uniform 93 way if they want to. 95 The document is meant to spur discussion in the IETF community. If 96 there proves to be rough consensus in the community in support of the 97 proposals in this document, the functional requirements would need to 98 be discussed with the IETF Tools Team, and the IETF Secretariat who 99 would need to support various pieces of what is proposed here. 101 2. Administrative Process and Conventions 103 This section specifies a proposal for an administrative process and 104 conventions to support the creation and management of GitHub 105 organizations for working groups and single-document repositories in 106 a uniform way. The steps could be done manually by the IETF 107 Secretariat or they could be automated. For example, see 108 and 109 for working examples 110 of automation that is in use in some working groups. 112 In this document the question of whether processes should be manual 113 or automated is deliberately left ambiguous since the first question 114 that should be asked is whether this is functionality the community 115 would want to have supported at all. 117 Most of the conventions below are drawn from 118 [I-D.thomson-github-bcp]. 120 2.1. Creation of GitHub Organizations 122 This document proposes that there be a facility in the IETF 123 Datatracker () interface to allow an 124 area director or working group chair to request the creation of a 125 GitHub organization for a particular working group. Ideally, this 126 facility would appear both as part of the working group chartering UI 127 as well as the working group page UI. 129 When an area director or working group chair makes a request to 130 create a GitHub organization, the following process would be 131 initiated: 133 1. Create a GitHub organization for the working group. 135 2. Name the organization as ietf--wg 137 3. Initialize the organization by designating the IETF Secretariat 138 and the area directors in the working group's area as owners. If 139 the responsible AD for the working group is from another area, 140 that AD will be an owner as well. 142 4. Initialize the organization with a team that has administrator 143 access. This team will consist of the working group chairs and 144 working group secretary, if one exists. 146 After the organization is created, the URL for the organization would 147 be added to the working group's page in the datatracker. 149 Steps 3 and 4 above imply that the GitHub identities of the 150 organization owners and administrators are known. Recording GitHub 151 identities in the datatracker (see 152 ) would 153 facilitate this. The person requesting the organization would need 154 to be notified if the GitHub identities of any of the people meant to 155 be owners or administrators were not available. 157 2.2. Migration of an Existing Organization 159 If a working group already has an organization, it would be useful to 160 be able to make it have the same management as one would get with 161 going through the steps in Section 2.1. That is, it would be good to 162 be able to run steps 3 and 4 from Section 2.1 so that the rest of the 163 activities in this section such as personnel work the same for the 164 organizations that were created on their own. 166 2.3. Personnel Changes 168 When there are personnel changes in the area or the working group, 169 those changes would be reflected in the GitHub organization. There 170 should likely be an API to specify that there were personnel changes. 171 [[ Need to do a bit of research on how to do this through the API, if 172 possible. ]] 174 2.4. Working Group Closing 176 When a working group is closed, the team with administrative access 177 would be removed and the owner list would be returned to its initial 178 composition. The organization summary and the repositories within 179 the organization would be updated to indicate that they are no longer 180 under development. 182 2.5. Creation of Document Repository 184 There are many different scenarios and configurations where it might 185 be useful to have automation and/or established administrative 186 conventions for repositories within WG organizations, such as: 188 o Creating a new repository for an individual draft that is at the 189 discretion of the WG chair 191 o Creating a new repository for an already-adopted working group 192 draft 194 o Migrating an existing document repository into the WG organization 196 o Creating a new repository that contains multiple drafts 198 As an incremental step, this document proposes that there be a 199 facility in the Datatracker interface to allow an administrator of an 200 ietf--wg organization to request the creation of a new 201 repository within that organization for a single document. The 202 document authors would be identified as collaborators. The 203 repository name would be the draft name. Ideally, the repository 204 would be configured with an skeleton draft file, default 205 CONTRIBUTING, LICENSE, and README files, and continuous integration 206 support, in the vein of . 209 3. Working Group Process 211 [I-D.thomson-github-bcp] contains discussion of the different 212 possible ways that a working group can use GitHub and the large 213 number of decisions associated with doing so. This section proposes 214 a basic set of administrative policies for working groups to follow 215 and the administrative support needed to carry out those policies. 217 3.1. Contributions 219 At a minimum, every repository created in a working group 220 organization needs to incorporate into its CONTRIBUTING file the 221 boilerplate text at from the IETF license file for open source 223 repositories. The CONTRIBUTING file can contain other information as 224 well (see for examples). 227 It would be useful if the user data in the Datatracker could list (at 228 a minimum) the GitHub account of the user so that their contributions 229 could be tracked more easily. 231 3.2. Backing Up and Archiving GitHub Content 233 IETF working group mailing lists are automatically backed up by the 234 IETF Secretariat, and the archives are publicly available. All 235 official interactions in a WG must be archived. 237 It would be good for working group GitHub content to also be backed 238 up and publicly archived. This document proposes using the git 239 protocol [git-protocol] itself for both of these tasks. 241 Every IETF working group repository on GitHub will have a mirror 242 repository of the same name on a server maintained by the IETF 243 Secretariat. Every hour, a service will use the "git fetch" command 244 on every GitHub repository that is being tracked. The mirror 245 repository will allow anyone to read the repository. 247 Note that this system will not back up GitHub issues or pull 248 requests. It is very likely that these should be backed up as well. 249 The GitHub API possibly allows this; if so, the IETF Secretariat 250 should back up those at the same time as it is backing up the GitHub 251 repositories. 253 [I-D.thomson-github-bcp] has more discussion of backing up and 254 archiving. 256 4. Security Considerations 258 An attacker who can change the contents of Internet Drafts, 259 particularly late in a working group's process, can possibly cause 260 unnoticed changes in protocols that are eventually adopted. 262 5. IANA Considerations 264 This document has no IANA actions. 266 6. References 268 6.1. Normative References 270 [git-protocol] 271 "Git on the Server - The Protocols", n.d., . 275 6.2. Informative References 277 [I-D.thomson-github-bcp] 278 Thomson, M. and A. Atlas, "Using GitHub at the IETF", 279 draft-thomson-github-bcp-00 (work in progress), February 280 2017. 282 Authors' Addresses 284 Alissa Cooper 285 Cisco 287 Email: alcoop@cisco.com 288 Paul Hoffman 289 ICANN 291 Email: paul.hoffman@icann.org