Subject: Re: [Last-Call] [Gen-art] Genart last call review of draft-ietf-git-using-github-04

From: Alissa Cooper <[email-masked]>
Date: Tue, 3 Mar 2020 21:06:32 -0500

I put this in an RFC Editor note.
Alissa

> On Feb 24, 2020, at 11:04 AM, Martin Thomson <[email-masked]> wrote:
> 
> Thanks Brian,
> 
> On Sun, Feb 23, 2020, at 17:01, Brian Carpenter via Datatracker wrote:
>> Is this draft intended to become part of BCP25? I think it would be
>> useful for the IESG to clarify this rather than leave it to the RFC Editor.
> 
> This is a good question.  Given the intended status of BCP, I would say that integrating into 25 is better than creating a new number.  I don't know how to best signal this intent though.
> 
> And I fixed the nit in the copy on GitHub.
> 
> _______________________________________________
> Gen-art mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/gen-art

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 4 Mar 2020 15:48:57 +1300

Thanks
   Brian

---

From: Alexandre Petrescu <[email-masked]>
Date: Fri, 6 Mar 2020 17:31:58 +0100

Hi,

I take advantage of this Last Call about github use at IETF to give my 
comments about writing I-Ds on github.

We are writing a draft with a few colleagues at IETF about a 6MAN topic. 
  We initially  thought we'd use the Word template but quickly we moved 
to xml2rfc and github storage.

- the xml2rfc.ietf.org GUI generates a *.txt.pdf file, whereas it should
   generate a *.pdf file.  That makes difficult to talk about a 'txt'
   file (is it the ASCII or the .txt.pdf?).  I have been told I should
   report this to 'tools-discuss' email list, which I will do one day.

- the github folder containing the xml source should be as small as
   possible, and have at least as possible additional clutter files.
   This is not like a project of C files where there are no numerous *.c
   and *.h and *.asm files.  There is just one source: the xml.

- I wrote a README about how to use that xml file.  There are to
   distinct operations: compilation and submission.

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

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

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/

3. do not commit the xml file to github before you are sure it
compiles safely on xml2rfc.tools.ietf.org

Alex

Le 24/02/2020 à 02:01, Brian Carpenter via Datatracker a écrit :
> Reviewer: Brian Carpenter
> Review result: Ready with Issues
> 
> Gen-ART Last Call review of draft-ietf-git-using-github-04
> 
> I am the assigned Gen-ART reviewer for this draft. The General Area
> Review Team (Gen-ART) reviews all IETF documents being processed
> by the IESG for the IETF Chair.  Please treat these comments just
> like any other last call comments.
> 
> For more information, please see the FAQ at
> <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.
> 
> Document: draft-ietf-git-using-github-04.txt
> Reviewer: Brian Carpenter
> Review Date: 2020-02-24
> IETF LC End Date: 2020-03-03
> IESG Telechat date:
> 
> Summary: Ready with issue
> --------
> 
> Comment:
> --------
> 
> I've tracked this document since the -00 version and I think it is clear
> and represents WG consensus.
> 
> Issues:
> -------
> 
> Nit:
> ----
>> 3.4.  Document Formats
>>    In addition to the canonical XML format [RFC7991], document editors
>>    might choose to use a different input form for editing documents,
>>    such as Markdown.  Markdown-based formats are more accessible for new
>>    contributors, though ultimately decisions about format is left to
>>    document editors.
> 
> s/is/are/
> 
>

---

From: Kjetil Torgrim Homme <[email-masked]>
Date: Tue, 10 Mar 2020 07:05:15 +0100

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
> - this the README that I wrote and put in the github repository of
> the xml file of the Internet Draft we currently write:
> 
> -----------------------------------------------------------------
> 

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.

> 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")

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

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 11:29:28 +0100

Le 10/03/2020 à 07:05, Kjetil Torgrim Homme a écrit :
> 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

---

From: Kjetil Torgrim Homme <[email-masked]>
Date: Tue, 10 Mar 2020 11:47:23 +0100

On Tue, 2020-03-10 at 11:29 +0100, Alexandre Petrescu wrote:
> 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.

it is right up there in the file browser in Github,

  [Create new file] [Upload files] [Find File]

in Gitlab there is a generic [+ v] dropdown menu to upload a new file,
create a new branch etc.

there is also the concept of gist (Github) and snippet (Gitlab) which
is for more informal sharing of files, think pastebin on steroids.

>  Not even to Download a file.

well, that is slightly less obvious, I'll grant you that - the button
is called [Raw] in Github, which you may have to Control click to get
the file download dialog.  in Gitlab there is a separate download icon
(an arrow pointing down into a tray).

-- 
regards,
Kjetil T.

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 12:46:56 +0100

>    [Create new file] [Upload files] [Find File]

'Find file' is a term that means to open a file, if expressed in Mac, or 
it means to search and find a file if expressed in Windows.  It is 
misleading.

The particular need is the following: I want to download the file.  I do 
not want to display it first and only then download it.  It is too long.

So, I think my need is the following: I want a big visible button on 
github to quickly download a file, and not to have to go through 
numerous other buttons first.

Then, I want to update a file, not to upload a new one.

The fact that there are is no straight button to update a file leads to 
generation of many files in the same folder.  I upload a file with -AP 
in name, others put theirs, and we end up with too many files.

> (an arrow pointing down into a tray).

Thank you for the explanation.  I did not know that.  I think  I might 
need to put it in my howto.

Alex