Internet DRAFT - draft-cooper-wugh-github-wg-configuration
draft-cooper-wugh-github-wg-configuration
wugh A. Cooper
Internet-Draft Cisco
Intended status: Informational P. Hoffman
Expires: June 20, 2019 ICANN
December 17, 2018
GitHub Configuration for IETF Working Groups
draft-cooper-wugh-github-wg-configuration-02
Abstract
The use of GitHub in IETF working group processes is increasing.
This document describes possible uses and conventions for working
groups which are considering starting to use GitHub. It does not
mandate any processes, and does not intend to change the processes
used by current working groups.
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
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 20, 2019.
Copyright Notice
Copyright (c) 2018 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
Cooper & Hoffman Expires June 20, 2019 [Page 1]
Internet-Draft GitHub Configuration December 2018
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Administrative Process and Conventions . . . . . . . . . . . 3
2.1. Creation of GitHub Organizations . . . . . . . . . . . . 3
2.2. Migration of an Existing Organization . . . . . . . . . . 4
2.3. Personnel Changes . . . . . . . . . . . . . . . . . . . . 4
2.4. Working Group Closing . . . . . . . . . . . . . . . . . . 4
2.5. Creation of Document Repository . . . . . . . . . . . . . 4
3. Working Group Process . . . . . . . . . . . . . . . . . . . . 5
3.1. Contributions . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Backing Up and Archiving GitHub Content . . . . . . . . . 5
4. Security Considerations . . . . . . . . . . . . . . . . . . . 6
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
6.1. Normative References . . . . . . . . . . . . . . . . . . 6
6.2. Informative References . . . . . . . . . . . . . . . . . 6
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6
1. Introduction
Many IETF working groups and participants make use of GitHub in
different ways as part of their work on IETF documents. Some others
are interested in having their working groups use GitHub to
facilitate the development of working group documents, but they are
unfamiliar with how to get started or they are unclear about which
conventions to follow.
This document proposes a set of administrative processes and
conventions for IETF working groups to use if they chose as a working
group to use GitHub to facilitate their work. The proposals in this
document are not directed at working groups or individuals that are
already using GitHub to do IETF work. Practices vary among existing
working groups and some of them are not consistent with the
conventions proposed here: that is fine. The goal of the proposals
in this document is not to require uniformity in current practice,
but to help working groups to get started using GitHub in a uniform
way if they want to.
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
Cooper & Hoffman Expires June 20, 2019 [Page 2]
Internet-Draft GitHub Configuration December 2018
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 here.
2. Administrative Process and Conventions
This section specifies a proposal for an administrative process and
conventions to support the creation and management of GitHub
organizations for working groups and single-document repositories in
a uniform way. The steps could be done manually by the IETF
Secretariat or they could be automated. For example, see
<https://github.com/richsalz/ietf-gh-scripts> and
<https://github.com/martinthomson/i-d-template> for working examples
of automation that is in use in some working groups.
In this document the question of whether processes should be manual
or automated is deliberately left ambiguous since the first question
that should be asked is whether this is functionality the community
would want to have supported at all.
Most of the conventions below are drawn from
[I-D.thomson-github-bcp].
2.1. Creation of GitHub Organizations
This document proposes that there be a facility in the IETF
Datatracker (<https://datatracker.ietf.org/>) interface to allow an
area director or working group chair to request the creation of a
GitHub organization for a particular working group. Ideally, this
facility would appear both as part of the working group chartering UI
as well as the working group page UI.
When an area director or working group chair makes a request to
create a GitHub organization, the following process would be
initiated:
1. Create a GitHub organization for the working group.
2. Name the organization as ietf-<wgname>-wg
3. Initialize the organization by designating the IETF Secretariat
and the area directors in the working group's area as owners. If
the responsible AD for the working group is from another area,
that AD will be an owner as well.
4. Initialize the organization with a team that has administrator
access. This team will consist of the working group chairs and
working group secretary, if one exists.
Cooper & Hoffman Expires June 20, 2019 [Page 3]
Internet-Draft GitHub Configuration December 2018
After the organization is created, the URL for the organization would
be added to the working group's page in the datatracker.
Steps 3 and 4 above imply that the GitHub identities of the
organization owners and administrators are known. Recording GitHub
identities in the datatracker (see
<https://trac.tools.ietf.org/tools/ietfdb/ticket/2548>) would
facilitate this. The person requesting the organization would need
to be notified if the GitHub identities of any of the people meant to
be owners or administrators were not available.
2.2. Migration of an Existing Organization
If a working group already has an organization, it would be useful to
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
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 work the same for the
organizations that were created on their own.
2.3. Personnel Changes
When there are personnel changes in the area or the working group,
those changes would be reflected in the GitHub organization. There
should likely be an API to specify that there were personnel changes.
[[ Need to do a bit of research on how to do this through the API, if
possible. ]]
2.4. Working Group Closing
When a working group is closed, the team with administrative access
would be removed and the owner list would be returned to its initial
composition. The organization summary and the repositories within
the organization would be updated to indicate that they are no longer
under development.
2.5. Creation of Document Repository
There are many different scenarios and configurations where it might
be useful to have automation and/or established administrative
conventions for repositories within WG organizations, such as:
o Creating a new repository for an individual draft that is at the
discretion of the WG chair
o Creating a new repository for an already-adopted working group
draft
Cooper & Hoffman Expires June 20, 2019 [Page 4]
Internet-Draft GitHub Configuration December 2018
o Migrating an existing document repository into the WG organization
o Creating a new repository that contains multiple drafts
As an incremental step, this document proposes that there be a
facility in the Datatracker interface to allow an administrator of an
ietf-<wgname>-wg organization to request the creation of a new
repository within that organization for a single document. The
document authors would be identified as collaborators. The
repository name would be the draft name. Ideally, the repository
would be configured with an skeleton draft file, default
CONTRIBUTING, LICENSE, and README files, and continuous integration
support, in the vein of <https://github.com/martinthomson/
i-d-template>.
3. Working Group Process
[I-D.thomson-github-bcp] contains discussion of the different
possible ways that a working group can use GitHub and the large
number of decisions associated with doing so. This section proposes
a basic set of administrative policies for working groups to follow
and the administrative support needed to carry out those policies.
3.1. Contributions
At a minimum, every repository created in a working group
organization needs to incorporate into its CONTRIBUTING file the
boilerplate text at <https://trustee.ietf.org/license-for-open-
source-repositories.html> from the IETF license file for open source
repositories. The CONTRIBUTING file can contain other information 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) the GitHub account of the user so that their contributions
could be tracked more easily.
3.2. Backing Up and Archiving GitHub Content
IETF working group mailing lists are automatically backed up by the
IETF Secretariat, and the archives are publicly available. All
official interactions in a WG must be archived.
It would be good for working group GitHub content to also be backed
up and publicly archived. This document proposes using the git
protocol [git-protocol] itself for both of these tasks.
Cooper & Hoffman Expires June 20, 2019 [Page 5]
Internet-Draft GitHub Configuration December 2018
Every IETF working group repository on GitHub will have a mirror
repository of the same name 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 mirror
repository will allow anyone to read the repository.
Note that this system will not back up GitHub issues or pull
requests. It is very likely that these should be backed up as well.
The GitHub API possibly allows this; if so, the IETF Secretariat
should back up those at the same time as it is backing up the GitHub
repositories.
[I-D.thomson-github-bcp] has more discussion of backing up and
archiving.
4. Security Considerations
An attacker who can change the contents of Internet Drafts,
particularly late in a working group's process, can possibly cause
unnoticed changes in protocols that are eventually adopted.
5. IANA Considerations
This document has no IANA actions.
6. References
6.1. Normative References
[git-protocol]
"Git on the Server - The Protocols", n.d., <https://git-
scm.com/book/en/v2/
Git-on-the-Server-The-Protocols#The-Git-Protocol>.
6.2. Informative References
[I-D.thomson-github-bcp]
Thomson, M. and A. Atlas, "Using GitHub at the IETF",
draft-thomson-github-bcp-00 (work in progress), February
2017.
Authors' Addresses
Alissa Cooper
Cisco
Email: alcoop@cisco.com
Cooper & Hoffman Expires June 20, 2019 [Page 6]
Internet-Draft GitHub Configuration December 2018
Paul Hoffman
ICANN
Email: paul.hoffman@icann.org
Cooper & Hoffman Expires June 20, 2019 [Page 7]