Re: [Ietf-and-github] Seeking feedback on draft-ietf-git-using-github and Git tutorial

["Christopher Wood" <[e-mail]>]

On Fri, Oct 4, 2019, at 6:41 PM, Brian E Carpenter wrote:
> >> On Oct 4, 2019, at 1:32 PM, Christopher Wood <[e-mail]> wrote:
> >>
> >> Hi folks,
> >>
> >> As we approach Singapore, it would be quite useful to get more feedback on draft-ietf-git-using-github, especially with the changes merged in September. You can view the editor's copy here:
> >>
> >>   https://ietf-gitwg.github.io/using-github/draft-ietf-git-using-github.html
> >>
> >> (I'm sure an updated version in the datatracker will come shortly.)
> 
> When, please? 

I don't know exactly, but certainly before the draft deadline.

> The -00 draft is close to expiry. Apparently no update 
> was posted prior to IETF 105 (against the advice in "6. Internet-Draft 
> Publication"). Reading that section, I think it says too little about 
> the danger of infrequent updates disadvantaging some WG members. I 
> think that WG chairs SHOULD adopt a policy about the frequency of 
> drafts (and IMHO it SHOULD be more frequent than one per IETF cycle, if 
> a document is under active development).

Perhaps, but that's a separate issue. Some things just move slowly or take time, and not for lack of author or WG contributor activity. 

> Also I had to work a little bit to get hold of diffs in the usual 
> (rfcdiff) form. This may change somwhat as we move to xmlrfcv3, but 
> could we recommend that .txt and Diff...txt.html files are also always 
> made available? (Yes, the .txt file is there, but I had to guess where.)

That seems reasonable to me! I filed this issue to add that to the document:

   https://github.com/ietf-gitwg/using-github/issues/19

The i-d-template tool links to these from document repository READMEs (see the "Compare Editor's Copy to Working Group Draft" link):

   https://github.com/ietf-gitwg/using-github

Here's the diff in case others want it too:

   https://tools.ietf.org/rfcdiff?url1=https://tools.ietf.org/id/draft-ietf-git-using-github.txt&url2=https://ietf-gitwg.github.io/using-github/draft-ietf-git-using-github.txt

> >> To accompany this document, we also put together a tutorial for people new to Git(Hub) and its use for IETF draft development:
> >>
> >>   https://ietf-gitwg.github.io
> >>
> >> It aims to help IETF contributors get started with the system, Martin's excellent i-d-template toolchain, and GitHub for the purposes of supporting the different Modes of Interaction described in draft-ietf-git-using-github.
> 
> It's a good start. But it doesn't provide pointers on how to install 
> GitHub on the popular operating systems, and it doesn't do much for 
> people who prefer to use the GitHub desktop app on Windows, or those 
> who mainly want to use the web interface.

Interesting! I've a couple followup questions:

1. When you say "install GitHub," do you mean an application for using GitHub? If so, does this link suffice? 
    
   https://help.github.com/en/desktop

2. Putting aside the "how" aspect for now, is the content of the page complete, or are there gaps that you'd like to see filled? For instance, are there parts of a workflow that are not described which you think should be?

3. This page shows how to modify documents using the GitHub application:
   
   https://help.github.com/en/desktop/contributing-to-projects

Would pointing to that page from the "Document Modification" section, where relevant, suffice? Or would you want to see details about using the application inlined in the tutorial? (Personally, I think that's unwise, as the tutorial documentation will likely become outdated as GitHub makes changes to their application.)

Thanks!
Chris