Set up your package to get the most out of your community

[stefaniebutland]

Topic

Set up your package to get the most out of your community

This topic is about making your package contributor/ feedback / collaboration-friendly and citable, and brings together some suggested community call content from:

• Make the most of GitHub for package development and R ecosystem knowledge (see comment below)
• How to write clear and compelling READMEs (see comment below)

Who is the audience?

Target audience is mid-level technical but ALL are welcome and everyone can learn from it.

Why is this important?

Example: rOpenSci can more easily help developers get what they want from the community if help wanted issues are clearly labelled

What should be covered?

See content copied below from other issues.

Suggested speakers or contributors

@maelle @mpadge

Resources you would recommend to the audience

• Dev guide Collaboration Guide
• Dev guide GitHub Grooming
• The Rt of good package READMEs, by @maelle

[stefaniebutland]

Suggested by @maelle in READMEs #11 and copied here

Topic

How to write clear and compelling READMEs.

Who is the audience?

Package developers
Maybe people interested in starting to contributed: docs are a good way to start and as an outsider you might write a better pitch for the package?

Why is this important?

I often read READMEs that could be improved and every package needs one, especially since the pitch that the README is can be re-used elsewhere.
Most potential users of a package have very little time so if the README loses them they won't try to use the package, or they'll lose time using a package that's not adapted to their needs (because the README was misleading).
It's also a topic closely related to "writing a good pre-submission inquiry".

What should be covered?

What's a good README, how to write one, who can give you feedback on it.
Also some tricks specific to R (usethis' README template, re-use of sections for the vignette).

Suggested speakers or contributors

• one of the editors or a reviewer who reviewed several packages could explain how they read READMEs.

Resources you would recommend to the audience

https://www.writethedocs.org/blog/newsletter-july-2019/#readmes-on-readmes-and-other-readme-related-resources
the discussion started by @noamross in ropensci/software-review-meta#55

The Rt of good package READMEs, by @maelle

[stefaniebutland]

Suggested by @maelle in Make the most of GitHub for package development and R ecosystem knowledge #6 and copied here.

Who is the audience?

Who might want to know this? What other groups or organizations might be interested?

So many people!

Why is this important?

Currently, the majority of rOpenSci packages are developed on GitHub

What should be covered?

Use rOpenSci repositories and people as examples,

• How to search on GitHub
• How to assess a repo for activity; number of stars, starred by people you trust; latest commit; issue activity; repo archived?; repostatus/lifecycle badge.
• How to use your GitHub's timeline
• How to browse repos based on topics, and conversely how to add topics to your repo
• How to make GitHub linguist results more representative of your package
• How to make your GitHub profile informative (avatar, company, website, pinned repos etc.)
• How to use the gh / usethis packages for some of the repo operations

Suggested speakers or contributors

• Maëlle Salmon

Resources you would recommend to the audience

• GitHub Grooming chapter of rOpenSci's Software Development Guide

[maelle]

After thinking about #22 I wonder whether this should be the same but developer-facing. So #22 might be about helping users, this one about helping contributors including you, future you, issue openers.

Some topics (some of them unsurprisingly are R-hub blog posts)

• COC, how does rOpenSci default COC file work (so mentioning default GitHub community files)
• What goes in a good contributing guide. How to set up a sandbox for your package development. See https://docs.ropensci.org/ruODK/CONTRIBUTING.html, https://docs.ropensci.org/osfr/CONTRIBUTING.html
• GitHub issue templates, see blogdown repo now cc @apreshill @cderv (I like the waving hand so much!) + issue guide by @yihui. Combining being clear about expectations whilst still being welcoming of contributions.
• Regarding making expectations clear the perspective of @Bisaloo and @mpadge would be interesting cf governance.md, support.md, roadmap ropensci/dev_guide#289
• Links in DESCRIPTION https://blog.r-hub.io/2019/12/10/urls/
• Maybe something about automation. https://blog.r-hub.io/2020/04/29/maintenance/ See also the PR GitHub Actions workflow use_github_action_pr_commands(), with this everyone's life is easier when someone submits a small fix in the README.Rmd or roxygen2 docs.
• NEWS file https://blog.r-hub.io/2020/05/08/pkg-news/
• Beyond your package... Tell your secrets/tips for other developers cf https://twitter.com/EmilyRiederer/status/1266431103948206080 by @emilyriederer, with an awesome example of this being https://gargle.r-lib.org/articles/articles/managing-tokens-securely.html by @jennybc (and also https://www.tidyverse.org/blog/2020/04/self-cleaning-test-fixtures/ by Jenny too, that became a vignette in testthat)

[stefaniebutland]

@annakrystalli is willing to talk about READMEs with @maelle! #22 (comment)

[stefaniebutland]

An issue Label-athon #23 would follow this comm call beautifully

[maelle]

Another topic, user surveys.

• https://twitter.com/antuki13/status/1192911393923764225 by @antuki
• https://twitter.com/juliasilge/status/1254879555979849729 by @juliasilge

[stefaniebutland]

New GitHub Discussions feature will influence this and the labelathon #23 so rOpenSci needs to figure out how we’ll advise folks, publish a technote, and then run this call.

[llrs]

I want to highlight the non-technical side of the community interaction:

• Finding the community (Social media, slack, mailing list, forums, conferences, websites, journals,...?)
• Fast response even if not complete (but it doesn't mean < 5 minutes!!)
• Reminders and acknowledgments
• Lower expectation on engagement (perhaps we tend to focus on super successful and active repositories, but most of them the activity is usually very low after the initial development)

[llrs]

Not sure if this is the place, but seeing also other initiatives of increase participation I would also suggest to start watching the repositories of packages you use/like in order to help maintainers:

• If there are no incoming issues: you lose nothing,
• If there are few and you can't help: minor inconvenience
• If there are many incoming issues: you will be able to sort, or propose workarounds given your knowledge
• If it is too much you can always unfollow the repo.

I've done this for a couple of packages and usually the volume of issues is low, so even if the maintainer does not answer you can help the user somehow.

[maelle]

right this is a great point and by watching one gets a good idea of the social conventions within the repo.

[stefaniebutland]

Really appreciate the perspective you have raised here @llrs.

Lower expectation on engagement (perhaps we tend to focus on super successful and active repositories, but most of them the activity is usually very low after the initial development)

yes!! If we emphasize only the successful and active, it can deter people by implying the bar is very high.

[Bisaloo]

This discussion reminds me of a question I would love to see addressed:

Someone opened a feature request in one of the package I'm maintaining. I was very excited at first, asked more information I needed to develop this feature but I still haven't gotten around implementing it.

This was a couple of months ago and I'm now afraid this user will not open new issues/feature requests in the future because they didn't see any result and might think this is useless.

So: how to keep the community involved (in the sense they are encouraged to submit bug reports / PR, etc.) when the development is not very active?

[llrs]

Perhaps signaling that the package is mature/stable? With one of the status or life cycle badge? Also even if I don't make much progress, I tend to reply with what I got (tried that, done X, half baked...).
If the user is responsive and has more comments then you might proceed otherwise, I might drop the issue/development.
But I also tend to leave open issues on my packages of ideas I have or possible directions I would like some day to improve. (Also not sure if this help or not.)

---

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.

[maelle]

ropensci/opencage#128 (comment) by @dpprdan

[maelle]

I was just thinking about the very precise issue labels by @wlandau, https://github.com/ropensci/targets/labels?page=1&sort=name-asc -- seeing the labels being put on issues might help users have realistic expectations (e.g. if your issue gets a "later" label).

[stefaniebutland]

Make Your R Package Easier to Cite, by Maëlle Salmon, Scott Chamberlain, Karthik Ram

[maelle]

A greetings GHA workflow to answer all new issues https://github.com/ropensci/UCSCXenaTools/blob/master/.github/workflows/greetings.yml

[stefaniebutland]

It's happening! Speakers and date confirmed.
Thursday, April 22, 2021 with Maëlle Salmon, Hugo Gruson, Steffi LaZerte, moderated by me Stefanie Butland

Details will be added to the landing page soon.

[stefaniebutland]

Summary blog post: https://ropensci.org/blog/2021/04/28/commcall-pkg-community/

Landing page with video and links to resources, incl collaborative notes doc: https://ropensci.org/commcalls/apr2021-pkg-community/

Social Labelathons are happening so folks can co-work on implementing some of these recommendations....or to hang out and work on their own package, but with company.