GitHub Concierge/Ambassador Program

[jennybc]

This could be just a group discussion or could be concretely developed as an actual project. Or something in between.

Consider an R package developed on GitHub. The issues are an important place for users and developer to interact. Problems that can aggravate one or both parties:

• Timeliness of response (or lack thereof). Typical scenario: user opens an issue or PR, hears nothing for weeks or months, feels like they're speaking into the void. But can also be developer putting something back in user's court and ... crickets.
• Quality of issue or PR. Typical problems here are bug report that lacks a reprex or formatting that is so terrible it inhibits readability.

These problems are most acute for developers or developer groups with lots of packages and lots of users.

Such a project could have a GitHub Concierge or Ambassador. Or more than one! This person would watch the repo, literally, and lightly tend it. The mandate is not to close issues or fix bugs, but rather to provide an appropriate initial response quickly and, when necessary, work with poster to create a better issue.

I think this can be filed under "on-ramps". It's a good way for the development-curious to lend a hand, while observing development cycles first-hand. It also makes GitHub a friendlier place for newcomers, directly and indirectly.

A central program would be useful for training, establishing norms, discussion. Then developers/developer groups could choose to sign on.

This is motivated by my involvement with Forwards, R-Ladies, rOpenSci, and the tidyverse.

[stefaniebutland]

GitHub community management!

[jules32]

Very cool idea Jenny.

I saw this article in Slate today that is somewhat relevant: "We Need a GitHub for Academic Research". I don't agree that academics need their own GitHub, but I do think we need to make it easier to get academics onboard with using GitHub. Maybe concierges or ambassadors is the way to go!

[batpigandme]

I really like this idea— I know I've definitely refrained from either pointing out a possible issue, or submitting a PR for a lack of knowing the git "etiquette" in a given context. (But, sample size…just me)

[jennybc]

I also went through a phase where I was watching package repos I cared and knew about. And I recognized duplicate issues, knew of features that were already in devel, created more minimal reprexes, etc. but wasn't sure if it was my place to chime in. If I had had some sort of official blessing from the maintainer, I would have been happy to help out.

[jennybc]

This group could maintain a central resource re: what makes an issue (in)effective (with real examples!), PR etiquette, etc. Participating repos/package can then point back to this from README, CONTRIBUTING.md, and saved replies.

If this were a project, one of the tasks is to figure out how much a concierge can do with regular read permission on a repo (vs write or admin) and to test drive + document some of the workflows.

[batpigandme]

@jennybc As meta as it seems, feedback on feedback can be super helpful. Though GH PRs etc are much less involved, I never would have known where to begin (or even how) in package reviewing without the rOpenSci onboarding resources, and the active help of non-package-writing guides (in my case, @noamross).

I also wonder if there might be a good way for package/repo authors to point out less technical areas where they might want help and/or an extra set of eyes. (Possibly separate, and/or not worthwhile, but this was an idea that came up after I asked about GH spelling correction etiquette on twitter a few months back).

[hadley]

@batpigandme one easily place to start would be a guide on how to make changes to the documentation. This would discuss the basics of how most documentation is generated (i.e. with roxygen) and cover how to navigate backwards from a problem in ?xyz to the root roxygen comment. It would also need to cover a few github basics, like how to automatically close the related issue with a correctly formatted commit message.

I don't think any maintainer would have problems accepting an unsolicited PR for typos and other minor changes, but we'd need to point out that before embarking on major changes you should start by filing an issue to make sure the maintainer is on board with your changes before you start the work.

It might be possible to include changes to bookdown books in the same document.

That said, this feels a little orthogonal to the ambassador/concierge program, although they both share similar goals of empowering the less experienced R developer. One way this might interact in practice is that an ambassador might spot an issue that just reports a typo in the documentation, and then could help the submitter do a pull request themselves. I would also imagine that ambassadors would be more active than average in submitting minor fixes.

[batpigandme]

@hadley Great idea re. roxygen and documentation generation. I've been going through a few posts/slide decks on the basics of R-package-writing, most of which include something on this (e.g. was looking at Karl Broman's Writing documentation with Roxygen2 this morning). But understanding the mechanics of how docs work would be helpful outside of the context of package creation— certainly for contributing to others' work more effectively.

[maelle]

For info, not a concierge thing but something related to empowering new developpers, @LucyMcGowan's contributr for finding issues that were identified as beginner-friendly (in rOpenSci repos) such as this one.

[jennybc]

I've made a new issue for #47 First Timers Only Issues.

[cwickham]

(Coming over from Forwards where Jenny linked to here) @hadley @batpigandme I think that kind of guide would be great! I also think it would be even greater if that was just the first in a series of guides that built on each other.

Perhaps the next guide would be about contribution to code including communicating intent with the maintainer/ambassador, forking, testing, keeping commits clean, what it means for a package to use travis etc. That seems like a lot now I write it, which means it's a big step for people and they could probably really use a resource that guides them through it.

[LucyMcGowan]

@cwickham that sounds a lot like what we are chatting about in #47 too - @maelle & I have been brainstorming guides for contribution to code a bit through an app we're calling contributr

[batpigandme]

@cwickham I like that idea, as well as what @LucyMcGowan and @maelle are building over on #47 — in fact, I think they could go together quite nicely.

[maelle]

yes at some point we wondered about what to point people to in the app, for Travis there's this blog post and for R packages beginners like this one / there is material & links in these slides but a brand-new guide with "everything" sounds useful!

[cwickham]

@maelle Yeah, there are a lot of really nice guides on how to write a package, but I think that can be overwhelming when you just want to contribute. I think a "What a contributor needs know about writing a package" guide might be more accessible.

[maelle]

@cwickham oooh ok I see, awesome!

[batpigandme]

@maelle There's an embarrassment of riches, but curation is always key (imho). I think the "writing a package" bit might scare away the novice (e.g. yours truly), so I like the idea of a modular, or specified approach (i.e. what @cwickham suggested above)!