< draft-ietf-git-github-wg-configuration-06.txt   draft-ietf-git-github-wg-configuration-07.txt >
GIT Working Group A. Cooper GIT Working Group A. Cooper
Internet-Draft Cisco Internet-Draft Cisco
Intended status: Informational P. Hoffman Intended status: Informational P. Hoffman
Expires: August 16, 2020 ICANN Expires: October 15, 2020 ICANN
February 13, 2020 April 13, 2020
Working Group GitHub Administration Working Group GitHub Administration
draft-ietf-git-github-wg-configuration-06 draft-ietf-git-github-wg-configuration-07
Abstract Abstract
The use of GitHub in IETF working group processes is increasing. The use of GitHub in IETF working group processes is increasing.
This document describes possible uses and conventions for working This document describes uses and conventions for working groups which
groups which are considering starting to use GitHub. It does not are considering starting to use GitHub. It does not mandate any
mandate any processes, and does not require changes to the processes processes, and does not require changes to the processes used by
used by current and future working groups not using GitHub. current and future working groups not using GitHub.
Discussion of this document takes place on the ietf-and-github
mailing list (ietf-and-github@ietf.org), which is archived at
<https://mailarchive.ietf.org/arch/search?email_list=ietf-and-
github>.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 16, 2020. This Internet-Draft will expire on October 15, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Administrative Process and Conventions . . . . . . . . . . . 3 2. Administrative Process and Conventions . . . . . . . . . . . 2
2.1. Creation of GitHub Organizations . . . . . . . . . . . . 3 2.1. Creation of GitHub Organizations . . . . . . . . . . . . 3
2.2. Migration of an Existing Organization . . . . . . . . . . 4 2.2. Migration of an Existing Organization . . . . . . . . . . 4
2.3. Personnel Changes . . . . . . . . . . . . . . . . . . . . 4 2.3. Personnel Changes . . . . . . . . . . . . . . . . . . . . 4
2.4. Working Group Closing . . . . . . . . . . . . . . . . . . 4 2.4. Working Group Closing . . . . . . . . . . . . . . . . . . 4
2.5. Creation of Document Repository . . . . . . . . . . . . . 4 2.5. Creation of Document Repository . . . . . . . . . . . . . 4
2.6. Listing Related Repositories . . . . . . . . . . . . . . 5 2.6. Listing Related Repositories . . . . . . . . . . . . . . 5
3. Working Group Process . . . . . . . . . . . . . . . . . . . . 5 3. Working Group Process . . . . . . . . . . . . . . . . . . . . 5
3.1. Contributions . . . . . . . . . . . . . . . . . . . . . . 5 3.1. Contributions . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Backing Up and Archiving GitHub Content . . . . . . . . . 6 3.2. Backing Up and Archiving GitHub Content . . . . . . . . . 6
4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6
skipping to change at page 2, line 40 skipping to change at page 2, line 36
Many IETF working groups and participants make use of GitHub in Many IETF working groups and participants make use of GitHub in
different ways as part of their work on IETF documents. Some others different ways as part of their work on IETF documents. Some others
are interested in having their working groups use GitHub to are interested in having their working groups use GitHub to
facilitate the development of working group documents, but they are facilitate the development of working group documents, but they are
unfamiliar with how to get started or they are unclear about which unfamiliar with how to get started or they are unclear about which
conventions to follow. Some other working groups use or plan to use conventions to follow. Some other working groups use or plan to use
other code repository services such as GitLab and Bitbucket, which other code repository services such as GitLab and Bitbucket, which
have different properties than GitHub. have different properties than GitHub.
This document proposes a set of administrative processes and This document specifies a set of administrative processes and
conventions for IETF working groups to use if they choose as a conventions for IETF working groups to use if they choose as a
working group to use GitHub to facilitate their work. The proposals working group to use GitHub to facilitate their work. The
in this document are not directed at working groups or individuals specifications in this document are not directed at working groups or
that are already using GitHub to do IETF work. Practices vary among individuals that are already using GitHub to do IETF work. Practices
existing working groups and some of them are not consistent with the vary among existing working groups and some of them are not
conventions proposed here: that is fine. The goal of the proposals consistent with the conventions proposed here: that is fine. The
in this document is not to require uniformity in current practice, goal of the specifications in this document is not to require
but to help working groups get started using GitHub in a uniform way uniformity in current practice, but to help working groups get
if desired. started using GitHub in a reviewed and validated way if desired.
The document is meant to spur discussion in the IETF community. If
there proves to be rough consensus in the community in support of the
proposals in this document, the functional requirements would need to
be discussed with the IETF Tools Team and the IETF Secretariat, who
would need to support various pieces of what is proposed herein.
2. Administrative Process and Conventions 2. Administrative Process and Conventions
This section specifies a proposal for an administrative process and This section specifies an administrative process and conventions to
conventions to support the creation and management of GitHub support the creation and management of GitHub organizations for
organizations for working groups and single-document repositories in working groups and single-document repositories in a uniform way.
a uniform way. The steps could be done manually by the IETF
Secretariat or they could be automated. See The steps may be done manually by the IETF Secretariat or they may be
<https://github.com/richsalz/ietf-gh-scripts> and automated. See <https://github.com/richsalz/ietf-gh-scripts> and
<https://github.com/martinthomson/i-d-template> for working examples <https://github.com/martinthomson/i-d-template> for working examples
of automation that is in use in some working groups. of automation that is in use in some working groups.
In this document the question of whether processes should be manual In this document the question of whether processes should be manual
or automated is deliberately left unspecified, since the first or automated is deliberately left unspecified, since these are
question that should be asked is whether this is functionality the implementation details that the IETF Secretariat and Tools Team will
community would want to have supported at all. address.
Most of the conventions below are drawn from Most of the conventions below are drawn from
[I-D.ietf-git-using-github]. [I-D.ietf-git-using-github].
2.1. Creation of GitHub Organizations 2.1. Creation of GitHub Organizations
This document proposes that there be a facility in the IETF This document specifies that there be a facility in the IETF
Datatracker (<https://datatracker.ietf.org/>) interface to allow an Datatracker (<https://datatracker.ietf.org/>) interface to allow an
area director or working group chair to request the creation of a area director or working group chair to request the creation of a
GitHub organization for a particular working group. Ideally, this GitHub organization for a particular working group. Ideally, this
facility would appear both as part of the working group chartering UI facility would appear both as part of the working group chartering UI
as well as the working group page UI. as well as the working group page UI.
When an area director or working group chair makes a request to When an area director or working group chair makes a request to
create a GitHub organization, the following process would be create a GitHub organization, the following process would be
initiated: initiated:
skipping to change at page 4, line 33 skipping to change at page 4, line 20
be able to make it have the same management as one would get with be able to make it have the same management as one would get with
going through the steps in Section 2.1. That is, it would be good to going through the steps in Section 2.1. That is, it would be good to
be able to run steps 3 and 4 from Section 2.1 so that the rest of the be able to run steps 3 and 4 from Section 2.1 so that the rest of the
activities in this section, such as personnel changes, work the same activities in this section, such as personnel changes, work the same
way as for organizations that were created as specified herein. way as for organizations that were created as specified herein.
2.3. Personnel Changes 2.3. Personnel Changes
When there are personnel changes in the area or the working group, When there are personnel changes in the area or the working group,
those changes would be reflected in the GitHub organization. There those changes would be reflected in the GitHub organization. There
should likely be an API to specify that there were personnel changes. should be an ability in the Datatracker to specify that there were
personnel changes.
2.4. Working Group Closing 2.4. Working Group Closing
When a working group is closed, the team with administrative access When a working group is closed, the team with administrative access
would be removed and the owner list would be returned to the would be removed and the owner list would be returned to the
Secretariat and current ADs at the time of closing. The organization Secretariat and current ADs at the time of closing. The organization
summary and the repositories within the organization would be updated summary and the repositories within the organization would be updated
to indicate that they are no longer under development. to indicate that they are no longer under development. Later, the
owner list could become just the Secretariat, or might include others
chosen by the Secretariat or the IESG.
2.5. Creation of Document Repository 2.5. Creation of Document Repository
There are many different scenarios and configurations where it might There are many different scenarios and configurations where it might
be useful to have automation or established administrative be useful to have automation or established administrative
conventions for repositories within WG organizations, such as: conventions for repositories within WG organizations, such as:
o Creating a new repository for an individual draft (at the o Creating a new repository for an individual draft (at the
discretion of the WG chair); discretion of the WG chair);
o Creating a new repository for an already-adopted working group o Creating a new repository for an already-adopted working group
draft; draft;
o Migrating an existing document repository into the WG o Migrating an existing document repository into the WG
organization; and organization; and
o Creating a new repository that contains multiple drafts. o Creating a new repository that contains multiple drafts.
As an incremental step, this document proposes that there be a As an incremental step, this document specifies that there be a
facility in the Datatracker interface to allow an administrator of an facility in the Datatracker interface to allow an administrator of an
ietf-wg-<wgname> organization to request the creation of a new ietf-wg-<wgname> organization to request the creation of a new
repository within that organization for a single document. The repository within that organization for a single document. The
document authors would be identified as collaborators. The document authors would be identified as collaborators. The
repository name would be the draft name. Ideally, the repository repository name would be the draft name. Ideally, the repository
would be configured with a skeleton draft file, default CONTRIBUTING, would be configured with a skeleton draft file, default CONTRIBUTING,
LICENSE, and README files, and continuous integration support, in the LICENSE, and README files, and continuous integration support, in the
vein of <https://github.com/martinthomson/i-d-template>. Performing vein of <https://github.com/martinthomson/i-d-template>. Performing
this step would automatically inform the IETF Secretariat that this this step would automatically inform the IETF Secretariat that this
repository should be backed up as described in Section 3.2. repository should be backed up as described in Section 3.2.
skipping to change at page 5, line 36 skipping to change at page 5, line 25
The IETF Datatracker should allow users to add links to repositories The IETF Datatracker should allow users to add links to repositories
(for GitHub and other repository services) on working group, (for GitHub and other repository services) on working group,
document, and user pages. At the time of this writing this feature document, and user pages. At the time of this writing this feature
was under development. was under development.
3. Working Group Process 3. Working Group Process
[I-D.ietf-git-using-github] contains discussion of the different [I-D.ietf-git-using-github] contains discussion of the different
possible ways that a working group can use GitHub and the large possible ways that a working group can use GitHub and the large
number of decisions associated with doing so. This section proposes number of decisions associated with doing so. This section specifies
a basic set of administrative policies for working groups to follow a basic set of administrative policies for working groups to follow
and the administrative support needed to carry out those policies. and the administrative support needed to carry out those policies.
3.1. Contributions 3.1. Contributions
At a minimum, every repository created in a working group At a minimum, every repository created in a working group
organization needs to incorporate into its CONTRIBUTING file the organization needs to incorporate into its CONTRIBUTING file the
boilerplate text at <https://trustee.ietf.org/license-for-open- boilerplate text at <https://trustee.ietf.org/license-for-open-
source-repositories.html> from the IETF license file for open source source-repositories.html> from the IETF license file for open source
repositories. The CONTRIBUTING file can contain other information as repositories. The CONTRIBUTING file can contain other information as
skipping to change at page 6, line 17 skipping to change at page 6, line 11
significant cross-references. In such a case, the README for the significant cross-references. In such a case, the README for the
repository needs to say that clearly so that a participant repository needs to say that clearly so that a participant
understands that changes might be made to multiple drafts at once. understands that changes might be made to multiple drafts at once.
3.2. Backing Up and Archiving GitHub Content 3.2. Backing Up and Archiving GitHub Content
IETF working group mailing lists are automatically backed up by the IETF working group mailing lists are automatically backed up by the
IETF Secretariat, and the archives are publicly available. All IETF Secretariat, and the archives are publicly available. All
official interactions in a WG must be archived. official interactions in a WG must be archived.
It would be good for working group GitHub content to also be backed Working group GitHub content needs to also be backed up and publicly
up and publicly archived. This document proposes using the git archived. This document specifies using the git protocol
protocol [git-protocol] itself for both of these tasks. [git-protocol] itself for both of these tasks.
Every IETF working group repository on GitHub will have a mirror Every IETF working group repository on GitHub will have a mirror
repository of the same name on a server maintained by the IETF repository of the same name on a server maintained by the IETF
Secretariat. Every hour, a service will use the "git fetch" command Secretariat. Every hour, a service will use the "git fetch" command
on every GitHub repository that is being tracked. The mirror on every GitHub repository that is being tracked. The mirror
repository will allow anyone to read the repository. repository will allow anyone to read the repository.
Note that this system will not back up GitHub issues or pull Note that this system will not back up GitHub issues or pull
requests. These should be backed up as well; the GitHub API allows 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 for this. The IETF Secretariat should back up those at the same time
skipping to change at page 6, line 44 skipping to change at page 6, line 38
directors should also be able to request that the IETF Secretariat directors should also be able to request that the IETF Secretariat
back up additional repositories that are related to IETF working back up additional repositories that are related to IETF working
groups. groups.
4. Security Considerations 4. Security Considerations
An attacker who can change the contents of Internet Drafts, An attacker who can change the contents of Internet Drafts,
particularly late in a working group's process, can possibly cause particularly late in a working group's process, can possibly cause
unnoticed changes in protocols that are eventually adopted. unnoticed changes in protocols that are eventually adopted.
There is a risk of data loss due to centralization of data in one
service. This is recognized, and mitigated by the plan described in
Section 3.2.
5. IANA Considerations 5. IANA Considerations
This document has no IANA actions. This document has no IANA actions.
6. Informative References 6. Informative References
[git-protocol] [git-protocol]
"Git on the Server - The Protocols", n.d., <https://git- "Git on the Server - The Protocols", n.d., <https://git-
scm.com/book/en/v2/ scm.com/book/en/v2/
Git-on-the-Server-The-Protocols#The-Git-Protocol>. Git-on-the-Server-The-Protocols#The-Git-Protocol>.
[I-D.ietf-git-using-github] [I-D.ietf-git-using-github]
Thomson, M. and B. Stark, "Working Group GitHub Usage Thomson, M. and B. Stark, "Working Group GitHub Usage
Guidance", draft-ietf-git-using-github-03 (work in Guidance", draft-ietf-git-using-github-06 (work in
progress), December 2019. progress), March 2020.
Authors' Addresses Authors' Addresses
Alissa Cooper Alissa Cooper
Cisco Cisco
Email: alcoop@cisco.com Email: alcoop@cisco.com
Paul Hoffman Paul Hoffman
ICANN ICANN
 End of changes. 17 change blocks. 
48 lines changed or deleted 44 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/