Subject: [Ietf-and-github] Heavy and light mode text

From: "Christopher Wood" <[email-masked]>
Date: Mon, 09 Sep 2019 09:04:10 -0700

Hi folks,

As discussed during our last meeting, Martin proposed some text further describing heavy and light modes [1]. Please have a look and comment here (or on the Pull Request) as you see fit. Barring objections, we'll merge these changes at the end of the week, and continue iterating on Barbara's proposed "ultra light" mode afterwards.

Thanks,
Chris

[1] https://github.com/ietf-gitwg/using-github/pull/15

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 10 Sep 2019 08:36:12 +1200

"I am probably incapable of seeing what a truly light option looks like." [Martin]

IMNSHO it means using GH only as a repository for intermediate versions, and using email for *all* discussion. Personally I find GH a very inconvenient mechanism for discussion compared to email threads, so I am at one end of the spectrum described at https://github.com/ietf-gitwg/using-github/pull/15#issuecomment-526450315. I think Martin is correct that each WG could find its own sweet spot.

Regards
   Brian

On 10-Sep-19 04:04, Christopher Wood wrote:
> _______________________________________________
> Ietf-and-github mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-and-github
>

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 10 Sep 2019 12:17:50 +1000

> "I am probably incapable of seeing what a truly light option looks 

:)

> IMNSHO it means using GH only as a repository for intermediate 
> versions, and using email for *all* discussion. Personally I find GH a 
> very inconvenient mechanism for discussion compared to email threads, 
> so I am at one end of the spectrum described at 
> https://github.com/ietf-gitwg/using-github/pull/15#issuecomment-526450315. I think Martin is correct that each WG could find its own sweet spot.

The intent was that the "light mode" described was exactly that, with the one addition being that issues could be recorded and tracked in GitHub.  They would absolutely NOT be discussed there.

As an aside, I also find GH to be a poor venue for discussion in many ways, but the advantage of having spent a lot of time being forced to do just that, I've found ways to make it tolerable.  It requires a fair bit of effort still.

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 10 Sep 2019 17:49:37 +1000

> [1] https://github.com/ietf-gitwg/using-github/pull/15

Based on the feedback received, I've made a few changes to smooth things out.  I think that this captures the lighter end of the scale a little better now.  Thanks to those who provided feedback, that was very helpful.

---

From: Bret Jordan <[email-masked]>
Date: Tue, 10 Sep 2019 13:51:54 +0200

There are parts that I like about GitHub for this kind of work, but discussions and collaboration are not them. Seeing everyone’s suggested text all at once is critical. 

In my utopian world you would have something _like_ GoogleDocs that was connected to github.  So you could do live collaboration and comments in the document and see everyone’s suggestions all at once, then have a way to push that markdown text to GitHub automagically.  This would give day-by-day, week-by-week, or draft-by-draft version tracking. 

Bret 

Sent from my Commodore 128D

PGP Fingerprint: 63B4 FC53 680A 6B7D 1447  F2C0 74F8 ACAE 7415 0050

> On Sep 9, 2019, at 10:36 PM, Brian E Carpenter <[email-masked]> wrote:
>

---

From: Martin J. Dürst <[email-masked]>
Date: Tue, 10 Sep 2019 23:37:07 +0000

> As an aside, I also find GH to be a poor venue for discussion in many ways, but the advantage of having spent a lot of time being forced to do just that, I've found ways to make it tolerable.  It r…

Glad to hear that (in the sense that it shows that it's not just me). Of 
the "ways to make it tolerable", if there's anything that isn't in the 
draft, please put it in. If you think some things are too 
person-specific, I'd appreciate if you'd at least explain them here.

Regards,   Martin.

---

From: "Martin Thomson" <[email-masked]>
Date: Wed, 11 Sep 2019 10:21:31 +1000

> person-specific, I'd appreciate if you'd at least explain them here.

I think that we're firmly into the "what works for you" territory here.  I have tweaked my email settings very little from the default and rely on email notifications.  I end up clicking on different links in those emails if I find that there is an action or response required.  The tiny "view on github" link at the bottom for discussion points, the names of changed files in new pull requests.  Then everything goes through the GitHub interface.  After that, it's mostly becoming familiar with the quirks of the interface.

There's a bit of a need for situational awareness, as every repositories have different rules and social contracts.  For instance, labeling rules for QUIC are unique; other projects also have different expectations on when things get merged or when to request review.  Part of why we're doing this is to help reduce the number of unique contexts, but I somehow think that this is an unavoidable human fact.

On situational awareness, the visual similarity of pull requests and issues leads to a tendency to treat them the same, which can turn out poorly.  I still manage to get that bit wrong often.

Learning to use #42 or "Closes #42" mentions for issues and pull requests is something that helps a great deal as it ties different threads together.  Just don't forget to include the "Closes #42" in the opening comment when making a pull request; because editing it in later doesn't do anything.  You probably can't overdo this much within a project, but I try to avoid going cross-project, just like with @mentions.  There is probably a whole social science lesson in the use of @mentions as well, but I'll spare people that, aside from an anecdote.  Don't use @-prefixes on labels in drafts or people will start pulling all sorts of people into conversations they aren't interested in.

I also write a fair number of pull requests, which are done mostly on the command line (some tips here: https://github.com/martinthomson/i-d-template/blob/master/doc/TIPS.md), though occasionally through the web interface.

As for reviewing, I've gained a love-hate relationship with the suggestions tool.  The tendency of GitHub to hide comments when the associated context changes is both good and bad.  Here, you have to be careful to dig through hidden comments on occasion.  Though the emails tend to hold a record of these hidden interactions, they also don't provide context for replies, so there is sometimes a bit of back-and-forth to get everything straight.  Most of reviewing is keeping context straight in your own head, which is a skill that the tool can't help with.  That and being civil and constructive, of course.

To provide contrast, here's the view from someone who uses GitHub even more than I: https://annevankesteren.nl/2017/11/using-github

---

From: "Christopher Wood" <[email-masked]>
Date: Wed, 11 Sep 2019 06:01:36 -0700

On Tue, Sep 10, 2019, at 12:49 AM, Martin Thomson wrote:
> Based on the feedback received, I've made a few changes to smooth 
> things out.  I think that this captures the lighter end of the scale a 
> little better now.  Thanks to those who provided feedback, that was 
> very helpful.

The new changes look great! Thanks, Martin, and everyone else who provided feedback thus far. I think moving from profiles to modes of interaction is an elegant way to describe the range of options by which folks can use GitHub their benefit. As a reminder, I plan to merge this change at the end of the week if there are no objections. 

As a followup question to the group, are there modes of interaction not described which should be included? If so, what are they, and what are some examples of Working Groups that use them?

Best,
Chris

---

From: "Salz, Rich" <[email-masked]>
Date: Wed, 11 Sep 2019 13:18:06 +0000

>I think moving from profiles to modes of interaction is an elegant way to describe the range of options by which folks can use GitHub their benefit. As a reminder, I plan to merge this change at the end of the week if there are no objections. 
  
Strong +1; nice wording.

---

From: "Christopher Wood" <[email-masked]>
Date: Fri, 13 Sep 2019 19:38:43 -0700

On Wed, Sep 11, 2019, at 6:01 AM, Christopher Wood wrote:
> The new changes look great! Thanks, Martin, and everyone else who 
> provided feedback thus far. I think moving from profiles to modes of 
> interaction is an elegant way to describe the range of options by which 
> folks can use GitHub their benefit. As a reminder, I plan to merge this 
> change at the end of the week if there are no objections. 

The PR is now merged. Thanks again to everyone who helped!

Best,
Chris