My Journey from Package User to Package Developer…

…and how to invite more users to take this journey

Hugo Gruson

grusonh
bisaloo

2021-04-22

My story

How I got started and fell in love with package development

My first contribution to an R package

pavo

A cohesive framework for parsing, analyzing and organizing colour from spectral data.

My first contribution to an R package

  1. Always on the look out for new features, avid reader of NEWS files
  2. Browsed the GitHub repo (https://github.com/rmaia/pavo)
  3. Noticed an open issue I knew how to solve
  4. Contacted the devs 😱 and offered a PR
  • I didn’t know the etiquette
  • I was afraid they would be offended I told them their package is not perfect

I continued contributing and eventually became an official maintainer

I felt empowered and started working on other R packages

How to facilitate this transition?

How to make sure projects are not simply open-source but community projects?

Many users think their feedback would not be valued

Twitter conversation with person 1 saying "Does anyone else refresh the page every 5 min after posting an issue on Github to see if the developer has answered, or am the only one that anxious?" and person 2 answering "Never because I know they don't actually want to deal with that shit. I feel lucky to ever get a reply."

usual pattern: something is broken/unclear -> give up and move on

we want: something is broken/unclear -> report the issue

How to foster a community around your package

Tips to make it less scary, more rewarding to give feedback / contribute.

Based on my experience -> very subjective.

Have confidence in your project and expect contribution

Screenshot from a GitHub comment at https://github.com/ropensci-org/community-calls/issues/21#issuecomment-767504258. Text reads: "Just an anecdote of my most active repository, in terms of issues. This repository is a 5 years old program we wrote for an assignment of my M.Sc. We didn't expect to be used outside the class, but as it was left on Github some people found it and used it. We realized people were using it when some people starred the repo, then some time later some users reported troubles they had with it."

Have confidence in your project and expect contribution

Screenshot from a GitHub comment closing a pull request with the following text: "Hi! Thanks for your suggestions. My apologies for responding so (!) late. For a very long time I didn't check pull requests, since I didn't really expect people to be interested enough in this project to want to contribute :) In the meantime, many of your suggestions or variations thereof have been already integrated in the code. The internal structure of the package has changed so much, that I will not merge this pull request. Best, [Maintainer name]"

Otherwise, we are running the risk of missing out on contributions.

By the time they saw my PR, it was out of date.

Show that you are available and want to communicate

  • If possible, allow to contact you through various platforms. On some projects, I noticed most feedback comes via email or twitter.
  • Share the recent changes (NEWS.md) of your package on these platforms
  • Open issues with unresolved questions (possibly tag as help-wanted)

All this creates engagement, feeling of a community.

Don’t let contributors work for nothing / feel ignored

  • Acknowledge feedback:
    • with a quick (even short) answer
    • with a shout-out / addition to contributors later

Don’t let contributors work for nothing / feel ignored

  • Acknowledge feedback

  • Always push your recent work in the public repo (don’t keep local branches)

Don’t let contributors work for nothing / feel ignored

  • Acknowledge feedback

  • Always push your recent work in the public repo (don’t keep local branches)

  • Share upcoming development (roadmap) of your package

Screenshot from Scott Chamberlain sharing notes from a (private) staff meeting on the public repository at https://github.com/ropensci/biweekly/issues/32

Don’t let contributors work for nothing / feel ignored

  • Acknowledge feedback

  • Always push your recent work in the public repo (don’t keep local branches)

  • Share upcoming development (roadmap) of your package

  • usethis::use_release_issue()

Screenshot from `usethis::use_release_issue()` documentation. The sentence `"It also helps watchers of your package stay informed about where you are in the process." is highlighted.

Reduce the workload

  • Disable failing tests
Screenshot of CI failure unrelated to the current pull request throwing off an occasional contributor

Reduce the workload

  • Disable unnecessary bots (e.g. coverage bot)
Screenshot from codecov-io bot on a pull request

To be honest, still not sure how to read it today…

But leave opportunities to learn

  • Avoid using the ‘Allow edits from maintainers’ feature
Screenshot presenting the "Allow edits from maintainers" feature

This can be demotivating. Similar to Carpentries’ advice:

“don’t grab the keyboard from a learner”

Letting the contributors fix their own mistakes is empowering.

Summary

  • Have confidence in your project and expect contribution
  • Show that you are available and want to communicate
  • Don’t let contributors work for nothing / feel ignored
  • Reduce the workload
  • But leave opportunities to learn