| RFC 8875 | WG GitHub Admin | August 2020 |
| Cooper & Hoffman | Informational | [Page] |
The use of GitHub in IETF working group processes is increasing.This document describes uses and conventions for workinggroups that are considering starting to use GitHub. It does notmandate any processes and does not require changes to the processesused by current and future working groups not using GitHub.¶
This document is not an Internet Standards Track specification; it is published for informational purposes.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are candidates for any level of Internet Standard; see Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc8875.¶
Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
Many IETF working groups and participants make use of GitHub in different ways as part oftheir work on IETF documents. Some others are interested in having their working groupsuse GitHub to facilitate the development of working group documents, but they areunfamiliar with how to get started or unclear about which conventions to follow.Some other working groups use or plan to use other code-repository servicessuch as GitLab and Bitbucket, which havedifferent properties than GitHub.¶
This document specifies a set of administrative processes and conventions for IETF workinggroups to use if they choose as a working group to use GitHub to facilitate their work. The specifications in this document are not directed at working groups or individuals that arealready using GitHub to do IETF work. Practices vary among existing working groups, andsome of them are not consistent with the conventions proposed here: that is fine. The goalof the specifications in this document is not to require uniformity in current practice, but tohelp working groups get started using GitHub in a reviewed and validated way, if desired.¶
This section specifies an administrative process and conventions to supportthe creation and management of GitHub organizations for working groups and single-documentrepositories in a uniform way. The steps may be done manually by the IETF Secretariat, orthey may be automated. See<https://github.com/richsalz/ietf-gh-scripts> and<https://github.com/martinthomson/i-d-template> for working examples of automationthat is in use in some working groups.¶
In this document the question of whether processes should be manual or automated isdeliberately left unspecified, since these are implementation details that the IETF Secretariat and Tools Team will address.¶
Most of the conventions below are drawn from[RFC8874].¶
This document specifies that there be a facility in the IETF Datatracker(<https://datatracker.ietf.org/>) interface to allow an area director (AD) orworking group chair to request the creation of a GitHub organization for aparticular workinggroup. Ideally, this facility would appear both as part of the working groupchartering UI and the working group page UI.¶
When an area director or working group chair makes a request to create a GitHuborganization, the following process would be initiated:¶
After the organization is created, the URL for the organization would be added to theworking group's page in the Datatracker.¶
Steps3 and4 above imply that the GitHub identities of the organization owners andadministrators are known. Recording GitHub identities in the Datatracker (see<https://trac.tools.ietf.org/tools/ietfdb/ticket/2548>) would facilitate this. Theperson requesting the organization would need to be notified if the GitHub identities ofany of the people meant to be owners or administrators were not available.¶
If a working group already has an organization, it would be useful to be ableto make it have the same management as one would get by going through thesteps inSection 2.1. That is, it would be goodto be able to run Steps3 and4 fromSection 2.1 so that the rest of the activities in this section, such aspersonnel changes, work the same way as for organizations that were created asspecified herein.¶
When there are personnel changes in the area or the working group, those changes would bereflected in the GitHub organization.There should be an ability in the Datatracker to specify that personnel changes have occurred.¶
When a working group is closed, the team with administrative access would be removed, andthe owner list would be returned to the Secretariat and current ADs at the time of closing.The organization summary and the repositories within the organization would be updated toindicate that they are no longer under development.Later, the owner list could become just the Secretariat, or it might include otherschosen by the Secretariat or the IESG.¶
There are many different scenarios and configurations where it might be useful to haveautomation or established administrative conventions for repositories within WGorganizations, such as:¶
As an incremental step, this document specifies that there be a facility in the Datatrackerinterface to allow an administrator of an ietf-wg-<wgname> organization to requestthe creation of a new repository within that organization for a single document. Thedocument authors would be identified as collaborators. The repository name would be thedraft name. Ideally, the repository would be configured with a skeleton draft file,default CONTRIBUTING, LICENSE, and README files, and continuous integration support, inthe vein of <https://github.com/martinthomson/i-d-template>.Performing this step would automatically inform the IETF Secretariat that this repository shouldbe backed up as described inSection 3.2.¶
The IETF Datatracker should allow users to add links to repositories (for GitHub andother repository services) on working group, document, and user pages.At the time of this writing, this feature was under development.¶
[RFC8874] contains discussion of the different possible ways that aworking group can use GitHub and the large number of decisions associated with doing so.This section specifies a basic set of administrative policies for working groups to followand the administrative support needed to carry out those policies.¶
At a minimum, every repository created in a working group organization needs toincorporate into its CONTRIBUTING file the boilerplate text at<https://trustee.ietf.org/license-for-open-source-repositories.html> from the IETFlicense file for open-source repositories. The CONTRIBUTING file can contain otherinformation as well (see<https://github.com/ietf/repo-files/tree/master/contributing-samples> for examples).¶
It would be useful if the user data in the Datatracker could list (at a minimum) theGitHub account of the user so that their contributions could be tracked more easily.¶
Some working groups choose to have more than one draft in a repository, particularlyfor drafts that are tightly linked with significant cross-references.In such a case, the README for the repository needs to say so clearly, so thata participant understands that changes might be made to multiple drafts at once.¶
IETF working group mailing lists are automatically backed up by the IETF Secretariat, andthe archives are publicly available. All official interactions in a WG must be archived.¶
Working group GitHub content also needs to be backed up and publicly archived. This document specifies using the Git protocol[git-protocol] itself for both of these tasks.¶
Every IETF working group repository on GitHub will have a mirror repository of the samename on a server maintained by the IETF Secretariat. Every hour, a service will use the"git fetch" command on every GitHub repository that is being tracked. The mirrorrepository will allow anyone to read the repository.¶
Note that this system will not back up GitHub issues or pull requests.These should be backed up as well; the GitHub API allows for this.The IETF Secretariat should back up those at the same time as it is backing up the GitHubrepositories.¶
The steps inSection 2.5 inform the IETF Secretariat which repositories should be backed up.Working group chairs and area directors should also be able to request that the IETFSecretariat back up additional repositories that are related to IETF working groups.¶
An attacker who can change the contents of Internet-Drafts, particularly late in a workinggroup's process, can possibly cause unnoticed changes in protocols that are eventuallyadopted.¶
There is a risk of data loss due to centralization of data in one service.This is recognized and mitigated by the plan described inSection 3.2.¶
This document has no IANA actions.¶