Last Thursday we held a Community Call discussing how to set up a Package to Foster a Community.
🔗 Summarizing the community call
Scientific software development – and with that R packages – is a community effort. While there are often just a handful of developers maintaining an R package, the development really starts to thrive when users start to contribute.
In principle, every open source package has an open invitation to contribute. The question is how this invisible rule can be turned into something more explicit (and less intimidating) so that users who want to contribute can do so easily and feel welcomed and at ease. This brings us to the topic of rOpenSci’s last community call.
Over the course of an hour, the three speakers emphasised various aspects of an R package that can be used to invite code contributions, and to manage expectations of both users and contributors, for example through a contributor guide, or through explicit instructions how to use issues on GitHub. Speakers also emphasised the importance of the “soft skills” of package maintainers, especially the importance of considering the effect of how package maintainers interact with contributors, such as fostering opportunities to learn, being kind when saying “no”, and always acknowledging contributions.
The three speakers were:
- Maëlle Salmon, a research software engineer, part-time with rOpenSci
- Hugo Gruson, a research software engineer and evolutionary biologist
- Steffi LaZerte, an R programming consultant, and part-time community assistant at rOpenSci
A package has many different actors – the package authors, the users, the contributors – and they may act and interact with each other in a variety of ways.
Each role has slightly different needs. Everyone wants a better, well-maintained package. But the authors may want citations and grateful users, the users themselves may want certain features, and the contributors might seek recognition.
Also, authors may need help in tackling issues and who better to help than someone with a user perspective!
Before diving into tips, Maëlle talked about how authors can improve their communication with contributors. One of the best ways to encourage and retain contributors is simply being kind. But emojis can also be a great tool to compensate for lack of nuances, for example, when having to say “no”.
Maëlle then suggested three steps to foster a community for a package:
🔗 1. Define rules & standards for your package
Some “rules & standards” include:
- Add a code of conduct:
- Add a citation to help people to cite your package:
- Add a contribution guide: store as
CONTRIBUTING.md, add style preferences, process preferences, scope lined out, how you prefer testing to work.
🔗 2. Add them in publicly visible places
🔗 3. Help users & contributor find them
Add links everywhere: in GitHub repository and pkgdown website.
Hugo spelled out the obvious – that every package contributor is a) a user first and b) starts out as a beginner.
Hugo himself followed his favourite package where at one point he noticed something that needed fixing. So he fixed it – an intimidating process at first. But he repeated that, and after some time became an official maintainer.
Hugo’s talk focussed on how to facilitate the transition from user to contributor and suggested five tips for package maintainers to make contributing less scary:
🔗 1. Have confidence in your project + expect contribution
(if you don’t, you may miss messages from users)
🔗 2. Show that you are available and want to communicate
Use GitHub, Twitter, email for that. For example, tweet the NEWS file after a release.
🔗 3. Don’t let contributors work for nothing / feel ignored
- Mention the name of the person.
- Keep them in the loop.
- Always have the latest version on GitHub.
- Share a roadmap of project.
🔗 4. Reduce workload for contributors
- Disable failing tests.
- Disable unimportant bots (Hugo mentioned the notoriously confusing coverage bot)
🔗 5. Leave opportunities to learn
In GitHub, don’t abuse “allow edits from maintainers”, as this is demotivating (“Don’t take the keyboard from the learner”, Carpentry)
Steffi found the low-hanging fruits in making packages more contributor-friendly – GitHub issues!
GitHub issues can be labeled, and labels can be searched by users who want to become contributors but are maybe too shy to tackle an unlabelled issue.
So why not label some well-defined issues with
"help wanted", a clear open invitation to users.
Other options for labeling include:
Because package maintainers rarely have time for this, the idea of a social label-athon – labeling issues in a social setting – was born and is happening for the first time on Thursday 29 April 2021 at 16:00 UTC (sign up).
At this Social, participants will get together on Zoom, have some time to meet and greet, and will then spend time co-working (working at the same time on different projects) to make their repositories more contributor-friendly.
The idea is to make this relatively low-priority task a bit more fun, and to offer a chance to socialize with others in the rOpenSci community.
(Rob Crystal-Ornelas) Many of the suggested files have standardized names, is this convention or does it enable features on GitHub? (document)
(Athanasia Mo Mowinckel) Are there any best-practices in terms of formatting NEWS.md files? (document)
(Silvia Canelón) What kind of positive response did Hugo notice after sharing NEWS.md on social media? (document)
(Jeremy Selva) The easystats R package has this cool feature to classify issues. Any idea how to do this? (document)
(Sina Rüeger) Maëlle, you mentioned badges for README, can you elaborate on that? (document)
(Ella Kaye) In terms of encouraging users to contribute, do you have any advice on how to leverage twitter to get attention for it? (document)
(Sina Rüeger) Now that there will be labelathons in co-working mode, could there be a time where some issues are tackled in co-working fashion, similar to a tidydev day? (document)
(Wayne Smith) Is there a convention for where to put ORCID–readme.md? Citation? or? (document)
(Valentina Costa) For a released package that is still a work in progress do you suggest immediately adding contributors to your contributor list? (document)
(Janani Ravi) Is there a good way to indicate in contributing guidelines that contributions may result in co-authorship/acknowledgements in the subsequent publication? (document)