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

[Alexandre Petrescu <[e-mail]>]

Le 10/03/2020 à 07:05, Kjetil Torgrim Homme a écrit :
> On Fri, 2020-03-06 at 17:31 +0100, Alexandre Petrescu wrote:
>> - I wrote a README about how to use that xml file.  There are two
>>     distinct operations: compilation and submission.
>>
>> - this the README that I wrote and put in the github repository of
>> the xml file of the Internet Draft we currently write:
>>
>> -----------------------------------------------------------------
>>
>> 0. on Windows, use the free Github Desktop tool.  Within it, use
>>      buttons like 'Commit to master' and others like 'Push origin' in
>>      order to upload the files that you modify.
>>
>> 1. How to 'compile' the .xml file:
>>
>> - go to https://xml2rfc.tools.ietf.org
>> - press the button to select a file
>> - choose the .xml file
>> - leave the 'Output format' and 'Options' to their default
>> - click 'Submit'
>>
>> That displays the .txt file in the browser, but can also create .txt
>> and .pdf files, depending on how the Output format is Optioned.
> 
> this should be handled automatically by Github Actions (I am not that
> familiar with Github Actions, but it is trivial to set up with Gitlab
> CI and I don't think Github is much worse.)  the draft mentions this in
> section 8 about Continuous Integration.
> 
>> That does not submit the draft to the IETF.
>>
>> 2. In order to submit a draft, upload the .xml at the address
>> https://datatracker.ietf.org/submit/
> 
> this could also be done automatically, possibly restricted to happen
> only for merges into specific git branches, if you adopt a "git flow"
> work method (the draft hints at using something like that, since it
> discourages direct commits to "master")
> 
>> 3. do not commit the xml file to github before you are sure it
>> compiles safely on xml2rfc.tools.ietf.org
> 
> again, this sanity check is best left to computers.
> 
>> - despite my efforts of explaining, people still prefer to exchange
>> the files by email.  This feedback is from working with several
>> groups on several xml drafts on several github repositories.
> 
> both Github and Gitlab have good web based editors which can
> recommended to Git skeptics

I heard that skepticism from many people in a hurry.  They dont have 
time to get imposed some rule.

It is difficult to understand some parts of the github behaviours.

Especially by those who do shared document processing by using other 
document sharing tools like github.

This is the gist of it: having a beautiful modern web interface, makes 
one think that GitHub easily supports things like uploading a document. 
It is not the case.  There is no button on the web to Upload a file. 
Not even to Download a file.

Alex

  (there is no doubt that Git can be
> intimidating to get started with, and for some contributors it may not
> be worthwhile).  I have not tried them on an XML formatted draft,
> however.
> 
> the draft stresses that a WG's choice of using a git service should not
> exclude participants who will not use the service.  the draft does not
> go into reasons for such a rejection, but, e.g., the Github EULA is not
> necessarily acceptable to everyone, and this should be respected.
>