Subject: [Ietf-and-github] AD evaluation of draft-ietf-git-using-github-03

From: Alissa Cooper <[email-masked]>
Date: Thu, 6 Feb 2020 15:53:10 -0500

I have reviewed draft-ietf-git-using-github-03 in preparation for IETF last call. The document is almost ready for LC. I have just a couple of substantive questions and suggestions to be answered before initiating the LC. I’ve also included some nits that should be resolved together with any last call comments.

=== Substantive comments ===

== General ==

Should there be some words in this document about how research groups might draw inspiration from this document, but that specific guidance for research groups is out of scope?

== Section 2.1 ==

draft-ietf-git-github-wg-configuration settled on the naming convention ietf-wg-<wgname> so this document needs to be updated to align with that.

== Section 4.2 ==

Do you want to say a few words about who determines what constitutes a "substantial" change (or add a forward reference to Section 5 and provide some uniform statement about it there)? For example, might some WGs determine that anything non-editorial is substantial (also discussed in 5.3.2)? Whose call would that be?

== Section 4.3 ==

Should we see if the secretariat can setup server infrastructure to support github-notify-ml for WGs that want it, and have a process whereby WGs can request support for it? This would imply changes to draft-ietf-git-github-wg-configuration rather than to this document, but I figured I would ask while I'm reviewing this.

== Section 10 ==

I'd like to suggest:

OLD
Maintaining a mirror of a repository that is hosted on GitHub is relatively simple and might be considered as a way to provide a backup for the primary repository.

NEW
Maintaining a mirror of a repository that is hosted on GitHub is relatively simple and is specified in [GH-CONFIG] to provide IETF-hosted backups for WG repositories.

== Nits ==

Section 1: Perhaps you should add a citation to www.github.com on first use of Github.

Section 1.1: Same comment as above, adding a citation for Git might be useful for completeness/posterity.

Section 1.4: s/does require/requires/

Section 3: s/accomplish the Charter/accomplish the charter objectives/

Section 3.1: s/Working Group Chairs that decide/Working Group Chairs who decide/

Section 3.4: You might want to clarify what you mean by text-based (some people might interpret it as documents being submitted in binary or something ... better to be clear)

Section 4.1.2: "Restrictions on closing issues are generally not advisable until a document has reached a certain degree of maturity." This is a little vague. Perhaps you mean "Restrictions on who can close an issue"?

Section 4.2: s/how they manage changes./how they manage changes amongst themselves./

Section 6: s/MAY request the creation of an Internet-Draft at any time/MAY request a revision of an Internet-Draft being managed on Github at any time/

Section 7: s/GitHub, mailing lists, and in-person meetings/GitHub, mailing lists, interim meetings, and IETF meetings/

Section 7: s/explicitly identify/identify/

Section 8: s/For a document that use/For a document that uses/

Section 9: s/that raises what a new issue/that raises a new issue/

Thanks,
Alissa

---

From: "Christopher Wood" <[email-masked]>
Date: Sat, 08 Feb 2020 14:38:37 -0800

Thanks for the review, Alissa! I made two PRs that should address your 
substantive comments [1] and nits [2]. Please have a look. I also left 
some comments inline below.

On 6 Feb 2020, at 12:53, Alissa Cooper wrote:
> Should there be some words in this document about how research groups 
> might draw inspiration from this document, but that specific guidance 
> for research groups is out of scope?

Good idea! I made this change in [1].

>
> == Section 2.1 ==
>
> draft-ietf-git-github-wg-configuration settled on the naming 
> convention ietf-wg-<wgname> so this document needs to be updated to 
> align with that.

This is also done in [1].

>
> == Section 4.2 ==
>
> Do you want to say a few words about who determines what constitutes a 
> "substantial" change (or add a forward reference to Section 5 and 
> provide some uniform statement about it there)? For example, might 
> some WGs determine that anything non-editorial is substantial (also 
> discussed in 5.3.2)? Whose call would that be?

Pointing to 5.3.2 seems easiest and minimizes redundancy. I went with 
that in [1].

>
> == Section 4.3 ==
>
> Should we see if the secretariat can setup server infrastructure to 
> support github-notify-ml for WGs that want it, and have a process 
> whereby WGs can request support for it? This would imply changes to 
> draft-ietf-git-github-wg-configuration rather than to this document, 
> but I figured I would ask while I'm reviewing this.

I don’t have a strong opinion on this. However, it’s worth noting 
that Mark Nottingham recently introduced a new service [3] that 
effectively replaces github-notify-ml. I found it fairly easy to use. 
See [4] as a recent change made for the TLS WG. If maintaining this 
service is costly, perhaps it would be a good idea to see if the 
secretariat can help.

> == Section 10 ==
>
> I'd like to suggest:
>
> OLD
> Maintaining a mirror of a repository that is hosted on GitHub is 
> relatively simple and might be considered as a way to provide a backup 
> for the primary repository.
>
> NEW
> Maintaining a mirror of a repository that is hosted on GitHub is 
> relatively simple and is specified in [GH-CONFIG] to provide 
> IETF-hosted backups for WG repositories.

Fixed in [1].

Thanks again!

Best,
Chris

[1] https://github.com/ietf-gitwg/using-github/pull/41
[2] https://github.com/ietf-gitwg/using-github/pull/39
[3] https://github.com/ietf-github-services/activity-summary
[4] 
https://github.com/ietf-github-services/activity-summary/commit/0b7d52d77f507a6e26cce8c02e489e5d2afe1e48

---

From: Alissa Cooper <[email-masked]>
Date: Mon, 10 Feb 2020 09:41:17 -0500

Thanks Chris. All the changes look good. Please post the rev and then I’ll initiate last call. One comment below.

> On Feb 8, 2020, at 5:38 PM, Christopher Wood <[email-masked]> wrote:
> 
>> 
>> == Section 4.3 ==
>> 
> I don’t have a strong opinion on this. However, it’s worth noting that Mark Nottingham recently introduced a new service [3] that effectively replaces github-notify-ml. I found it fairly easy to use. See [4] as a recent change made for the TLS WG. If maintaining this service is costly, perhaps it would be a good idea to see if the secretariat can help.

Ah, I had missed this, thanks. Let’s leave this out, then, since we can always ask the secretariat to do things even if we don’t say so in this RFC.

Alissa

> [4] https://github.com/ietf-github-services/activity-summary/commit/0b7d52d77f507a6e26cce8c02e489e5d2afe1e48