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

[Ballot comment]
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/ to www.github.com/capport-wg/ - 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).

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up. Changes are expected over time.

This version is dated 1 November 2019.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

Informational, as indicated in the title page header. This is appropriate because the document discusses known good practices for using GitHub to aid IETF working group and document development.

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

This document describes best practices for Working Groups that use GitHub for their work including, for example: guidelines for deciding when and how to use GitHub in working groups, methods for contributing to IETF documents using GitHub, and working group policies for managing document development on GitHub.

Working Group Summary:

This document collates experience from multiple IETF members with varying levels of experience and expertise with GitHub. As such, it encapsulates knowledge relevant to a wide audience in the IETF. No content has been flagged as particularly controversial (yet).

Document Quality:

The document is well written and easy to read.

Personnel:

Christopher A. Wood is the Document Shepherd. Alissa Cooper is the Responsible Area Director.

(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

The document was reviewed in total alongside archived WG correspondence relating to this document. This version of the document is ready for publication.

(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No.

(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

No.

(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

None.

(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

Yes.

(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No.

(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

This document has strong WG consensus. It received (positive) reviews from multiple individuals with different WG backgrounds. As a whole, the WG understands and agrees with the document's contents.

(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No.

(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

There are no nits.

(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A.

(13) Have all references within this document been identified as either normative or informative?

Yes.

(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

No. The corresponding document (draft-ietf-git-github-wg-configuration) will advance in tandem with this document.

(15) Are there downward normative references references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

There is one downward normative reference to the companion document draft-ietf-git-github-wg-configuration.

(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

No.

(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

N/A.

(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

N/A.

(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

N/A.

(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

N/A.

[Ballot comment]
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.

[Ballot comment]
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

[Ballot comment]
(Updated, see comments from Francesca below)
I am agreeing with many issues raised by Mirja.

**********************************************************************
* Note, that I am conducting an experiment when people aspiring to be*
* Area Directors get exposed to AD work ("AD shadowing experiment"). *
* As a part of this experiment they get to review documents on IESG  *
* telechats according to IESG Discuss criteria document and their    *
* comments get relayed pretty much verbatim to relevant editors/WGs. *
* As an AD I retain responsibility in defending their position when  *
* I agree with it.                                                  *
* Recipients of these reviews are encouraged to reply to me directly *
* about perceived successes or failures of this experiment.          *
**********************************************************************

The following comments were provided by Francesca Palombini .
My comments are marked with [[Alexey:]] below.

Francesca would have balloted *YES* on this document. She wrote:

Comment:

I see the value of the document stating: "if you use GitHub, this is the best practice, if you want to follow it." The document motivates covering GitHub by stating that it has "a very large community of contributors". I still think some additional considerations should be there about using other services, possibly having IETF hosting a git server, even by saying "it is out of scope of this document" (implying it might be covered by a different BCP?).

Section 4.1 "When deciding to use GitHub..."
I'd like a sentence saying that WG chairs SHOULD evaluate over time and MAY change these policies based on the WG experience. I do think what described in this document is very valuable, but let's not forget that each WG is different and might need to make tweaks on the way, to get the best out of it. -- Just reached Section 5 where this is stated. Still think it would be good to have it in Section 4.1 as well.

[Ballot comment]
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-, 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).

[Ballot comment]
** 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?

[Ballot comment]
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.

[Ballot comment]
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/ to www.github.com/capport-wg/ - 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).

[Ballot comment]
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.

[Ballot comment]
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 vs. a mandate to use.

[Ballot discuss]
This is a process DISCUSS.  I don't believe the status of this document as a BCP belonging to BCP 25 was discussed in the WG or with the IETF community.

The Charter for the git WG only explicitly mentions BCP 9:

  The documents produced by this group will not alter the Internet Standards
  Process (BCP 9). They will describe how to work within it. Whether working
  groups choose to use GitHub or the documented policies to support their work
  will remain entirely at their discretion.


However, including this document as a part of BCP 25 (IETF Working Group Guidelines and Procedures) results in the interpretation that it represents consensus on how WGs should proceed -- and not that the decision "to use GitHub or the documented policies...[is]...entirely at their discretion."

My reading of the mailing list is that the current RFC Editor note (in which appending the document to BCP 25 is requested) was added only after the topic was brought up in the Genart LC review.  [Did I miss the discussion?]

IOW, both (1) the process of reaching the conclusion that this document belongs in BCP 25, and (2) the concept that this document would be part of BCP 25, are the subject of my DISCUSS.    I would like for the IESG to discuss this topic. 

Not expecting this document to be part of BCP 25, or having an explicit discussion with the community about it, would lead me to clear my DISCUSS.


====
[Non blocking comment.  I'm including it here because it is related to the status of the document.]

This document would be very good Informational document.

I am not a regular GitHub user (and none of the WGs I'm responsible for use it as part of their process), but I have no reason to doubt that the text represents what is believed to be the best way to use GitHub within the IETF process.  However, the designation as a BCP can create confusion.  [Again, this is a non-blocking comment.]

[Ballot discuss]
This is a process DISCUSS.  I don't believe the status of this document as a BCP belonging to BCP 25 was discussed in the WG or with the IETF community.

The Charter for the git WG only explicitly mentions BCP 9:

  The documents produced by this group will not alter the Internet Standards
  Process (BCP 9). They will describe how to work within it. Whether working
  groups choose to use GitHub or the documented policies to support their work
  will remain entirely at their discretion.


However, including this document as a part of BCP 25 (IETF Working Group Guidelines and Procedures) results in the interpretation that it represents consensus on how WGs should proceed -- and not that the decision "to use GitHub or the documented policies...[is]...entirely at their discretion."

My reading of the mailing list is that the current RFC Editor note (in which appending the document to BCP 25 is requested) was added only after the topic was brought up in the Genart LC review.

IOW, both (1) the process of reaching the conclusion that this document belongs in BCP 25, and (2) the concept that this document would be part of BCP 25, are the subject of my DISCUSS.    I would like for the IESG to discuss this topic. 

Not expecting this document to be part of BCP 25, or having an explicit discussion with the community about it, would lead me to clear my DISCUSS.


====
[Non blocking comment.  I'm including it here because it is related to the status of the document.]

This document would be very good Informational document.

I am not a regular GitHub user (and none of the WGs I'm responsible for use it as part of their process), but I have no reason to doubt that the text represents what is believed to be the best way to use GitHub within the IETF process.  However, the designation as a BCP can create confusion.  [Again, this is a non-blocking comment.]

[Ballot comment]

(0) I share Warren's concerns.


(1) The datatracker should list draft-thomson-git-using-github as being replaced by this document.


(2) It would be nice to have a short terminology section; I assume many people reading this document will not already be GitHub-savy, so push, pull, commits, may not be familiar to them.  Alternatively, an Informational pointer to a tutorial would also be ok.


(3) Personally, I don't have an issue with the use of GitHub, but some of the statements in the Introduction sound like marketing blurbs, for example:

- "Use of this service has been found to reduce the time that Working Groups
  need to produce documents and to improve the quality of the final result."

- "...encourage contributions from a larger set of contributors."

- "Using GitHub can also broaden the community of contributors for a
  specification."


(4) [nit] s/This is problematic for contributors who do not track discussion closely./This is problematic for contributors who do not track discussions closely.


(5) [major]  §5.3: "Working Group chairs SHOULD confirm that the Working Group has consensus to adopt any process."  When would the chairs not confirm consensus to adopt a process?  IOW, why is this not a MUST?

Note that §3 says this:

  Working Group Chairs are responsible for determining how to best
  accomplish the charter objectives in an open and transparent fashion.
  The Working Group Chairs are responsible for determining if there is
  interest in using GitHub and making a consensus call to determine if
  the proposed policy and use is acceptable.

Even though this text doesn't use rfc2119 keywords, my impression of the intent is that it is required for the chairs to make the consensus call.  IOW, I think that this text and the one above (from §5.3) are in conflict.


(6) §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.

This sentence doesn't sound right to me: "consensus...can be done in the abstract, with editors being permitted to capture the outcome...as they see fit".  That last part doesn't sound right: Chairs call consensus.  Maybe I'm misinterpreting...


(7) [major]. Why is draft-ietf-git-github-wg-configuration listed as a Normative Reference?  I don't think that dependency is needed.

[Ballot discuss]
I originally balloted Abstain, but this is (and has been) bothering me enough that I'm changing it to a discuss.

This feels like additional centralization / control / process, without good justification. I happen to use GitHub for my documents (along with discussion / agreement with co-authors), but in personal repos. Our documents include something like:
"[ This document is being collaborated on in Github at https://github.com/wkumari/.  The most recent  version of the document, open issues, and so on should all be available there.  The authors gratefully accept pull requests. ]"

This document contains a lot of text about setting up, administering, etc a WG organization / repos -- but there is no good justification (that I could find) on what advantages this has over simply encouraging people use GitHub (because it is easy, and well known), and keeping things in their own repos. If WG documents include a pointer (like above) to the repo, everyone can find it, and we don't need all this.
This smacks of scope-creep / chairs having control and process where it a: isn't needed and b: isn't helpful.

[Ballot comment]
I spent a while trying to decide between Abstain and DISCUSS.

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/ to www.github.com/capport-wg/ - 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).

[Ballot comment]
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.

[Ballot comment]
Martin has an update in the works, under review by the WG, which resolves my former DISCUSS and my comments, all below.  Thanks!

Reminder: include a note that this document will be added to BCP 25.

— Section 1.2 —

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

Why mention v4 only?  Does such mention have archival value once github supports v6?

  GitHub provides a simplified and integrated interface to not only
  git, but also provides basic user management, an issue tracker,

This doesn’t really work as written; I suggest this:

NEW
  GitHub provides a simplified and integrated interface to
  git, and also provides basic user management, an issue tracker,
END

  along with other improvements that come from broader
  participation by facilitating those in the community to participate.

Participation/participate feels odd.  Maybe, “along with other improvements that come from facilitating participation by a broader community.” ?

— Section 1.5 —
Please use the boilerplate directly from 8174: it was debated and worded as it is intentionally.  (That said, this is not a blocking comment.)

— Section 3 —

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

I’m not objecting to this, but... why?  If the WGCs may decide to use github for drafts without involving the ADs, why can’t they also decide to use it for charter revisions, agendas, and minutes without involving the ADs?

— Section 4.1.3 —

  Chairs need to assess whether the
  arguments offered represent new information or not.  This can require
  some discussion to determine accurately.  Resolved issues MUST remain
  closed unless there is consensus to reopen an issue.

There seems to be an inconsistency here: WGCs decide whether new information has been given, so it would seem that it’s the WGCs who decide that an issue should be reopened.  But then we say there has to be consensus for it.  In addition to that appearing inconsistent, I’m not clear how one would determine whether there’s rough consensus to reopen an issue, if doing so were controversial.

— Section 4.2 —

  Pull requests are the GitHub feature that allow users to request
  changes to a repository.

There’s a number agreement issue here (“feature” and “allow”).  I would fix this by making it all singular, so the sentence doesn’t sound strange:

NEW
  A pull request is a GitHub feature that allows a user to request
  a change to a repository.
END

— Section 4.2.1 —

  In addition to the features that pull requests share with issues,
  users can also review the changes in a pull request.  This is a
  valuable feature, but it has some issues.

You use “issues” here in two different senses; I suggest reserving the word for referring to github “issues”, and using a different word for “but it has some issues.”  Maybe, “but it presents some challenges.”

— Section 5.3.1 —

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

Number agreement: “Finally, process checkpoints, such as Working Group Last Call (WGLC; Section 7.4 of [RFC2418]), provide additional safeguards”.

— Section 6 —

  During the development of a document, individual revisions of a
  document can be built and formally submitted as an Internet-Draft.

Nit: two indefinite articles feels odd; I would make it, “individual revisions of the document”.

[Ballot comment]
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.

[Ballot comment]
I abstain with the meaning of "I oppose this document but understand that others differ and am not going to stand in the way of the others." per https://www.ietf.org/standards/process/iesg-ballots/ as the main issue (see below) cannot easily be fixed. I have also a couple of COMMENTs and I would appreciate an answer to those COMMENTs even if you can freely ignore my main ABSTAIN issue

Is there a reason why "GitHub" is used rather than simply "Git" or similar system ? At least, it is explicit to be the commercial web site "github.com". Alternatives such as GitLab and BitBucket are only briefly mentioned.

Section 1.3 has an amazing-to-my-eyes sentences "This document concentrates primarily on GitHub as it has a large and active community of contributors.  As a result, some content might not be applicable to other similar services.". In my opinion, if the same reasoning was applied to other topics, the Internet will become centralized into popular applications without innovation.
 
The document itself is clear, easy to read, and sensible except for the overlapping content with the companion document.

Finally, the reason for my ABSTAIN ballot is that I cannot accept that an IETF document in 2020 proposes to use an IPv4-only commercial web site (see also the IAB statement https://www.iab.org/2016/11/07/iab-statement-on-ipv6 ). Let's eat our own dog food. Why not having a git repo on the IETF servers?

-éric

PS: as a side note, I use daily the "git" tools sometimes for private use on github.com but for professional use on a corporate-run git server.

--- Start of COMMENT ---

General comment: it appears that the two 'git' documents have very similar content. Was it considered to better split them or merge them?

Section 3.2: a private repository is not free AFAIK with github.com. Which party will pay for those repos ?

--- End of COMMENT ---

[Ballot discuss]
I have a really simple thing to discuss before I move to a “yes” ballot:

— Section 4.1.3 —

  Chairs need to assess whether the
  arguments offered represent new information or not.  This can require
  some discussion to determine accurately.  Resolved issues MUST remain
  closed unless there is consensus to reopen an issue.

There seems to be an inconsistency here: WGCs decide whether new information has been given, so it would seem that it’s the WGCs who decide that an issue should be reopened.  But then we say there has to be consensus for it.  In addition to that appearing inconsistent, I’m not clear how one would determine whether there’s rough consensus to reopen an issue, if doing so were controversial.

[Ballot comment]
Idle question: Would it make sense for this document to formally update 2418?

— Section 1.2 —

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

Why mention v4 only?  Does such mention have archival value once github supports v6?

  GitHub provides a simplified and integrated interface to not only
  git, but also provides basic user management, an issue tracker,

This doesn’t really work as written; I suggest this:

NEW
  GitHub provides a simplified and integrated interface to
  git, and also provides basic user management, an issue tracker,
END

  along with other improvements that come from broader
  participation by facilitating those in the community to participate.

Participation/participate feels odd.  Maybe, “along with other improvements that come from facilitating participation by a broader community.” ?

— Section 1.5 —
Please use the boilerplate directly from 8174: it was debated and worded as it is intentionally.  (That said, this is not a blocking comment.)

— Section 3 —

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

I’m not objecting to this, but... why?  If the WGCs may decide to use github for drafts without involving the ADs, why can’t they also decide to use it for charter revisions, agendas, and minutes without involving the ADs?

— Section 4.2 —

  Pull requests are the GitHub feature that allow users to request
  changes to a repository.

There’s a number agreement issue here (“feature” and “allow”).  I would fix this by making it all singular, so the sentence doesn’t sound strange:

NEW
  A pull request is a GitHub feature that allows a user to request
  a change to a repository.
END

— Section 4.2.1 —

  In addition to the features that pull requests share with issues,
  users can also review the changes in a pull request.  This is a
  valuable feature, but it has some issues.

You use “issues” here in two different senses; I suggest reserving the word for referring to github “issues”, and using a different word for “but it has some issues.”  Maybe, “but it presents some challenges.”

— Section 5.3.1 —

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

Number agreement: “Finally, process checkpoints, such as Working Group Last Call (WGLC; Section 7.4 of [RFC2418]), provide additional safeguards”.

— Section 6 —

  During the development of a document, individual revisions of a
  document can be built and formally submitted as an Internet-Draft.

Nit: two indefinite articles feels odd; I would make it, “individual revisions of the document”.

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has reviewed draft-ietf-git-using-github-04, which is currently in Last Call, and has the following comments:

We understand that this document doesn't require any registry actions.

While it's often helpful for a document's IANA Considerations section to remain in place upon publication even if there are no actions, if the authors strongly prefer to remove it, we do not object.

If this assessment is not accurate, please respond as soon as possible.

Thank you,

Sabrina Tanamal
Senior IANA Services Specialist

The following Last Call announcement was sent out (ends 2020-03-03):

From: The IESG
To: IETF-Announce
CC: git-chairs@ietf.org, ietf-and-github@ietf.org, alissa@cooperw.in, Christopher Wood , draft-ietf-git-using-github@ietf.org, caw@heapingbits.net
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (Working Group GitHub Usage Guidance) to Best Current Practice


The IESG has received a request from the GitHub Integration and Tooling WG
(git) to consider the following document: - 'Working Group GitHub Usage
Guidance'
  as Best Current Practice

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2020-03-03. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This document describes best practices for Working Groups that use
  GitHub for their work.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-git-using-github/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-git-using-github/ballot/


No IPR declarations have been submitted directly on this I-D.


The document contains these normative downward references.
See RFC 3967 for additional information:
    draft-ietf-git-github-wg-configuration: Working Group GitHub Administration (None - IETF stream)

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up. Changes are expected over time.

This version is dated 1 November 2019.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

BCP, as indicated in the title page header. This is appropriate because the document describes best current practices for using GitHub to aid IETF working group and document development.

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

This document describes best practices for Working Groups that use GitHub for their work including, for example: guidelines for deciding when and how to use GitHub in working groups, methods for contributing to IETF documents using GitHub, and working group policies for managing document development on GitHub.

Working Group Summary:

This document collates experience from multiple IETF members with varying levels of experience and expertise with GitHub. As such, it encapsulates knowledge relevant to a wide audience in the IETF. No content has been flagged as particularly controversial (yet).

Document Quality:

The document is well written and easy to read.

Personnel:

Christopher A. Wood is the Document Shepherd. Alissa Cooper is the Responsible Area Director.

(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

The document was reviewed in total alongside archived WG correspondence relating to this document. This version of the document is ready for publication.

(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No.

(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

No.

(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

None.

(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

Yes.

(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No.

(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

This document has strong WG consensus. It received (positive) reviews from multiple individuals with different WG backgrounds. As a whole, the WG understands and agrees with the document's contents.

(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No.

(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

There are no nits.

(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A.

(13) Have all references within this document been identified as either normative or informative?

Yes.

(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

No. The corresponding document (draft-ietf-git-github-wg-configuration) will advance in tandem with this document.

(15) Are there downward normative references references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

There is one downward normative reference to the companion document draft-ietf-git-github-wg-configuration.

(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

No.

(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

N/A.

(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

N/A.

(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

N/A.

(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

N/A.

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up. Changes are expected over time.

This version is dated 1 November 2019.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

BCP, as indicated in the title page header. This is appropriate because the document describes best current practices for using GitHub to aid IETF working group and document development.

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

This document describes best practices for Working Groups that use GitHub for their work including, for example: guidelines for deciding when and how to use GitHub in working groups, methods for contributing to IETF documents using GitHub, and working group policies for managing document development on GitHub.

Working Group Summary:

This document collates experience from multiple IETF members with varying levels of experience and expertise with GitHub. As such, it encapsulates knowledge relevant to a wide audience in the IETF. No content has been flagged as particularly controversial (yet).

Document Quality:

The document is well written and easy to read.

Personnel:

Christopher A. Wood is the Document Shepherd. Alissa Cooper is the Responsible Area Director.

(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

The document was reviewed in total alongside archived WG correspondence relating to this document. This version of the document is ready for publication.

(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No.

(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

No.

(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

None.

(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

Yes.

(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No.

(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

This document has strong WG consensus. It received (positive) reviews from multiple individuals with different WG backgrounds. As a whole, the WG understands and agrees with the document's contents.

(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No.

(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

There are no nits.

(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A.

(13) Have all references within this document been identified as either normative or informative?

Yes.

(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

No. The corresponding document (draft-ietf-git-github-wg-configuration) will advance in tandem with this document.

(15) Are there downward normative references references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

There is one downward normative reference to the companion document draft-ietf-git-github-wg-configuration.

(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

No.

(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

N/A.

(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

N/A.

(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

N/A.

(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

N/A.