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
Picture by mostafa eissa on Pexels.
Words of an open-source professional
About 90% of bee species are solitary (not social)
Are package maintainers also solitary?
Picture by Pixabay on Pexels.
Community of a package?
You & other package authors, users, contributors.
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.
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.
Picture by Magda Ehlers on Pexels.
Some important words
Kindness 💐
Gracefulness 🩰
Emojis ✨
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!
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.
-
Start with
usethis::use_citation(); -
Amend it to suit your needs. Example from nasapower.
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.
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.
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
- On the website,
- as a default GitHub community file,
- Linked from the footer used for the main website and pkgdown websites.
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
urlfield. - 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.
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! 🕊️
Picture by Pixabay on Pexels.