Re: [Ietf-and-github] Mirja Kühlewind's No Objection on draft-ietf-git-using-github-05: (with COMMENT)

[Martin Thomson <[e-mail]>]

Hi Mirja,

This got long, so I trimmed a few things out where you had some useful suggestions that seemed obvious enough.  I have updated the same PR from before at https://github.com/ietf-gitwg/using-github/pull/45/files

On Fri, Mar 13, 2020, at 05:27, Mirja Kuehlewind wrote:
> There is a risk if chairs allow repos for some draft but not other, 
> that those drafts are seen as more important. So I think some more 
> discussion is needed in this document that if a wg decide to support 
> individual drafts in their GitHub organisation, they are expected to 
> give that opportunity to everybody asking.
> 
> However, I still see some higher risk here for confusing for people who 
> are less familiar with the IETF and the respective naming convention. 
> In the datatracker the document for each wg are clearly separated into 
> a section for wg doc and other related docs. That is less obvious on 
> GitHub, especially for people who only find things over GitHub and are 
> not aware of e.g. the datatracker or other IETF processes.
> 
> I’m not saying we should forbid this. Chairs are free in how they think 
> they can manage their groups best. But I also think we should not 
> recommend it. Also we should probably give more guidelines how to make 
> it more clear that documents have different status in GitHub besides 
> the draft name. E.g. there is the repo description that could include a 
> “warning”. Or we could recommend to have all wg doc repos as pinned 
> repos but other not…

I realize that this happens, but it is just one of many ways in which chairs might abuse their authority (intentionally or not). But I just don't see that happening here.  Chairs who have this policy are open about it and extend this opportunity to any who request it.

So I'm against making a firm recommendation.  I like the potential for there to be no special status implied by inclusion in an organization, any more than having a draft listed on https://tools.ietf.org/wg/$WG/ or https://datatracker.ietf.org/wg/$WG/documents/ implies any special status.

> > 
> >> 3) Sec 4.2:
> >> "   Editors SHOULD make pull requests for all substantial changes rather
> >>   than committing directly to the "master" branch of the repository."
> >> I think this does not align well with how we work today (without GitHub). E.g.
> >> if a group decides to use GitHub to better track changes and maybe easily
> >> integrate editorial comments, but decide to have all discussion on the mailing
> >> list (and not use github issues), I think it would be fully okay for the
> >> editors just commit directly based on the consensus on the mailing list. So I
> >> think the important part is that substantial comments should only be committed
> >> with wg consensus and therefore it is a good practice to have pull requests
> >> first to declare consensus based on the concrete proposed edits. However, if a
> >> different way to declare consensus is used that's fine as well. In short, I
> >> think the SHOULD is to string here for the general case.
> > 
> > I think that it greatly improves transparency, and I want to add that WG policies could insist upon this practice, but we don't need normative force in the two statements in this paragraph.
> 
> Yes, it should not be normative but I’m also not sure if that practice 
> is the right thing for every document. Yes it greatly can improve 
> transparency and I agree that is is a good practice but for some e.g. 
> small documents it might be more overhead/“process burden” than really 
> needed. So I think it would be good to  reword slightly and/or add some 
> more emphasis that there might be cases where it might not be needed.

I'm fairly sure that we have consensus in the WG to keep a recommendation for this practice.  It is now a recommendation without normative force, are you suggesting that no such recommendation be made?  Because I don't think that is reflective of the practices that have emerged, nor is it a good idea.

> >> 4) Sec 5.3 (mostly editorial): [...]
> >> This text seems to apply more general to all content in section 5 and should
> >> maybe be moved out of section 5.3. Similarly I'm not sure if section 5..3.1 and
> >> 5.3.2 should actually be subsection of 5.3. The question of which issue to
> >> track seem rather orthogonal to the question who resolves the issue (I agree
> >> that this discussion does not make sense when no issue are tracked like in sec
> >> 5.1 but it could make sense for the mode in section 5.2)
> > 
> > The organization here is tricky, but I do agree that this text is generic.  I've moved the piece you quoted up to the intro to Section 5.
> 
> Thanks! What’s about 5.3.1 and 5.3.1. I would recommend to create a new 
> subsection there and not have these subsubsection within 5.3.

Maybe I'm not following you now.  My view is that the 4 paragraphs under 5.3 directly belong there without creating additional subsections.

> Thanks! I would also propose to slightly rephrase it to make it more 
> GitHub specific 
> "The risk is that changes that potentially contain design changes might 
> get merged into the working version of the document before consensus of 
> the Working Group is confirmed. However, transparency of these changes 
> is expected to still be higher compared to when documents are 
> maintained by the editors without any detailed change log.”

I've reworded this, but I think that the second sentence you propose is duplicative of the paragraph that follows.  Here's what I have now:

> [...] The risk is from integrating changes including substantive decisions that don't reflect the
consensus of the Working Group or that the need for consensus on an issue is not identified.
>
> Changes made by editors under this process do not lack options for identifying and correcting problems.  GitHub and git provide tools for ensuring that changes are tracked and can be audited.

> >> 8) Sec 5.3.2:
> >> "   As documents mature further, explicit confirmation of technical
> >>   decisions with the Working Group mailing list becomes more important."
> >> Not sure I agree here. I know what you mean but explicit confirmation on the
> >> mailing list is always important. Maybe there is a way to rephrase that (or
> >> just remove that sentence...?)
> > 
> > This is really only emphasis, but I would prefer to keep it.
> 
> I’m concern that this sentence implies that technical design changes do 
> not need to be confirmed in the early phase, which I think it just 
> wrong. I think this is more than emphasis.

I will have to disagree here.  The previous section is quite deliberate about the need for obtaining review and consensus on these decisions.  The point is that there are fewer opportunities left to find and discuss issues on a mature specification.


> I believe you already revised this text based on other comments, right? 
> (Lost track a bit). If so, maybe you can just point me add the next 
> text…?

You aren't the only one, it was in response to Alvaro:

> Chairs can declare Working Group consensus about the resolution of issues in the abstract, allowing editors discretion on how to capture the decisions in documents.
-- https://github.com/ietf-gitwg/using-github/pull/47/files#diff-f0832ea1138ac7354c220723b246954bR633-R636

> > The intent here is to reiterate 2418 regarding session documents and to encourage routine publication of snapshots.
> 
> Actually it might be better to not use normative language here and 
> rather point to 2418. However, right now the text does not seems to 
> encourage routine publication of snapshots but rather it seems to 
> encourage to “only” publish if there is a meeting.

That happened as a result of a review (and now I'm losing track too): https://github.com/ietf-gitwg/using-github/pull/48/files