Re: [Ietf-and-github] [Last-Call] Genart last call review of draft-ietf-git-using-github-04

[Martin Thomson <[e-mail]>]

On Mon, Mar 9, 2020, at 20:05, Alexandre Petrescu wrote:
> But I would like to mention, for the sake of not missing it, that
> in my experience it is not the WG Chairs who request the use of GitHub
> for documents, but it is the potential authors that might decide so.
> They feel a need to share and contribute to a common document, and
> select github as a place to store the intermediary verrsions.

This was always possible and remains so.  This document exists to describe how formal functions, like decision-making, might best use the tool.  More specific text on that is in Section 3.1.

> > 3.1.  What to Use GitHub For
> 
> This section 3.1 is good in general, but does not seem to me to say What
> to Use GitHub For.  This is what it should be used for: share Internet
> Drafts and share code implementing protocols.

That is in the Introduction and Document Goals sections, which I think is sufficient.

> > 4.2.  Pull Requests
> > 
> > Pull requests are the GitHub feature that allow users to request 
> > changes to a repository.
> 
> It might be a matter of English usage, but I think Pull Requests allow
> users to 'obtain' the most recent changes present in the repository(?)
> If I understand github correctly, in order to 'request changes to a
> repository' one might rather use 'push' instead of 'pull'(?)

"pull request" is the correct term.  It is a request for someone else to "pull" certain changes into their repository.  

It's not a push. That would imply no choice on the part of the target.

And yes, it's weird that you push to a branch in order to create a pull request.  But that's how git works: it makes a degree of sense, but only if your world view is sufficiently distorted to begin with.

> In this introductory section, I think it makes sense to explain the
> behaviour of GitHub with respect to accents in people names.  Is it
> working ok or not?

Yes.  The whole charset thing is difficult, but if you use UTF-8 and Unicode you will find that things just work.  In most cases, you don't even have to make an effort to do so because modern software has largely left the baggage of the past behind.  We've recently added the real names of contributors to the QUIC specs and it just worked.

> If we find out that github does not mess these accents then it would be
> great to tell so in the I-D.

I would rather leave that pass without comment.  From my perspective, this all works.  That might be cause to celebrate, but we don't need to burden people with the details of solved problems when there are enough unsolved ones left to worry about.  If you are having issues, then that's something to work on.  For instance, it could be a system locale issue.

> How about the other recommendation?
> I suggest recommending this: do not keep the .txt nor the .pdf in the 
> root folder.

That is a fine suggestion that I fully support.  I find that including build output in the repository contributes to a hostile process for contributors. I have other things that I would rather spend that budget on, like trailing whitespace...

But none of that really needs to be in an RFC.  It's just minutiae.