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

Hi Chris,
On 06-Oct-19 00:37, Christopher Wood wrote:
> On Fri, Oct 4, 2019, at 6:41 PM, Brian E Carpenter wrote:
>>>> On Oct 4, 2019, at 1:32 PM, Christopher Wood <caw@heapingbits.net> 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. 

Indeed, and that's why a SHOULD would be the strongest statement I'd
recommend, and why it should be a matter of WG policy.

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

Thanks!

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

Yes, exactly, and I see that it's also available for OS X; not Linux, sadly. I also installed the CLI too, of course. So maybe https://help.github.com/en/articles/set-up-git is a more general link.

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

It looked reasonably complete to me. Maybe add a link for feedback on any gaps in the document (presumably, an issue tracker for the document itself)?

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

I agree. That's the page I consulted when first using GitHub desktop.

My experience is that the desktop app is sufficient for most purposes; it's pretty rare that I have to use the CLI. Incidentally, make is a Unixism that doesn't exist in Windows. So that part of the tool chain isn't portable afaik.

Regards
    Brian

> 
> Thanks!
> Chris
> 
> _______________________________________________
> Ietf-and-github mailing list
> Ietf-and-github@ietf.org
> https://www.ietf.org/mailman/listinfo/ietf-and-github
> 