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

["Martin Thomson" <[e-mail]>]

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.

> Q5_1: Is there something GitHub specific with this section? To me it 
> 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/