Working Group GitHub Usage Guidance
draft-ietf-git-using-github-06

** I support Alvaro Retana’s DISCUSS position

** I philosophically agree with much of what Warren Kumari noted, and like Deborah Brungard and Adam Roach, I would have been more comfortable with an information document (given how the normative language was used).  However, the charter of the WG was to deliver a BCP and this document is it.

** I strongly concur with Mirja Kühlewind point #12, that we should be careful about guidance on when to publish the I-D.  For all of the virtues of using GitHub to reach new audiences, not all audiences will check there, so regular I-D updates when major changes are made is important.

Left unsaid for me from the feedback of my colleagues was:

** Section 10.  As there are no plans to formally backup anything beyond the repos and the mail, the mitigation of “[t]ools exist for extracting this information for backup” seems weak.  One of the real appeals of GitHub is that information/those services and their respective integrations.  Hence, what are those tools?  Who should take responsibility for that backup (if anyone)?  Why aren’t they being backed up?

Balloting closed for this document a while back, and so this is purely a symbolic act, but with the change from BCP to Informational, I'm changing my position from Abstain to No Objection.
I still don't love this document, but the authors and WG have carefully considered the questions raised, and made changes to address them. The status change addresses my largest source of discomfort and I'm signaling that with a (pointless) ballot position update...

--- 
Previous (2020-03-11) position:

I still don't love this, but I changed from DISCUSS to Abstain - https://github.com/ietf-gitwg/using-github/pull/46 , https://mailarchive.ietf.org/arch/msg/ietf-and-github/vnXiskU2VGIx8VenEP34GWGfOwM/

I recognize that my opinion does not trump WG / IETF consensus, so I'm holding my nose on this one. While I'm on this soapbox, I'd like to thank the authors for listening to, and trying to address my concerns.

I'm uncomfortable with much of this document:
1: This a BCP, and strongly implies that this is the "right" way for working groups to manage themselves and documents streams. The charter says: "Whether working groups choose to use GitHub or the documented policies to support their work will remain entirely at their discretion." - while the document does let WGs choose, the BCP track strongly implies that this is the "best" way. I happen to put documents that I author in git (hosted on GitHub), and use that to collaborate with my co-authors, but this is *our* choice, imposing our working process on others is a mistake - we have used the "as long at it can be turned into the canonical format we don't care how you make it" paradigm for a reason. If people create the XML in vim or emacs is, and should be entirely their decision - telling people that the "right" editor is vi is wrong - and a BCP does that... 

The charter also says: "The documents produced by this group will not alter the Internet Standards Process (BCP 9). They will describe how to work within it."
but the document sails very close to the wind in many places - e.g: "Working Group chairs MAY request a revision of an Internet-Draft being managed on Github at any time, in consultation with document editors." It has always been clear that chairs can request revisions to WG documents; this doesn't change it, but mentioning things like this simply muddies the water / makes more places for people to have to check. Section 7 is an example place where is is really dangerous - and I think comes close to trying to change BCP9.

2: The focus on GitHub makes my deeply uncomfortable -- I get the argument that it is the standard / best known hosted git provider (and, in my *opinion* the right one for us to use), but there are many places where term "GitHub" applies to "self hosted" solutions like GitLab / Gitea / etc. This feels very close to the IETF recommending that WG participants sign the blue-sheets with a Bic pen when all we need is some sort of writing implement. Just as one example: "GitHub facilitates more involved interactions,..." this is true of gitea, gitlab, bitbucket and many other tools -- calling out GitHub gives one tool prominence and is not appropriate for the IETF to do.

3: We require that all decisions be made on mailing lists - when people happen to use GitHub to collaborate on documents and happen to use the issue tracker to track issues, it is clear that this is just for their personal convenience -- having WG "owned" repos *will* lead to instances where decisions get made in the issue tracker, and not communicated tp the mailing list - this will end up with two classes of users: those that keep checking the issue tracker, and those that follow the mailing list and are surprised by the decisions made.

4: git (and GitHub) has a really steep learning curve - if a WG decides to fully jump in and start using GitHub, this (either explicitly or implicitly) disenfranchises people who don't use or want to use git. 

5: Moving state (primarily issues) from a personal repo to a WG one when a document is adopted is non-trivial -- "You can only transfer issues between repositories owned by the same user or organization account. You can't transfer an issue from a private repository to a public repository." and they have to be (AFAIK), moved individually - this will likely lead to loss of state (I may also have missed it, but I don't see anywhere in the document that talks about migrating a document / repo from an individual to a WG hosted version, and what should happen). I have a document which moved from hosted at www.github.com/wkumari/<document name> to www.github.com/capport-wg/<document-name> - this involved administrative annoyance, loss of state, and annoyance - for no benefit that I could see. I think a much much better approach would be have people simple keep the documents in their personal repos and not have the disruption that moving the repo entails. 

Don't get me wrong - I like git, and a: host my own gitea instance, b: maintain a few gitlabs and gogs instances, and c: put all of my drafts in GitHub - but I really don't think that the IETF should be implying that this is the "one true way" (BCP) (nor do I like the WG hosted model).

Thanks for the work that went into this document. While I don't feel very strongly about it, I tend to agree with the voices arguing for recharacterizing this document as Informational. I will leave it to the sponsoring AD to handle this issue as she sees fit.

Section 1.2:

   GitHub is a service operated at https://github.com/
   (https://github.com/).

The parenthetical seems unnecessary.

   GitHub is freely accessible on the open Internet,
   albeit currently only via IPv4.

One sincerely hopes that this second clause will age badly. Perhaps qualify it with “at the time this document is published.” Alternately, remove the clause, as it adds virtually nothing to the document.

Section 1.5:
   The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are
   used in this document.  It's not shouting; when they are capitalized,
   they have the special meaning defined in BCP 14 [RFC2119] [RFC8174].

Please use the boilerplate from RFC 8174.

Section 3.2:
   Repositories for private documents MAY
   be kept private, but only where there is a specific reason for doing
   so.

This seems really odd, completely undetectable/unenforceable, and actually harmful. It is common practice for editors to just keep their source local and only submit the output of such source to the i-d repository; and that’s just fine. This seems to say that such users are effectively forbidden to have their source equally private but also effectively backed-up and revision-controlled by one specific online service. It seems strictly better to allow and even encourage this, to prevent a loss of data.

I support Alvaro's Discuss.

In the vein of other comments, are we providing "best practices"
(Abstract) or "guidelines" (Introduction")?

Section 1

   Although similar, guidance for IRTF Research Groups is out of scope
   for this document.  However, such groups may draw inspiration for
   GitHub use from the contents herein.

The guidance is similar or the groups are similar?

Section 1.2

   There are a large number of projects at GitHub and a very large
   community of contributors.  One way in which some IETF Working Groups
   have benefited is through increased numbers of reviews and associated
   issues, along with other improvements that come from broader

Benefited, I presume, from their use of github?

Section 2.1

   Organizations are a way of forming groups of contributors on GitHub.
   Each Working Group SHOULD create a new organization for the Working
   Group.  A Working Group organization SHOULD be named consistently so
   that it can be found.  For instance, the name could be ietf-
   wg-<wgname>, as recommended in [GH-CONFIG].

I'm not sure I understand why the recommended value for consistency is
given in the Informational document as opposed to the BCP.

   A single organization SHOULD NOT be used for all IETF activity, or
   all activity within an area.  Large organizations create too much
   overhead for general management tasks, particularly when there is a
   need to maintain membership.

Is this a membership list or membership that's synchronized with
something else, or ...?

   Each organization requires owners.  The owner team for a Working

nit(?): maybe "github's procedures require that each organization has
owners"?

   Each organization requires owners.  The owner team for a Working
   Group repository MUST include responsible Area Directors.  Area
   Directors MAY also designate a delegate that becomes an owner and
   Working Group chairs MAY also be owners.

   A team with administrator access SHOULD be created for the Working

We seem to have introduced the github concept of "team" in passing here;
a more prominent note might be helpful.

Section 2.2

   A simple example of how to do this is to include a link to the GitHub
   organization on the WG Charter page in the datatracker.  Similarly,
   if there are multiple mailing list options, links to those mailing
   lists should be given.

Multiple mailing lists would be, e.g., to get different volume of
notifications from github?  I don't think we've introduced any mention
of "there are mailing lists other than the main WG list" yet.

   Repositories MUST include a copy or reference to the policy that

nit: "copy of"

   applies to managing any documents they contain.  Updating the README
   or CONTRIBUTING file in the repository with details of the process

It's slightly surprising to see the non-.md version of these files
mentioned, but I don't have any reason why it specifically matters.

   that new contributors need.  The README SHOULD contain a link to the
   CONTRIBUTING file.

Should/can the README contain anything else?

Section 3

   Chairs MUST involve Area Directors in any decision to use GitHub for
   anything more than managing drafts.

I think I saw another comment about this bit (but probably not all the
replies); it seems like the intent is more along the lines of "issue
tracker" type things than "slides for WG sessions", so clarification is
in order.

Section 3.1

   Working Group policies need to be set with the goal of improving
   transparency, participation, and ultimately the quality of the
   consensus behind documents.  At times, it might be appropriate to

Is there an example of how the policies might affect quality of
consensus.  (Also, does "quality of the documents" or even "quality of
the protocol being documented" not matter?)

Section 3.4

   In addition to the canonical XML format [RFC7991], document editors

[I'll channel Julian Reschke and note that RFC 7991 does not describe
the exact XML vocabulary used for the canonical RFC output...]

Section 4.1.1

   If labels are a core part of Working Group process, chairs MUST
   communicate any process to the Working Group.  This includes the

(We already said that chairs have to communicate the process to the WG,
regardless of whether issues are a core part of it or not.)

Section 5.2

   In addition to managing documents, the Working Group might choose to
   use GitHub for tracking outstanding issues.  In this mode of
   interaction, all substantive technical discussions are tracked as
   issues in the issue tracker.  However, discussion of any substantial

Is it the discussions themselves that are tracked, or the existence of
the topic being discussed?

Section 5.3

   Decisions about Working Group consensus MUST always be confirmed
   using the Working Group mailing list.  However, depending on the
   maturity of documents, this might be a more lightweight interaction,
   such as sending an email confirmation for a set of resolutions made
   using GitHub.

Perhaps "an initial set of resolutions arrived at by the GitHub
participants"?

Section 5.3.1

   review.  Finally, process checkpoints like Working Group Last Call
   (WGLC; Section 7.4 of [RFC2418]) provides additional safeguards
   against abuse.

This section is "Early Design Phases"; would a document move directly
from "early design phase" to WGLC without some other intermediate step
which would allow for detection of such abuse?  (In light of the
following paragraph perhaps the best approach is to change the name used
to describe this phase.)

Section 5.4

   Working Groups or editors might use additional labels as they choose.
   Any label that is used as part of a process requires that the process
   be documented and announced by Working Group chairs.  Editors SHOULD
   be permitted to use labels to manage issues without any formal
   process significance being attached to those issues.

Is there some conflict between "WG chairs must document and announce
process" and "editors are permitted to use labels without any formal
process significance"?  I'm not really sure I understand what this is
trying to say.

Section 6

   This creates a stable snapshot and makes the content of the in-
   progress document available to a wider audience.  Documents submitted

Is "wider audience" code for "the traditional IETF mode of work"?  Stuff
on github seems ... pretty available, as does the I-D archive; it's hard
to have much confidence in a claim that one has a "wider audience" than
the other.

Section 7

   If permitted, GitHub will be used for technical discussion and
   decisions, especially during early stages of development of a
   document.  Any decisions are ultimately confirmed through review, and
   ultimately, through Working Group Last Call (see Section 7.4 of
   [RFC2418]).

I'm not sure I understand what is meant by "review".

Section 10

I agree with Roman that it's surprising to mention that tools for
backing up "other information" exist but not make any recommendation for
their usage.

We could perhaps mention the potential consequences due to
authentication breach at github (minimal, due to distributed backups and
the I-D archive).

I support Alvaro and Barry's (and Warren's) comments on the overuse of normative language. I think if it was softened, it would help to put this document in the perspective of a best practice IF a group wants to use it for a specific document. But I also don't think this needs to be a BCP, I think it can be combined with the other document as informational. I understand there has been a lot of discussion and will not object.

Hi,

I share most of the concerns raised by my co-ADs.

What I'd really like to see is some clarifications added such that it is clear that these recommandations are not for all IETF WGs.
There is a sentence which aims at stating that:
   The requirements here apply to the case where Working Groups decide
   to use GitHub as a primary means of interaction.
But in fact before that one can also read:
   The intent is to allow each Working Group ...
and after that:
   Each Working Group SHOULD create ...
   Each Working Group MAY ...
plus many occurrences of "Working Groups" (plural).

To resolve the ambiguity may be you could do:
   The intent is to allow a Working Group considerable flexibility in how it uses GitHub.
   The Working Group SHOULD create its own new organisation.
   The Working Group MAY ...

And/or maybe reinforce the first sentence by clarifying that, in the rest of the document, "Working Groups" refer to working groups which have decided to use GitHub.

-m

Thanks for this well-written and helpful document. I have a couple of issue below that touch on the use of normative language and relation to RFC2418 (as well as maybe RFC2026). I guess those could qualify as discuss but I leave them as comments for now trusting in the editors and AD to address them appropriately.

One general comment:
I don't really understand the relationship between this document and draft-ietf-git-github-wg-configuration. There is a lot of direct overlap especially in section 2 but also in other sections. I understand that this document is BCP and such more appropriate to specify practices normatively but I don't really see why draft-ietf-git-github-wg-configuration is still needed then. The only part that is left to draft-ietf-git-github-wg-configuration are ideas about how things could be integrated in the datatracker and with the secretariat. As I say in my discuss ballot for that draft, it is not clear to my why we need an RFC for that at this point of time. If no decision is made yet, this could have also just be integrated e.g. into the appendix on this draft (or even partially in the security considerations section).

Other comments/questions:

1) Sec 3.2
"...or they might create repositories for individual documents on request."
I made a similar comment in my ballot for draft-ietf-git-github-wg-configuration. I think creating repos for individuals document is maybe not always the best option. I assume the intention here to not out-rule any cases where this might be okay (e.g. if a document is expectd to be adopted soon), however, I would rather prefer to see a recommendation to usually not do that as there can be many individual drafts in the groups and it can provide a wrong signal if repos are created for some and not others.

2) Sec 4.1.3:
"   Issues that have reached a resolution that has Working Group
   consensus MUST NOT be reopened unless new information is presented."
I do understand the intention here as it is important to make process, however, inline with the rest of the document and the general idea that practises can vary from group to group, I think this really should be a SHOULD NOT only.

Also further
"Resolved issues MUST remain
   closed unless there is consensus to reopen an issue."
I find this actually a bit strange because it should also then say something like "Resolved issues MUST only be closed with wg consensus"... I guess the word "resolved" is important here but why would you re-open an issue at all if it is resolved? I guess the case is that the wg figures that the issue is not resolved yet. Is the recommendation here for a wg participant to open a new issue if he/she thinks an issue is not fully resolved yet (rather than just re-open)? If so, you should say that.

3) Sec 4.2:
"   Editors SHOULD make pull requests for all substantial changes rather
   than committing directly to the "master" branch of the repository."
I think this does not align well with how we work today (without GitHub). E.g. if a group decides to use GitHub to better track changes and maybe easily integrate editorial comments, but decide to have all discussion on the mailing list (and not use github issues), I think it would be fully okay for the editors just commit directly based on the consensus on the mailing list. So I think the important part is that substantial comments should only be committed with wg consensus and therefore it is a good practice to have pull requests first to declare consensus based on the concrete proposed edits. However, if a different way to declare consensus is used that's fine as well. In short, I think the SHOULD is to string here for the general case.

4) Sec 5.3 (mostly editorial):
"It is possible to use
   different processes for different documents in the Working Group.

   Working Group chairs SHOULD confirm that the Working Group has
   consensus to adopt any process.  In particular, the introduction of a
   more tightly-controlled process can have the effect of privileging
   positions already captured in documents, which might disadvantage
   alternative viewpoints."
This text seems to apply more general to all content in section 5 and should maybe be moved out of section 5.3. Similarly I'm not sure if section 5.3.1 and 5.3.2 should actually be subsection of 5.3. The question of which issue to track seem rather orthogonal to the question who resolves the issue (I agree that this discussion does not make sense when no issue are tracked like in sec 5.1 but it could make sense for the mode in section 5.2)

5) Sec 5.3.1:
"The risk is that
   design changes might not always reflect the consensus of the Working
   Group."
I know that happens, even without GitHub, but should ideally not be the case. However, I think the root cause is rather that changes were incorrectly not identified by the editors as requiring consensus. Maybe this can be reworded accordingly to not give the impression that it is okay to implement design changes in a working group without consensus. Actually this is a broader problem (independent of GitHub) because some editors, especially when they also have been the authors of the individual draft, often implement design changes first in a new version and then ask the working group for consensus. As I said that's a different issue but it could be good to mention that GitHub and the use of PRs can actually help to not use this practice but always each consensus first.

6) Sec 5.3.1:
"... it is likely appropriate to move
   to a more tightly controlled process."
Maybe add something like "e.g. potentially during or after after working group last call". I think in many groups (that do not use GitHub) it is very common practice that editors have full control about the document. I mean I guess that's their role. I think GitHub really can help to make the process more transparent but it should not be a requirement. Especially shorter documents that had have good consensus form the beginning, there might necessarily be a need to every change that process. (I would say QUIC is rather the other extreme.)

7) Sec 5.3.2:
"   Chairs might choose to manage the process of deciding which issues
   are substantive.  For instance, chairs might reserve the ability to
   use the "design" label to new issues (see Section 5.4.1) and to close
   issues marked as "design".  Chairs should always allow document
   editors to identify and address editorial issues as they see fit."
I guess you could also use normative language here: "MAY choose to" and "Chairs SHOULD always allow"

8) Sec 5.3.2:
"   As documents mature further, explicit confirmation of technical
   decisions with the Working Group mailing list becomes more important."
Not sure I agree here. I know what you mean but explicit confirmation on the mailing list is always important. Maybe there is a way to rephrase that (or just remove that sentence...?)

9) Sec 5.3.2:
"   Gaining Working Group consensus about the resolution of issues can be
   done in the abstract, with editors being permitted to capture the
   outcome of discussions as they see fit."
I'm actually not sure what you mean here. Can you clarify?

10) Sec 5.3.2:
"   WGLC SHOULD be proposed as pull requests, and MUST be discussed on
   the mailing list, and MUST have chairs explicitly confirm consensus."
I agree with the "MUST be discussed on the mailing list" (as this is inline with RFC2418 e.g. 3.2 but therefore doesn't necessarily need to be normative in this doc) but find the other two SHOULD and MUST too strict. I don't think this is aligned with the process we have today in groups and we should not use this document to make the process more strict than it is. Especially I'm not sure what "chairs MUST explicitly confirm consensus" really means and it seems to be a requirement independent of GitHub and therefore eventually would even update RFC2481.

11) Sec 5.4.4:
It might be too late for this kind of input, however, as I review the document I'll note it here anyway. In taps we also have a "discuss" label to mark issue that has been discussed but need further discussion e.g. at an (interim) meeting. For this, one could even create a milestone to indicate at which meeting more discussion should take place (or when e.g. a document is text-ready until when text should be provided). We/the editors also did this for a while in taps.

12) Section 6 seems to encourage revision only in preparation for meetings. I'm not sure if that is inline with our usual working practice. I mean yes in reality we see the draft submission deadline as forcing function for updates and there want to keep it but we also do encourage to rev documents more often and work continuously, e.g. when a mayor change was implemented or a mayor issue resolved. And yes this works probably better for smaller documents but the section seems a bit contradicting to this practice. I mean the reason that we see many updates just at the draft deadline is because editors assign time to make updates to resolve issue to match the deadline. If editors make continuous changes we should encourage to update more often. Maybe it could rather say something like: "Revisions SHOULD be submitted as I-Ds when a signification issue has been resolved. Editors MAY bundle multiple changes in one revision if updates are done in timely close coherence and SHOULD update at least two weeks before any meeting." However, some of this advise is actually not GitHub specific and might again just touch our general guidelines and as such update RFC2026 and RFC2418...

13) sec 7:
"   Chairs MUST consider input from all discussion venues when assessing
   consensus including GitHub, mailing lists, interim meetings, and IETF
   meetings."
This seems like an update to RFC2481 again... as maybe also some other notes in this section.

Update: Thanks for replying and considering the TSV-ART review (thanks David for the review!). I don't consider the points raised there as transport-related and leave it to reviewer and editors to further discuss if needed.

Thanks for writing up this document. I believe it provides good advice for WG chairs to use github in their workflow. I also have concerns about centralization and the lack of IPv6, but I also see the other side of the argument that the community (specifically the non-IETF collaborators) is what makes github more useful than self-hosting or other alternatives. Pretty much everything I wanted to comment has been brought up by my co-ADs and hence I am content to watch their resolutions. There is only one thing I would like to propose. In Section 6 regarding I-D publication it would be good if there is a recommendation (for chairs/editors) to summarize the issues addressed by the revision especially for the benefit of the WG participants who don't use github.