Tuesday, September 19, 2023 From rOpenSci (https://ropensci.org/blog/2023/09/19/help-wanted/). Except where otherwise noted, content on this site is licensed under the CC-BY license.
Maintaining a package can be a lonesome activity, which sometimes poses a problem if you prefer team work or if you encounter a very thorny-for-you problem. Beside belonging to a supportive community of maintainers (like rOpenSci 😉), for collaborative help and commiseration you can try to build a community of contributors around your package! In this post, we’ll explore one tool helping you towards that goal: “help wanted” issues, with which your repository could attract and retain new developers! We’ll discuss what “help wanted” issues are, four steps for soliciting external help, and remind you that this can be a beneficial process, even if you don’t end up attracting help.
Note that this post uses GitHub-specific terminology like issues and labels. If you use GitLab or another git platform, there’s probably an equivalent. 🙂
“Help wanted” issues are issues for which you’d accept or need external contributions.
They are labelled with the community standard “help wanted” label (example; optionally with an emoji, if you ran usethis::use_tidy_github_labels()).
For some of them, if they’re not too involved, or if they’re a good onboarding ramp to your codebase, you can also use the “good first issue” label.
Next we’ll cover four steps for soliciting external help.
Sometimes a hurdle you are unsure how to handle looms ahead on the road to your next development milestone. At this stage you can either
For instance, when working on the tinkr package, Maëlle opened a very specific issue that did end up getting miraculous outside help.
You can also add the “help wanted” label to a bug report or feature request someone else opened in your package! With a bit of luck, the issue creator themselves will be able to participate 🎉 .
Now sometimes there are some upkeep or enhancement ideas you have for your package for which you don’t have time right now, or which are not urgent. For instance, updating the testing infrastructure to testthat third edition, or adding terra support to a spatial package. By listing them in your issue tracker,
Once you have a topic in mind, make the issue title and text as clear as possible. Even if you are the one fixing the issue in the end, future-you will be happy you didn’t jot down an undecipherable comment. Link to resources as needed, and make sure to include context. Approach writing an issue in your own repo the same way you would in a repo that isn’t yours: challenge description, desired outcome, trade-offs, etc.
Beyond efforts in the individual issue, it’s crucial to have a contributing guide underlining anything that is good to know about contributing to your package: tooling used, style and design preferences.1 Do not duplicate external resources, point to them instead. Try to be a bit flexible so you don’t overload or scare off contributors by having requirements which are too strict: you can probably finish off PRs yourself, or teach them little by little.
First of all, for rOpenSci packages “help wanted” issues are broadcast to the community via the website and social media posts!
You can also share it within your own networks: rOpenSci slack workspace, your social media, a local R User Group communication channel, etc.
You can also consider leveraging hack-a-thon events like Hacktoberfest for instance (if you add the “hacktoberfest” topic to your repository), but with really large events like this you can’t necessarily count on someone discovering your tiny issue in that sea of issues.
If someone answers in the issue or open a PR, try to be somewhat responsive. Check your settings allow you to be notified of issue comments and PRs, you might need to watch your repository.
Acknowledge contributions generously! 🙏🏼
Even if you wrote an excellent issue, it just might not get picked up. In that case, consider broadcasting again, ask for general tips from your fellow maintainers, and consider applying for funding (therefore time, either yours or an external contractor’s) for your maintenance efforts. See for instance the R Consortium’s two yearly calls for proposals.
Even if no one tackles the issue in the end, going through this process can be helpful as it gives you a chance to think through this issue in detail and to consider possible resolutions, which can help you solve your problem your own. Also, a well-documented issue is a great way to document your decisions about your software transparently and can help future users and contributors understand the reasons for your choices.
Opening “help wanted” issues can be a way to grow your package’s contributor community. They might be a better door to contribution than less specific issues with a laundry list of needed tasks, as they’re less overwhelming. Contributors might fix one “help wanted” issue and then leave, or go ahead and solve more of them. Sometimes a conversation in the comments can help you find a solution even if a contributor doesn’t submit a PR.
As a contributor, always comment in an issue before tackling it, to ensure it’s still up-to-date, and that no one else is preparing a duplicate PR right now! How vexing would that be to work for nothing.
For further thoughts on how to foster a community around your package, you might enjoy the recording and materials on our past community call on the topic.
You might find https://contributing.streamlit.app/ helpful, but another way to improve your contributing guide is to keep amending it based on your experience with new contributors. ↩︎
