Subject: [Ietf-and-github] Comments on draft-ietf-git-using-github-00

From: Christer Holmberg <[email-masked]>
Date: Sun, 4 Aug 2019 12:55:02 +0000

Hi,

I have read the draft, and I have some comments.

---

Section 1:

The text says:

    "This document describes how the IETF uses GitHub through the
   development of Internet-Drafts.  This concentrates on the work that
   occurs within IETF working groups.  Recommendations for working
   groups and their chairs are made for integrating these tools with
   their processes."

Q1_1: What is the meaning of this paragraph? The main purpose of the document is to give guidance when a WG decides to use GitHub, which is described in the following paragraph, and in Section 1.4.

---

Section 2:

Q2_1: Does this section (including sub sections) belong to this document? To me it seems like it belongs to draft-ietf-git-github-wg-configuration, and e.g., section 2.1 is very similar to section 2.1 of draft-ietf-git-github-wg-configuration-01.

---

Section 3:

The text says:

"Chairs SHOULD involve Area Directors any decision to use GitHub for anything more than managing of drafts."

Q3_1: I think the sentence belongs to Section 3.1.

Q3_2: What exactly does "managing of drafts" mean? If it means using GitHub for anything else than what is described in the draft, maybe it would be better to say so?

Q3_3: I also think that it would be good that the ADs are always informed about a WG using GitHub, and how it is used.

---

Section 3.2:

Q3-2_1: I think it shall be a MUST to provide the information on how the WG is going to use GitHub also in the repo (e.g., README/CONTRIBUTING). To me the text now only says it's a good idea.

---

Section 3.3:

Q3-3_1: Does this section belong in to draft-ietf-git-github-wg-configuration?

Q3-3_2: More generally, is there a need for draft-ietf-git-github-wg-configuration to begin with?

---

Section 3.5:

Q3-5_1: I think it would be useful to point out that the document format needs to be text based - at least if people are expected to provide pull requests.

Q3-5_2: I think it would be useful to point out that the WGs should choose a document format that the community can be considered being familiar with (unless the community agree on trying out something new). Also, in order to contribute, the document format should not mandate the installation of lots of software, and it should be possible to contribute on any major OS.

---

Section 4.1:

Q4-1_1: I suggest to rename the section to "Issue Tracker". "Issues" should be a section where it is described what to do, or whom to contact, if a WG has problems with using GitHub etc :)

Q4-1_2: Section 4.2 provides guidance on how pull requests are discussed, but there is nothing similar for Issues. There are two way to discuss Issues: in the Issue tracker, and on the list.

---

Section 4.1.1:

Q4-1-1_1: I think it would be useful to give examples of how labels have been used. Appendix A.2 describes how labels are used for the QUIC WG, so maybe adding a reference.

---

Section 4.2:

Q4-2_1: When a pull request is created, I think one should always provide some background data on what triggered the pull request. If there is a GitHub issue and/or email discussion associated with the pull request I think it would be good to include a link to the issue/email discussion. If there is a meeting discussion associated with the pull request I think it would be good to include a link to the minutes.

Q4-2_2: This question is not only related to pull requests, but to the usage of branches in general. Unless I've missed it, the document does not talk about usage of branches (apart from the ones used for pull requests). The text mentions the "master" branch. So, is the assumption that the work (pull requests etc) is always going to be done against the "master" branch? What if a WG wants to create a separate branch for each new version of a draft, submit all pull requests etc against that branch, and then merge that branch with the master once the new version of the draft has been submitted? That way the master branch would always reflect the latest version of the draft. I am not saying whether that is better or worse, but the document currently doesn't say anything about it. The document either needs to specify how branches are used, or specify that the WG chairs need to decide how branches are used within their WG.

---

Section 4.2.2:

Q4-2-2_1: I think it would be good to inform the community (using the WG mailing list) when a pull request is about to be merged - especially if it's related to a technical topic, and/or a topic that has triggered lots of discussions.

Q4-2-2_2: I agree with the statement saying that a merge does not always necessarily need to reflect WG consensus. However, I do think that it should be possible (e.g., using git tags) to find the revision that is associated with a given version of a draft.

---

Section 5:

Q5_1: Is there something GitHub specific with this section? To me it looks like normal IETF procedures.

The text says:

"Editors SHOULD create a new Internet-Draft submission two weeks prior to every session (see Section 7.1 of [RFC2418])."

Q5_2: This is not how I read 2418. It says that all information shall be available two weeks prior to every session. That may of course include submitting a new version of a draft, but that depends on whether there is anything new to submit.

Q5_3: In my opinion, this section should talk about the GitHub specifics on submitting a new version. For example, how/if a new version can be submitted if there are open Issues and/or pull requests.

Q5_4: As indicated in Q4-2-2_2, when a revision is used for a new draft version I think it should be properly marked/tagged.

Q5_5: When a new draft version is submitted, would it be useful to include links to all pull requests that have been merged for the new draft version? This makes it easier in future to look back when/why/if certain changes were doing.

----

Regards,

Christer

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 19 Aug 2019 17:24:30 +1000

Thanks for reviewing Christer, and apologies for taking so long to get back to this.

On Sun, Aug 4, 2019, at 22:55, Christer Holmberg wrote:
> Q1_1: What is the meaning of this paragraph? The main purpose of the 
> document is to give guidance when a WG decides to use GitHub, which is 
> described in the following paragraph, and in Section 1.4.

This paragraph is to explain the purpose of the document.  I've reworded in my copy slightly.

> Q2_1: Does this section (including sub sections) belong to this 
> document? To me it seems like it belongs to 
> draft-ietf-git-github-wg-configuration, and e.g., section 2.1 is very 
> similar to section 2.1 of draft-ietf-git-github-wg-configuration-01.

I've started the process of cutting this out.  There are probably still a few items in an ambiguous state between the two drafts, but we'll sort that out in time.

> Q3_3: I also think that it would be good that the ADs are always 
> informed about a WG using GitHub, and how it is used.

Yeah.

> Q3-2_1: I think it shall be a MUST to provide the information on how 
> the WG is going to use GitHub also in the repo (e.g., 
> README/CONTRIBUTING). To me the text now only says it’s a good idea.

Yep.

> Q3-3_1: Does this section belong in to draft-ietf-git-github-wg-configuration?

I don't think so.  Though it's not clear where the line between these docs will end up.

> Q3-3_2: More generally, is there a need for 
> draft-ietf-git-github-wg-configuration to begin with? 

It might be that that document never gets published.  It's a very targeted set of instructions that might not have value as something on permanent record.  Once we have tools in place, embedding practices in those tools is probably more valuable than in the RFC series.  But that's just my opinion.

> Q3-5_1: I think it would be useful to point out that the document 
> format needs to be text based – at least if people are expected to 
> provide pull requests.

Definitely.  I can't think of anything worse than having to deal with a pull request on a PDF.

> Q3-5_2: I think it would be useful to point out that the WGs should 
> choose a document format that the community can be considered being 
> familiar with (unless the community agree on trying out something new). 
> Also, in order to contribute, the document format should not mandate 
> the installation of lots of software, and it should be possible to 
> contribute on any major OS.

There's a host of things that might be said about accessibility here.  I've changed this to be a little more assertive about using markdown, but I don't want to over-rotate and prescribe something too closely.  A common format for content is probably sufficient.  And none of the tools we currently use have portability issues (even if installation on some platforms can leave a little to be desired).

> Q4-1_1: I suggest to rename the section to “Issue Tracker”. “Issues” 
> should be a section where it is described what to do, or whom to 
> contact, if a WG has problems with using GitHub etc :)

Done.

> Q4-1_2: Section 4.2 provides guidance on how pull requests are 
> discussed, but there is nothing similar for Issues. There are two way 
> to discuss Issues: in the Issue tracker, and on the list.

That's the subject of new material.   See https://github.com/ietf-gitwg/using-github/pull/15

> Q4-1-1_1: I think it would be useful to give examples of how labels 
> have been used. Appendix A.2 describes how labels are used for the QUIC 
> WG, so maybe adding a reference.

The above new work has more on that.

> Q4-2_1: When a pull request is created, I think one should always 
> provide some background data on what triggered the pull request. If 
> there is a GitHub issue and/or email discussion associated with the 
> pull request I think it would be good to include a link to the 
> issue/email discussion. If there is a meeting discussion associated 
> with the pull request I think it would be good to include a link to the 
> minutes.

Done.

> Q4-2_2: This question is not only related to pull requests, but to the 
> usage of branches in general. Unless I’ve missed it, the document does 
> not talk about usage of branches (apart from the ones used for pull 
> requests). The text mentions the “master” branch. So, is the assumption 
> that the work (pull requests etc) is always going to be done against 
> the “master” branch? What if a WG wants to create a separate branch for 
> each new version of a draft, submit all pull requests etc against that 
> branch, and then merge that branch with the master once the new version 
> of the draft has been submitted? That way the master branch would 
> always reflect the latest version of the draft. I am not saying whether 
> that is better or worse, but the document currently doesn’t say 
> anything about it. The document either needs to specify how branches 
> are used, or specify that the WG chairs need to decide how branches are 
> used within their WG.

I don't think that we need to make too many recommendations there.  I'd rather concentrate on the one branch and let people who want to do special things work out how to do that on their own.  I've added a disclaimer about that.

> Q4-2-2_1: I think it would be good to inform the community (using the 
> WG mailing list) when a pull request is about to be merged – especially 
> if it’s related to a technical topic, and/or a topic that has triggered 
> lots of discussions.

This is part of the new stuff (https://github.com/ietf-gitwg/using-github/pull/15) too.

> Q4-2-2_2: I agree with the statement saying that a merge does not 
> always necessarily need to reflect WG consensus. However, I do think 
> that it should be possible (e.g., using git tags) to find the revision 
> that is associated with a given version of a draft.

I've added that.  Thanks.

> looks like normal IETF procedures.

I've taken some of your suggestions, which means that it isn't really as bereft of useful information as before.

> Q5_5: When a new draft version is submitted, would it be useful to 
> include links to all pull requests that have been merged for the new 
> draft version? This makes it easier in future to look back when/why/if 
> certain changes were doing.

I didn't include this.  I think that policies about where to find change logs are a per-working group thing.  We meticulously build them for QUIC and it's annoying to do so, even if it's a valuable service editors provide.  Everyone will have to make their own call.

You can find updated drafts (and proposal text) here: https://ietf-gitwg.github.io/using-github/