idnits 2.17.1 draft-cooper-wugh-github-wg-configuration-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 : ---------------------------------------------------------------------------- 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 (October 22, 2018) is 2013 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: April 25, 2019 ICANN 6 October 22, 2018 8 GitHub Configuration for IETF Working Groups 9 draft-cooper-wugh-github-wg-configuration-01 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 April 25, 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. [[ Need 170 to do a bit of research on how to do this through the API, if 171 possible. ]] 173 2.4. Working Group Closing 175 When a working group is closed, the team with administrative access 176 would be removed and the owner list would be returned to its initial 177 composition. The organization summary and the repositories within 178 the organization would be updated to indicate that they are no longer 179 under development. 181 2.5. Creation of Document Repository 183 There are many different scenarios and configurations where it might 184 be useful to have automation and/or established administrative 185 conventions for repositories within WG organizations, such as: 187 o Creating a new repository for an individual draft that is likely 188 to become a working group document 190 o Creating a new repository for an adopted working group draft 192 o Migrating an existing document repository into the WG organization 193 o Creating a new repository that contains multiple drafts 195 As an incremental step, this document proposes that there be a 196 facility in the Datatracker interface to allow an administrator of an 197 ietf--wg organization to request the creation of a new 198 repository within that organization for a single document. The 199 document authors would be identified as collaborators. The 200 repository name would be the draft name. Ideally, the repository 201 would be configured with an skeleton draft file, default 202 CONTRIBUTING, LICENSE, and README files, and continuous integration 203 support, in the vein of . 206 3. Working Group Process 208 [I-D.thomson-github-bcp] contains discussion of the different 209 possible ways that a working group can use GitHub and the large 210 number of decisions associated with doing so. This section proposes 211 a basic set of administrative policies for working groups to follow 212 and the administrative support needed to carry out those policies. 214 3.1. Contributions 216 At a minimum, every repository created in a working group 217 organization needs to incorporate into its CONTRIBUTING file the 218 boilerplate text at from the IETF license file for open source 220 repositories. The CONTRIBUTING file can contain other information as 221 well (see for examples). 224 It would be useful if the user data in the Datatracker could list (at 225 a minimum) the GitHub account of the user so that their contributions 226 could be tracked more easily. 228 3.2. Backing Up and Archiving GitHub Content 230 IETF working group mailing lists are automatically backed up by the 231 IETF Secretariat, and the archives are publicly available. It would 232 be good for working group GitHub content to also be backed up and 233 publicly archived. This document proposes using the git protocol 234 [git-protocol] itself for both of these tasks. 236 Every IETF working group repository on GitHub will have a mirror 237 repository of the same name on a server maintained by the IETF 238 Secretariat. Every hour, a service will use the "git fetch" command 239 on every GitHub repository that is being tracked. The mirror 240 repository will allow anyone to read the repository. 242 Note that this system will not back up GitHub issues or pull 243 requests. It is very likely that these should be backed up as well. 244 The GitHub API possibly allows this; if so, the IETF Secretariat 245 should back up those at the same time as it is backing up the GitHub 246 repositories. 248 4. Security Considerations 250 An attacker who can change the contents of Internet Drafts, 251 particularly late in a working group's process, can possibly cause 252 unnoticed changes in protocols that are eventually adopted. 254 5. IANA Considerations 256 This document has no IANA actions. 258 6. References 260 6.1. Normative References 262 [git-protocol] 263 "Git on the Server - The Protocols", n.d., . 267 6.2. Informative References 269 [I-D.thomson-github-bcp] 270 Thomson, M. and A. Atlas, "Using GitHub at the IETF", 271 draft-thomson-github-bcp-00 (work in progress), February 272 2017. 274 Authors' Addresses 276 Alissa Cooper 277 Cisco 279 Email: alcoop@cisco.com 281 Paul Hoffman 282 ICANN 284 Email: paul.hoffman@icann.org