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

[Alexandre Petrescu <[e-mail]>]

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