Set Up Your Package to Foster a Community

Maëlle Salmon 🏠 https://masalmon.eu 🐦 ma_salmon

Licence CC-BY-SA

How we might imagine open-source development

Bee swarm

Picture by mostafa eissa on Pexels.

Words of an open-source professional

Screenshot of Scott Chamberlain's GitHub README including the fun fact 'About 90% of bee species are solitary (not social)'

About 90% of bee species are solitary (not social)

Screenshot of Scott Chamberlain's GitHub README including the fun fact 'About 90% of bee species are solitary (not social)'

Are package maintainers also solitary?

Bee flying near yellow flowers

Picture by Pixabay on Pexels.

Community of a package?

You & other package authors, users, contributors.

Two bees on lavender

Picture by Pixabay on Pexels.

People who create visualizations with ggplot2 are the most important members of the community; without these users, this project would have no purpose.

ggplot2 governance file 🐝

Everyone who contributed to drake is part of targets. Four years of pull requests, issues, rOpenSci discussions, RStudio Community posts, Stack Overflow threads are materializing in this new suite of tools.

Will Landau in https://ropensci.org/blog/2021/02/03/targets/ 🐝

Community of a package?

Everyone wants a better, well-maintained package.

Everyone wants something different for themselves.

  • You might want citations, thanks.
  • Users might want some features.
  • Contributors might want recognition.
Bee flying over a pink flower

Picture by Magda Ehlers on Pexels.

Some important words

Kindness 💐

Gracefulness 🩰

Emojis ✨

Bee on a sunflower

Picture by Karol Wiśniewski on Pexels.

Example of a kind answer with an emoji

I think if you want this, you could just include it in a vignette. Unfortunately, I don’t think it’s a good fit for this package: developing good software requires relentless focus, which means that we have to say no to many good ideas. Even though I’m closing this issue, I really appreciate the feedback, and hope you’ll continue to contribute in the future 😄

Hadley Wickham answering a pkgdown issue.

3 steps for setting up your package & foster a community

  • Think about rules & standards for your package.
  • Add them in the expected places.
  • Help users & contributors find them!
Bee flying towards a white flower

Picture by Lukas on Pexels.

Code of Conduct

.github/CODE_OF_CONDUCT.md. Example from (non-rOpenSci) opendatatoronto. usethis::use_code_of_conduct().

rOpenSci had a whole community call on the topic!

How do I Create a Code of Conduct for my Event/Lab/Codebase?, With C. Titus Brown, Pauline Barmby, Safia Abdalla.

CITATION file

inst/CITATION.

Blog post: Make Your R Package Easier to Cite

Contributing guide

.github/CONTRIBUTING.md. Example from wateRinfo.

  • Style preferences? Infrastructure like roxygen2?

  • Process preferences? Issue before a PR?

  • Scope? E.g. in skimr.

  • Sandbox account creation? Mocking in tests? Use links to external docs.

Bee upside down

Picture by Kat Jayne on Pexels.

Special note on code style

  • Use a popular one? Tidyverse?
  • Make it a configuration i.e. something used by lintr, styler?
  • Teach people? Or fix it yourself?

“BTW, I’ll make some cosmetic changes before I merge this PR, and you don’t need to worry about my style preferences.”

Yihui Xie commenting on a PR of mine to blogdown.

Other “community health” files

With a special role for GitHub: SECURITY.md, SUPPORT.md.

With no special role for GitHub: GOVERNANCE.md.

Bee on a yellow flower

Picture by Pixabay on Pexels.

Default GitHub community files?

In a <account or organization>/.github repo:

  • Code of Conduct;
  • Contributing guide;
  • Issue templates.

They can be overridden.

Code of Conduct, rOpenSci

How do users & contributors find your package

How would they find information about contributing?

Links everywhere

Not only good for setting up your repo for more contributions. 😁

Development repository URL, pkgdown website URL.

  • DESCRIPTION.
  • Package-level manual page (info from DESCRIPTION) via usethis::use_package_doc().
  • pkgdown configuration url field.
  • GitHub repository description.

GitHub README

“Personally, I take a “belt-and-suspenders” approach and still put citation things in the README.”

Noam Ross, rOpenSci forum.

  • Explicit sections about help, contributing, citing.

  • Badges? As a complement to text? (e.g. cpp11 README)

GitHub issues

Example 1: See links to the code of conduct & contributing guide.

Example 2 (source): GitHub issues templates / configuration. Don’t add too many choices.

You can even save replies for your account!

pkgdown website

Example from skimr. Example from (non-rOpenSci) openintro.

  • README content, Markdown files rendered.
  • (pkgdown development version) Sidebar links/text.
  • (pkgdown development version) Footer links/text.
  • rOpenSci packages have rOpenSci footer.
Bee on an orange flower

Picture by David Hablützel on Pexels.

Conclusion

  • Summarize the rules and quirks of your package;
  • Store them in standard places;
  • Help users & contributors find them.

And the whole time, be kind! 🕊️

Bee on a blue flower

Picture by Pixabay on Pexels.