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

From: "Christopher Wood" <[email-masked]>
Date: Fri, 04 Oct 2019 13:32:54 -0700

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

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.

Please have a look at this material and provide feedback! We would like to finish draft-ietf-git-using-github in (or before) Singapore.

Thanks,
Chris (chair hat on)

---

From: Tommy Pauly <[email-masked]>
Date: Fri, 04 Oct 2019 16:56:35 -0700

The document looks good and reads well! I think the content all makes sense.

I did find a few nits in my review, which I've created a PR to fix here: https://github.com/ietf-gitwg/using-github/pull/18

The one content change I propose is to change:

"All repositories for working group documents MUST be public."

To:

"All repositories for Working Group documents within the Working Group
organization MUST be public."

The sentence previously seemed to also include a requirement on working group documents for working groups not officially using GitHub; I don't think we can make a requirement for people who happen to use a private GitHub repo to manage a working group document that's not officially using GitHub.

Thanks!
Tommy

> On Oct 4, 2019, at 1:32 PM, Christopher Wood <[email-masked]> wrote:
> 
> Hi folks,
> 
> _______________________________________________
> Ietf-and-github mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-and-github

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 5 Oct 2019 14:41:21 +1300

>> (I'm sure an updated version in the datatracker will come shortly.)

When, please? 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).

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

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

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.

Regards
    Brian

---

From: "Christopher Wood" <[email-masked]>
Date: Sat, 05 Oct 2019 04:21:13 -0700

On Fri, Oct 4, 2019, at 4:56 PM, Tommy Pauly wrote:
> I did find a few nits in my review, which I've created a PR to fix 
> here: https://github.com/ietf-gitwg/using-github/pull/18

Thanks for taking the time to read and make improvements! The changes look good to me.

> The sentence previously seemed to also include a requirement on working 
> group documents for working groups not officially using GitHub; I don't 
> think we can make a requirement for people who happen to use a private 
> GitHub repo to manage a working group document that's not officially 
> using GitHub.

Agreed. Good catch!

Best,
Chris

---

From: "Christopher Wood" <[email-masked]>
Date: Sat, 05 Oct 2019 04:37:48 -0700

On Fri, Oct 4, 2019, at 6:41 PM, Brian E Carpenter wrote:
> 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

> 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

---

From: Brian E Carpenter <[email-masked]>
Date: Sun, 6 Oct 2019 08:51:16 +1300

Hi Chris,
> 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.

Thanks!

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

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

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

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

---

From: Benjamin Kaduk <[email-masked]>
Date: Tue, 8 Oct 2019 08:50:43 -0700

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

nmake and jom exist, though most projects I work with end up with separate
makefiles for windows and unix usage because the needed rules for
compiling/linking C are so different.

-Ben

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 9 Oct 2019 08:12:31 +1300

Hi ben,
> compiling/linking C are so different.

Are they well documented? In any case it seems that I am right about non-portability.

Thanks
   Brian

---

From: "Salz, Rich" <[email-masked]>
Date: Tue, 8 Oct 2019 20:18:32 +0000

Yes, I-D draft/makefile stuff only works on unix-like systems.  Luckily that is a fairly low bar these days.

---

From: Mike Bishop <[email-masked]>
Date: Tue, 8 Oct 2019 20:26:52 +0000

Particularly now that Windows includes the Windows Subsystem for Linux, meaning you can have a full Ubuntu install (with make toolchain) on a Win10 machine.

---

From: Benjamin Kaduk <[email-masked]>
Date: Thu, 10 Oct 2019 13:13:08 -0700

> Are they well documented? In any case it seems that I am right about non-portability.

The subsystem for linux is probably the right answer here (thanks, Mike!)
but for completeness: Microsoft seems to have nmake docs at
https://docs.microsoft.com/en-us/cpp/build/reference/nmake-reference?view=vs-2019
which presumably are comparable to most of Microsoft's docs.  I've never
actually used jot myself, so I can't say much more about it than people use
it in order to do parallel builds (not possible with nmake).

-Ben

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 11 Oct 2019 09:17:21 +1100

> The subsystem for linux is probably the right answer here (thanks, 

Yes, this is the configuration I use.  I used to use cygwin, which should work, but it's a lot more difficult to setup.

> it in order to do parallel builds (not possible with nmake).

I've never tried using nmake.  My guess is that it would fail spectacularly.

---

From: "Christopher Wood" <[email-masked]>
Date: Thu, 10 Oct 2019 19:39:52 -0700

Hi Brian,

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

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

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

> 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