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

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

Hi Brian,

On Sat, Oct 5, 2019, at 12:51 PM, Brian E Carpenter wrote:
> >> 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.

To clarify: are you suggesting we add text to one of the documents stating this? If so, what would that text be, and where would you add it?

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

Okay, good to know. I included that link, too.

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

Great idea! It's done.

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

That makes sense. For now, I'll point to the desktop application page. If someone wants to suggest text for the other operating systems, that would be greatly appreciated.

Thanks again for the feedback!

Best,
Chris