idnits 2.17.1 draft-ietf-git-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 (March 08, 2019) is 1868 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: September 9, 2019 ICANN 6 March 08, 2019 8 GitHub Configuration for IETF Working Groups 9 draft-ietf-git-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 require changes to the processes 17 used by current and future working groups not using GitHub. 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 September 9, 2019. 41 Copyright Notice 43 Copyright (c) 2019 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 . . . . . . . . . . . . . . . . . . . . . . . 7 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. Some other working groups use or plan to use 83 other other code repository services such at GitLab and Bitbucket, 84 which have different properties than GitHub. 86 This document proposes a set of administrative processes and 87 conventions for IETF working groups to use if they chose as a working 88 group to use GitHub to facilitate their work. The proposals in this 89 document are not directed at working groups or individuals that are 90 already using GitHub to do IETF work. Practices vary among existing 91 working groups and some of them are not consistent with the 92 conventions proposed here: that is fine. The goal of the proposals 93 in this document is not to require uniformity in current practice, 94 but to help working groups to get started using GitHub in a uniform 95 way if they want to. 97 The document is meant to spur discussion in the IETF community. If 98 there proves to be rough consensus in the community in support of the 99 proposals in this document, the functional requirements would need to 100 be discussed with the IETF Tools Team, and the IETF Secretariat who 101 would need to support various pieces of what is proposed here. 103 2. Administrative Process and Conventions 105 This section specifies a proposal for an administrative process and 106 conventions to support the creation and management of GitHub 107 organizations for working groups and single-document repositories in 108 a uniform way. The steps could be done manually by the IETF 109 Secretariat or they could be automated. For example, see 110 and 111 for working examples 112 of automation that is in use in some working groups. 114 In this document the question of whether processes should be manual 115 or automated is deliberately left ambiguous since the first question 116 that should be asked is whether this is functionality the community 117 would want to have supported at all. 119 Most of the conventions below are drawn from 120 [I-D.thomson-github-bcp]. 122 2.1. Creation of GitHub Organizations 124 This document proposes that there be a facility in the IETF 125 Datatracker () interface to allow an 126 area director or working group chair to request the creation of a 127 GitHub organization for a particular working group. Ideally, this 128 facility would appear both as part of the working group chartering UI 129 as well as the working group page UI. 131 When an area director or working group chair makes a request to 132 create a GitHub organization, the following process would be 133 initiated: 135 1. Create a GitHub organization for the working group. 137 2. Name the organization as ietf--wg 139 3. Initialize the organization by designating the IETF Secretariat 140 and the area directors in the working group's area as owners. If 141 the responsible AD for the working group is from another area, 142 that AD will be an owner as well. 144 4. Initialize the organization with a team that has administrator 145 access. This team will consist of the working group chairs and 146 working group secretary, if one exists. 148 After the organization is created, the URL for the organization would 149 be added to the working group's page in the datatracker. 151 Steps 3 and 4 above imply that the GitHub identities of the 152 organization owners and administrators are known. Recording GitHub 153 identities in the datatracker (see 154 ) would 155 facilitate this. The person requesting the organization would need 156 to be notified if the GitHub identities of any of the people meant to 157 be owners or administrators were not available. 159 2.2. Migration of an Existing Organization 161 If a working group already has an organization, it would be useful to 162 be able to make it have the same management as one would get with 163 going through the steps in Section 2.1. That is, it would be good to 164 be able to run steps 3 and 4 from Section 2.1 so that the rest of the 165 activities in this section such as personnel work the same for the 166 organizations that were created on their own. 168 2.3. Personnel Changes 170 When there are personnel changes in the area or the working group, 171 those changes would be reflected in the GitHub organization. There 172 should likely be an API to specify that there were personnel changes. 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 289 Paul Hoffman 290 ICANN 292 Email: paul.hoffman@icann.org