| Network Working Group | L. Eggert |
| Internet-Draft | NetApp |
| Intended status: Best Current Practice | February 02, 2017 |
| Expires: August 6, 2017 |
Using GitHub for IETF Working Groups
draft-eggert-github-bcp-latest
This document describes the best current practices on using the GitHub web service to support the operation of IETF Working Groups.
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 http://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 August 6, 2017.
Copyright (c) 2017 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 (http://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.
[blame Carsten Bormann for this subsection]
The CoRE WG (Constrained RESTful Environments) has been actively using the Trac/SVN combination offered by the Tools Team for its older drafts. Some newer drafts (including some drafts that are not yet WG drafts but could be considered candidates for that) are now being worked on in the core-wg github organization. These drafts generally use Martin Thomson’s template, except where the build process (examples, grammars) is much more complicated than can easily be supported by this template.
We try to keep discussion on the mailing list (as opposed to getting them entirely in the github issues), but may not have been very successful in that; it definitely requires constant vigilance.
The WG Wiki says:
We currently do not have an active backup regime; we would expect the IETF to come up with one that we can share.
As the contributors to CoRE are not necessarily deeply involved in software projects that already make use of github, moving work to github may create a sudden barrier of entry for some contributors at the same time as other contributors report that the work got much easier for them. Also, accidents do happen (such as committing versions of a text that suddenly have CRLF line endings), and some authors may not know how to fix them.
(There is a separate, chairs-only github organization for chair materials.)
(Add similar text for 6Lo, T2TRG, LWIG, CBOR, LPWAN…)
The QUIC WG was chartered in October 2016, and has been using GitHub very intensively.
We created a GitHub organization called “quicwg”, which the WG chairs administer. Under than organization, we set up two teams, one for WG document editors and one for regular contributors. Membership in the former team is contingent on being chosen as an editor for a WG deliverable. The latter team is more open, and consists of people that the chairs and editors want to assign reviews or issues to. Obviously, anyone can raise issues, comment on them, submit pull requests, etc. The benefit of the “contributors” team really lies in allowing the assignment of tasks to individuals, which is otherwise not possible.
Underneath the “quicwg” organization, we created two repositories, one for WG materials and one for our base WG drafts. Only the chairs have commit permissions to the WG materials repo, which is mostly used to hold presentations and other materials from our various meetings. This repo is configured to not allow issues to be raised or have a wiki (we instead store Markdown files inside the repo.)
Our second repo, for “base drafts”, is where most of the work occurs. The decision to use a common repo for several drafts was deliberate. QUIC is a complex protocol with a complex specification, text moves between different documents and issues can affect several. Maintaining each draft in a separate repo, while “cleaner” on first impression, actually complicates this workflow. When the WG adopts additional drafts, we will decide on a case-by-case basis whether they will be made part of the “base drafts” or if we create a new repo underneath the organization. Since Martin Thomson is an editor, we use his setup I-D template [ID-TEMPLATE] to rapidly publish HTML editor copies of the specs.
The “base drafts” repo is configured to allow issues to be raised, and its wiki is enabled (but rarely used.) Editors (and chairs) have commit rights to this repo.
We use sets of labels to tag issues that are raised. One set simply indicates which draft(s) an issue applies to, or whether it is potentially of broad “design” impact, or “editorial” in nature so that an editor can use his or her own discretion to resolve it without WG consensus. A second set is used to track the WG consensus on each issue (with states that currently include “needs-discussion”, “confirm-consensus”, “notify-consensus” and “editor-ready”). Issues progress from “needs-discussion” to either “confirm-consensus” or “notify-consensus”. The former is entered when consensus amongst the participants in the discussion has emerged, and the WG needs to confirm this consensus on the list. The latter is entered when a consensus call happened at a WG meeting, and the mailing list needs to confirm this consensus. (It is not clear if two separate labels actually make all that much sense here.) Once WG consensus has been established, an issue is labeled “editor-ready”.
Although the QUIC WG has only been chartered for a few months, we have already had ~250 issues raised, many of which have attracted dozens of comments. Good issue topics and actively searching for prior issues before opening new ones is essential to manage the workflow.
In order to allow WG participants to follow the activity on GitHub without needing to check the GitHub web site, we have set up a separate “quic-issues” mailing list at the IETF. It was a deliberate decision to use a list other than the regular WG mailing list. First, because we are intensively using GitHub, a lot of notifications get generated (dozens per day), which would drown out other list traffic, Second, the issues list is configured as a read-only list, where all incoming email is rejected, except for some whitelisted senders. The intent is to keep all discussion on the regular WG mailing list, or on GitHub tickets. (While GitHub will correctly reflect email replies to issue notifications, they seem to loose sender information, which is useless.)
Getting GitHub notifications to go to this list was mildly painful, and involved creating a dummy “IETF QUIC WG” GitHub user account, whose subscription email address is the quic-issues list address. The dummy user was made a member of the QUIC GitHub organization, and will therefore by default “track” all repo activity. This will cause GitHub to create the desired stream of notification emails to an IETF list. One caveat here is that GitHub uses the email address associated with the user who is interacting with the web site as the sender address of notification emails, which requires regular whitelisting in mailman. It also means that these users are allowed to otherwise email the issues list; we trust they don’t. This email integration is rather dissatisfyingly complex; we’d be interested to learn of a better way.
This document raises no security considerations.
This document has no IANA considerations.
Carsten Borman and Paul Hoffman have contributed text to this document.
Lars Eggert has received funding from the European Union’s Horizon 2020 research and innovation program 2014-2018 under grant agreement 644866 (“SSICLOPS”). This document reflects only the authors’ views and the European Commission is not responsible for any use that may be made of the information it contains.
This document is being prepared in a Github repository [REPO] using Martin Thomson’s I-D template [ID-TEMPLATE] and Carsten Bormann’s [KRAMDOWN-RFC2629].
| [ID-TEMPLATE] | Thomson, M., "martinthomson/i-d-template", n.d.. |
| [KRAMDOWN-RFC2629] | Bormann, C., "cabo/kramdown-rfc2629", n.d.. |
| [REPO] | Eggert, L., "larseggert/github-bcp", n.d.. |