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

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 <rsalz@akamai.com> wrote:

> 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
>
>
>
> _______________________________________________
> Ietf-and-github mailing list
> Ietf-and-github@ietf.org
> https://www.ietf.org/mailman/listinfo/ietf-and-github
>