Internet DRAFT - draft-ietf-git-github-wg-configuration

draft-ietf-git-github-wg-configuration







GIT Working Group                                              A. Cooper
Internet-Draft                                                     Cisco
Intended status: Informational                                P. Hoffman
Expires: October 15, 2020                                          ICANN
                                                          April 13, 2020


                  Working Group GitHub Administration
               draft-ietf-git-github-wg-configuration-07

Abstract

   The use of GitHub in IETF working group processes is increasing.
   This document describes uses and conventions for working groups which
   are considering starting to use GitHub.  It does not mandate any
   processes, and does not require changes to the processes used by
   current and future working groups not using 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 October 15, 2020.

Copyright Notice

   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




Cooper & Hoffman        Expires October 15, 2020                [Page 1]

Internet-Draft               WG GitHub Admin                  April 2020


   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  . . . . . . . . . . .   2
     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
     2.6.  Listing Related Repositories  . . . . . . . . . . . . . .   5
   3.  Working Group Process . . . . . . . . . . . . . . . . . . . .   5
     3.1.  Contributions . . . . . . . . . . . . . . . . . . . . . .   5
     3.2.  Backing Up and Archiving GitHub Content . . . . . . . . .   6
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   6.  Informative References  . . . . . . . . . . . . . . . . . . .   6
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   7

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.  Some other working groups use or plan to use
   other code repository services such as GitLab and Bitbucket, which
   have different properties than GitHub.

   This document specifies a set of administrative processes and
   conventions for IETF working groups 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 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 specifications in this document is not to require
   uniformity in current practice, but to help working groups get
   started using GitHub in a reviewed and validated way if desired.

2.  Administrative Process and Conventions

   This section specifies 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.



Cooper & Hoffman        Expires October 15, 2020                [Page 2]

Internet-Draft               WG GitHub Admin                  April 2020


   The steps may be done manually by the IETF Secretariat or they may be
   automated.  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 unspecified, since these are
   implementation details that the IETF Secretariat and Tools Team will
   address.

   Most of the conventions below are drawn from
   [I-D.ietf-git-using-github].

2.1.  Creation of GitHub Organizations

   This document specifies 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-wg-<wgname>

   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.

   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




Cooper & Hoffman        Expires October 15, 2020                [Page 3]

Internet-Draft               WG GitHub Admin                  April 2020


   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 changes, work the same
   way as for organizations that were created as specified herein.

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 be an ability in the Datatracker to specify that there were
   personnel changes.

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 the
   Secretariat and current ADs at the time of closing.  The organization
   summary and the repositories within the organization would be updated
   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

   There are many different scenarios and configurations where it might
   be useful to have automation or established administrative
   conventions for repositories within WG organizations, such as:

   o  Creating a new repository for an individual draft (at the
      discretion of the WG chair);

   o  Creating a new repository for an already-adopted working group
      draft;

   o  Migrating an existing document repository into the WG
      organization; and

   o  Creating a new repository that contains multiple drafts.

   As an incremental step, this document specifies that there be a
   facility in the Datatracker interface to allow an administrator of an



Cooper & Hoffman        Expires October 15, 2020                [Page 4]

Internet-Draft               WG GitHub Admin                  April 2020


   ietf-wg-<wgname> 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 a skeleton draft file, default CONTRIBUTING,
   LICENSE, and README files, and continuous integration support, in the
   vein of <https://github.com/martinthomson/i-d-template>.  Performing
   this step would automatically inform the IETF Secretariat that this
   repository should be backed up as described in Section 3.2.

2.6.  Listing Related Repositories

   The IETF Datatracker should allow users to add links to repositories
   (for GitHub and other repository services) on working group,
   document, and user pages.  At the time of this writing this feature
   was under development.

3.  Working Group Process

   [I-D.ietf-git-using-github] 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 specifies
   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.

   Some working groups choose to have more than one draft in a
   repository, particularly for drafts that are tightly linked with
   significant cross-references.  In such a case, the README for the
   repository needs to say that clearly so that a participant
   understands that changes might be made to multiple drafts at once.







Cooper & Hoffman        Expires October 15, 2020                [Page 5]

Internet-Draft               WG GitHub Admin                  April 2020


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.

   Working group GitHub content needs to also 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 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.  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 GitHub repositories.

   The steps in Section 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 IETF Secretariat
   back up additional repositories that are related to IETF working
   groups.

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.

   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

   This document has no IANA actions.

6.  Informative 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>.




Cooper & Hoffman        Expires October 15, 2020                [Page 6]

Internet-Draft               WG GitHub Admin                  April 2020


   [I-D.ietf-git-using-github]
              Thomson, M. and B. Stark, "Working Group GitHub Usage
              Guidance", draft-ietf-git-using-github-06 (work in
              progress), March 2020.

Authors' Addresses

   Alissa Cooper
   Cisco

   Email: alcoop@cisco.com


   Paul Hoffman
   ICANN

   Email: paul.hoffman@icann.org


































Cooper & Hoffman        Expires October 15, 2020                [Page 7]