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

[Kjetil Torgrim Homme <[e-mail]>]

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

-- 
regards,
Kjetil T.