Subject: Re: [Ietf-and-github] WGLC for draft-ietf-git-using-github

From: "Salz, Rich" <[email-masked]>
Date: Tue, 3 Dec 2019 18:56:13 +0000

Some comments I'd like to see addressed before existing WGLC.

I dislike the draft's use of the word "proven," and would prefer constructs like "demonstrably" or "shown to be" etc.  I could live with the others, but the use in the Introduction section really needs to be fixed.  I guess my dislike is that it could be taken by some as being needless confrontational, and we've already proven (heh) that this topic has some controversy.

The phrase "source control" in the Intro should be "version control"

 Near the end of page 3 (pagination in text format, sorry not sorry :) the phrase "avoid issues" should be "help WG chairs avoid issues" I think.

Sec 1.1 should explain why this is cool.  It allows several types of workflow to be used and changed. For example, authors collaborating, pushing changes to a WG repo, etc.

Sec 1.3 "bitbuckey *and* gitlab"

Sec 2.1, I prefer "ietf-wg-XXXX", top-down style, not intermixed.  Blue bikesheds rule. But it also follows the draft-ietf-<wg>- naming style.

Sec 3.1, Last sentence, about link from README to CONTRIBUTING. Should that be a SHOULD and written in active-voice?
At the end of 3.1, can you give an "anti-pattern" (we used to say counter-example I guess) of what would be something unfustifiably constraining?

Sec 3.2, "draft-ietf-<wg>-" should that be "draft-ietf-<wgname>-" ? I think using one term throughout is better.

Sec 3.3 "unless with prior..." reads better as "without prior" I think.

Sec 4.1.2 if restrictions on closing are changed, is this a change in policy that must be communicated and the WG agree to? Or is this something to include in the initial policy and if so, is there guidance in this document for that?

Sec 4.2  Should this mention that PR's can be updated by pushing new commits to the originating repo?  This lets PR's evolve in response to WG discussion.

Sec 4.3 "requires *email* server infrastructure" ?

Sec 5.2, near the end.  :communication about the work of the group from the *Working Group* mailing list." ?

Sec 5.4.1, flip the design and editorial pragraphs?  Matches the structure of increasing difficulty?  Not a big deal, freel free to ignore.

Sec 6, makes the document available "to a wider *IETF* audience" ?

Sec 7, top of page 19.  "If permitted" maybe mention "by the Working Group policy" ?  Fine if you think that's redundant.

Sec 8, "changes to a document" should be "repository" ? Add "These services are generally available at no cost" ?

Sec 9 uses "you" language. Should that change to "Editor" language? "Create a new issue for them"  And add a comment pointing to the issue and directing discussion there?

Sec 10.  Ha.

Sec 13.  Gh-config appears both normative and non-nomative

Sec A2 top of p	25  No "seem to lose" about it.  The lose sender info, which makes it useless.

Appendix B needs to add authors for A3 and A4

---

From: David Schinazi <[email-masked]>
Date: Tue, 3 Dec 2019 11:40:47 -0800

Thanks for writing this document. I think it's helpful and support
publication if one issue is resolved:
any chance the authors could rewrite section 10 with less sarcasm? I'm all
for humor but I think this
joke has served its purpose and doesn't necessarily need to land in the
published BCP.

Thanks,
David

On Tue, Dec 3, 2019 at 10:56 AM Salz, Rich <[email-masked]> wrote:

> I dislike the draft's use of the word "proven," and would prefer
> constructs like "demonstrably" or "shown to be" etc.  I could live with the
> others, but the use in the Introduction section really needs to be fixed.
> I guess my dislike is that it could be taken by some as being needless
> confrontational, and we've already proven (heh) that this topic has some
> controversy.
>
>  Near the end of page 3 (pagination in text format, sorry not sorry :) the
> phrase "avoid issues" should be "help WG chairs avoid issues" I think.
>
> Sec 1.1 should explain why this is cool.  It allows several types of
> workflow to be used and changed. For example, authors collaborating,
> pushing changes to a WG repo, etc.
>
> Sec 2.1, I prefer "ietf-wg-XXXX", top-down style, not intermixed.  Blue
> bikesheds rule. But it also follows the draft-ietf-<wg>- naming style.
>
> Sec 3.1, Last sentence, about link from README to CONTRIBUTING. Should
> that be a SHOULD and written in active-voice?
> At the end of 3.1, can you give an "anti-pattern" (we used to say
> counter-example I guess) of what would be something unfustifiably
> constraining?
>
> Sec 3.2, "draft-ietf-<wg>-" should that be "draft-ietf-<wgname>-" ? I
> think using one term throughout is better.
>
> Sec 4.1.2 if restrictions on closing are changed, is this a change in
> policy that must be communicated and the WG agree to? Or is this something
> to include in the initial policy and if so, is there guidance in this
> document for that?
>
> Sec 4.2  Should this mention that PR's can be updated by pushing new
> commits to the originating repo?  This lets PR's evolve in response to WG
> discussion.
>
> Sec 5.4.1, flip the design and editorial pragraphs?  Matches the structure
> of increasing difficulty?  Not a big deal, freel free to ignore.
>
> Sec 7, top of page 19.  "If permitted" maybe mention "by the Working Group
> policy" ?  Fine if you think that's redundant.
>
> Sec 8, "changes to a document" should be "repository" ? Add "These
> services are generally available at no cost" ?
>
> Sec 9 uses "you" language. Should that change to "Editor" language?
> "Create a new issue for them"  And add a comment pointing to the issue and
> directing discussion there?
>
> Sec 10.  Ha.
>
> _______________________________________________
> Ietf-and-github mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-and-github
>

---

From: "Martin Thomson" <[email-masked]>
Date: Wed, 04 Dec 2019 16:02:01 +1100

Thanks for the review Rich,

Your PR is https://github.com/ietf-gitwg/using-github/pull/34  I created https://github.com/ietf-gitwg/using-github/pull/33 to cover a separate item before I saw your email.

> counter-example I guess) of what would be something unfustifiably 

This was written in reaction to some recent attempts to constrain policies.  I've removed the more strongly worded bit.  The problem here is that there is a balance between giving editors some leeway and ensuring that the output of the process properly reflects consensus.  For instance, in QUIC, substantive changes now require chair involvement.  That is a real burden if you are at a stage in the process where there are many changes to make.   When that process was introduced, there were several occasions when chairs were not especially responsive for different reasons (illness, leave, other responsibilities) and that did result in problems.

For now, I think that it's enough to suggest that chairs and editors communicate about processes to ensure that they are working.

> policy that must be communicated and the WG agree to? Or is this 
> something to include in the initial policy and if so, is there guidance 
> in this document for that?

I think that falls under the "communicating policies" text.
 
> Sec 4.3 "requires *email* server infrastructure" ?

Not just email, if I understand how it works.

> Sec 6, makes the document available "to a wider *IETF* audience" ?

Yes, but also not IETF.

> Sec 8, Add "These services are generally available at no cost" ?

That doesn't seem relevant here.

> "Create a new issue for them"  And add a comment pointing to the issue 
> and directing discussion there?

I took the opportunity to revise this text.

> Sec A2 top of p	25  No "seem to lose" about it.  The lose sender info, 

Not entirely true.  It retains some of that information, but I agree, it's not ideal.

> Appendix B needs to add authors for A3 and A4

I'm going to ask about these sections separately.  I think that they might be able to go.

---

From: "Salz, Rich" <[email-masked]>
Date: Wed, 4 Dec 2019 15:56:29 +0000

I am fine with your responses and the PR, thanks for the consideration.

I approve this for WGLC.

---

From: "Christopher Wood" <[email-masked]>
Date: Mon, 16 Dec 2019 09:34:11 -0800

Thanks to all who read the document and resulting Pull Requests, provided feedback, and engaged in the process. The last call is is now complete.  As with the configuration draft, we'll merge the outstanding PRs, spin a new version, and then move the document onwards to the IESG. 

Best,
Chris

On Tue, Nov 19, 2019, at 1:18 AM, Christopher Wood wrote:
> This is the working group last call for draft-ietf-git-using-github 
> [1]. Due to upcoming holidays, it will run until December 13. Please 
> review the document and send your comments to the list by then.
> 
> Thanks,
> Chris, on behalf of the chairs
> 
> [1] https://datatracker.ietf.org/doc/draft-ietf-git-using-github/
>