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

[Alexandre Petrescu <[e-mail]>]

Hi,
Thank you for the message.

Le 09/03/2020 à 05:08, Martin Thomson a écrit :
> On Sat, Mar 7, 2020, at 03:31, Alexandre Petrescu wrote:
>> I take advantage of this Last Call about github use at IETF to give
>> my comments about writing I-Ds on github.
> 
> Hi Alex,
> 
> Thanks for sharing your experience. Taking this back to the Working 
> Group list as it doesn't seem to be a comment about the work.

Indeed I didnt read the draft prior to submitting the comments.

> Do you think that anything in this invalidates the advice and 
> procedures in the draft?  Or suggests the need for additions?  I 
> didn't see anything that suggests the need for changes.

I now read the draft.  I have the following comments:

draft-ietf-git-using-github-05:
> The Working Group Chairs are responsible for determining if there is
>  interest in using GitHub and making a consensus call to determine if
>  the proposed policy and use is acceptable.

I agree with the suggestion.

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.

But I agree that it might be that in other WGs where I am not active it 
is the WG Chairs who request it.

> 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.

> 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'(?)

(the button in GUI on Windows that obtains the most recent changes
present in the repository is labelled 'Pull origin'; after pressing it, 
and success, the GUI says 'Last fetched just now').

> 1.2.  GitHub

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?

For my part, I suspect gihub to be the origin of errors I am struggling
with the following accents in these names: 	
Ole Trøan, 神明達哉 (TATUYA Jinmei), Jérôme Härri.

They display perfectly fine in my emails on Windows with Thunderbird,
but get messed when putting in an xml file on Windows, gnu emacs,
xml2rfc.tools.ietf.org  and github.  I suspect github to be the problem.

I would like to know whether other people using Windows,
xml2rfc.tools.ietf.org and GitHub can put safely these names in an xml file.

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

You said:
> Indeed, your process would seem to fit within the pattern described,
> with the possible exception of missing a notice for contributors
> about their obligations (usually CONTRIBUTING.md).

Sounds reasonable.

> 
>> 3. do not commit the xml file to github before you are sure it 
>> compiles safely on xml2rfc.tools.ietf.org
> 
> I personally wouldn't make this recommendation.  Stuff breaks 
> occasionally and asking people to check is unreliable.  Automated 
> validation on check-in is my preferred solution to this problem.

Makes sense.

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

Alex
> 
> Cheers, Martin
>