Subject: IETF Git and GitHub tutorial

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

Hi folks,

Over in the GIT WG, we're trying to make GitHub easier to use for WGs and their contributors. As part of that effort, we put together a Git/GitHub tutorial for folks new to these technologies:

   https://ietf-gitwg.github.io

We would greatly appreciate feedback on the material, especially if your WG uses GitHub in some capacity. (Circulation to WG lists, should you feel it's appropriate, would be great, too!)

Thanks!
Chris, on behalf of the GIT WG

---

From: Daniel Migault <[email-masked]>
Date: Fri, 11 Oct 2019 08:22:50 -0400

Hi,

Thanks for initiating this page, this is really useful. I think it would be
useful to have a page detailing  to someone that has never used git and
that is willing to send comment or propose text to a wg document.
* how do I comment using github
* how do I purpose text.
For that scenario, we may only limit ourselves to the web interface.

Yours,
Daniel

>
> On Thu, Oct 10, 2019 at 10:46 PM Christopher Wood <[email-masked]>
> wrote:
>
>> Hi folks,
>>
>> Over in the GIT WG, we're trying to make GitHub easier to use for WGs and
>> their contributors. As part of that effort, we put together a Git/GitHub
>> tutorial for folks new to these technologies:
>>
>> We would greatly appreciate feedback on the material, especially if your
>> WG uses GitHub in some capacity. (Circulation to WG lists, should you feel
>> it's appropriate, would be great, too!)
>>
>> Thanks!

-- 
Daniel Migault
Ericsson

---

From: Michael Richardson <[email-masked]>
Date: Fri, 11 Oct 2019 16:06:55 +0200

Daniel Migault <[email-masked]> wrote:
    > Thanks for initiating this page, this is really useful. I think it
    > would be useful to have a page detailing to someone that has never used
    > git and that is willing to send comment or propose text to a wg
    > document.  * how do I comment using github * how do I purpose text.

And there is a serious limitation, which is that it pretty much impossible to
rebase with only the web interface, so after having submitted an edit, once
it is accepted, one winds up with a tree (fork) you can not use again.

-- 
]               Never tell me the odds!                 | ipv6 mesh networks [ 
]   Michael Richardson, Sandelman Software Works        | network architect  [ 
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [

---

From: "Salz, Rich" <[email-masked]>
Date: Fri, 11 Oct 2019 16:00:52 +0000

The work-around is simple and probably follows what most people do, anyway: do not re-use a branch name for different items of work. (Arguably that's an implied git best practice.) In fact, GitHub pull requests use the branch name, so I would not be surprised if doing this (which you shouldn't) can lead to problems anyway.

---

From: Sarah Banks <[email-masked]>
Date: Fri, 11 Oct 2019 09:12:56 -0700

My WG has a lot of first timers. And a lot of non engineers - technical folks, SQA for example, but non engineers. FWIW everything Rich just said would be over their heads, in that they don't check in/check out code on a daily basis. I strongly +1 a thorough walk through guide for the typical tasks. 

Thanks
Sarah

> On Oct 11, 2019, at 9:00 AM, Salz, Rich <[email-masked]> wrote:
> 
>

---

From: Warren Kumari <[email-masked]>
Date: Fri, 11 Oct 2019 20:49:32 +0200

> My WG has a lot of first timers. And a lot of non engineers - technical folks, SQA for example, but non engineers. FWIW everything Rich just said would be over their heads, in that they don't check…

I don’t see the complexity -- as (possibly) Bruce Lawson said "Git
gets easier once you understand branches are homeomorphic endofunctors
mapping submanifolds of a Hilbert space."

W

P.S: I *fully* agree with you -- I do basically all of my personal
projects in git, and all of my drafts, and I contribute to other
people projects, etc -- and I *still* often just copy my changes
somewhere, delete the entire repo, checkout a clean copy and then
stuff my changes back in, all the while chanting the mantra "nom erg
con flit, nom erg con flit, please gods, nom erg con flit". (Ok, it's
been many years since I'be blown away a repo, but I *do* still have a
personal cheatsheet for how to rebase a pull request...)

I've tried explaining to some "non-computer" people how to use git,
and their eyes quicky glazed over -- for some of them the closest I've
gotten is "Use Github, click the button that looks like a pencil, type
quickly and then click 'Commit changes'. Don't touch anything else..."

W

---

From: Sarah Banks <[email-masked]>
Date: Fri, 11 Oct 2019 13:16:16 -0700

Slightly soapboxish...

If we were all engineers writing code as a day job perhaps this would be second nature (or we'd be motivated to not admit we didn't know and we'd figure it out). But we're not all engineers, and git is unfortunately a tool for engineers. It's not as approachable as it seems some of us think it is. Thanks for supporting the effort; I do hope documentation solves the problem :)

/S

> On Oct 11, 2019, at 11:49 AM, Warren Kumari <[email-masked]> wrote:
>

---

From: Michael Richardson <[email-masked]>
Date: Fri, 11 Oct 2019 22:26:36 +0200

Salz, Rich <[email-masked]> wrote:
    >> And there is a serious limitation, which is that it pretty much
    >> impossible to rebase with only the web interface, so after having
    >submitted an edit, once it is accepted, one winds up with a tree (fork) you can not use again.
  
    > The work-around is simple and probably follows what most people do,
    > anyway: do not re-use a branch name for different items of
    > work. (Arguably that's an implied git best practice.) In fact, GitHub
    > pull requests use the branch name, so I would not be surprised if doing
    > this (which you shouldn't) can lead to problems anyway.

In order words, you have to know how to create a branch.
While helping some other newbies to git (who were on windows 10, and could
barely use a shell), when they use the crayon icon to edit/send-pull-request
it always forked to their account, and then used a branch "master".

At which point, we had no idea how to update what was in their account
without a shell.

---

From: "Salz, Rich" <[email-masked]>
Date: Fri, 11 Oct 2019 20:29:51 +0000

Shrug.

Can't teach everyone how to use a C compiler, either.

---

From: Michael Richardson <[email-masked]>
Date: Sun, 13 Oct 2019 11:19:20 +0200

Sarah Banks <[email-masked]> wrote:
    > If we were all engineers writing code as a day job perhaps this would
    > be second nature (or we'd be motivated to not admit we didn't know and
    > we'd figure it out). But we're not all engineers, and git is
    > unfortunately a tool for engineers. It's not as approachable as it
    > seems some of us think it is. Thanks for supporting the effort; I do
    > hope documentation solves the problem :)

I am a strong proponent of design teams using git (and I've used git for ID
for a long long time, and CVS before that!!!!).  
I consider github just a way for people without public IP addresses to use
git.  Github issues are also useful for design teams, but unless you do the
issue full-lifecycle bi-directoinal integration with the mailing list, which
seems non-trivial for WG chairs to organize (I haven't gotten it working),
then it is hostile to the formation of consensus.

Given that we believe in running-code and then rough consensus, I remain
a bit skeptical about efforts to make it very easy for
non-running-code-writers to be major contributors to technical
specifications.  {Where my thinking breaks down is when it comes to
non-bits-on-the-wire protocols, such as policy documents} 

So, I care less about making it easy for reviewers to be able make
pull-requests.  I significantly prefer that non-design-team members bring
their issues to the mailing list, and that they "send text" that way.

I think that the web interface to github is significantly more complex to
deeply understand than the CLI interface; at least given a OSX or Linux on
the desktop, and an having gotten over how ssh keys work. (And I consider
learning about ssh-agent to be something every student should have learned
before they go on their first work placement, and any 15yr old who wants to
write code should already know today)

It is only users of that other desktop that seem to have all the problems.
So, after decades of abuse from the makers of that companies' desktop
("This web site is designed for browser X in 1024x768. Please click here
download ActiveX so that we can p0wn your computer") I feel very very very
little sympathy.

And as I said in this thread, I don't think that the web interface supports
the full editing cycle: fork/edit/pull-request/rebase.  Maybe github's new
masters will find a good UX fix this; but I'd rather that they deployed IPv6.

If I thought there was a full-cycle solution with a browser, I'd do a
screencast of the web interface tomorrow.   If someone would like me to do a
screencast of the CLI version, I would be happy to that this week. (I'm at RIPE79)

---

From: Warren Kumari <[email-masked]>
Date: Sun, 13 Oct 2019 12:37:43 +0200

> their issues to the mailing list, and that they "send text" that way.

As a draft author, I deeply love pull requests — sure, substantive text
should go through discussions, but after 67 instances of:
O: “In other words it is better...”
P: “In other words, it is better...”
C: Nit - you are missing a comma.

Or
“In section 3.1.17.42 there is a missing ‘and’ between the twenty third and
twenty fourth word of the eight paragraph.” (I’ve had a nit report in
basically this way - what made it more fun was that the reporter didn’t
specify the version of the draft, and I’d rewritten section 3.1.17.42 many
times...)

W

> screencast of the CLI version, I would be happy to that this week. (I'm at
I don't think the execution is relevant when it was obviously a bad idea in
the first place.
This is like putting rabid weasels in your pants, and later expressing
regret at having chosen those particular rabid weasels and that pair of
pants.
   ---maf

---

From: Michael Richardson <[email-masked]>
Date: Tue, 15 Oct 2019 19:21:06 +0200

> C: Nit - you are missing a comma.

Yes, I totally agree with you here.
Such editorial nit pull requests can be done in many ways, and they simply
don't need WG attention at all.  Use the technology here.  The design team
ultimately decides when/if/how to process things.

While I applaud QUIC's ability to live in github issues (and the CELLAR WG
does almost as well), I think that for a large number of WGs, the
non-design-team members are simply not git-clueful enough (on average).

The lack of a complete web-based workflow (the missing git rebase step) means
it's just better not to do that.

---

From: Jim Fenton <[email-masked]>
Date: Tue, 15 Oct 2019 11:24:35 -0700

> it's just better not to do that.

If the workflow includes a rebase, you'll probably lose all but the more
experienced git users since rebase is considered by many to be advanced
functionality and isn't something that many git users learn.

-Jim

---

From: Michael Richardson <[email-masked]>
Date: Wed, 16 Oct 2019 18:23:12 +0200

> functionality and isn't something that many git users learn.

AFAIK, The alternative for a web-only github interaction is that the contributor
deletes their forked repo, and makes a new fork.   If you can come up with an
alternative, then please do.  This is why I don't think that teaching
CLI-phobic users to use github is a good use of our time.

--
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-

---

From: "Christopher Wood" <[email-masked]>
Date: Wed, 16 Oct 2019 09:50:26 -0700

>From my perspective, this tutorial aims to help those WGs that have elected to use GitHub in some capacity. If contributors of those WGs want to use GitHub yet don't know how, then this should help get them started. (And if it doesn't, then we should fix that!) It's a reference for those who need it.

Best,
Chris