“Recruiting a New Maintainer for Your R Package: Tips and Strategies”

Read it in: Español.

Maintaining an open source package is rewarding work, but it’s also a lot of work.
Life and careers change, interests shift, and sometimes you simply don’t have the time or energy to keep working on your R package (and that’s okay!¹).
When that happens, one of the most responsible things you can do for package users, and for yourself, is to proactively look for a new maintainer or co-maintainer.

‘How do I recruit a new maintainer?’ is a question we hear a lot at rOpenSci.
Over the years, we’ve supported rOpenSci’s package authors through this transition, helping them connect with potential maintainers, clarify expectations around the role, and make handovers smoother and more sustainable.

In this post, we share practical tips and strategies to help you find people that can contribute and eventually take over your package, based on what we have learned through supporting maintainers of packages that are part of the rOpenSci suite.

Start early

The best time to start looking for a new maintainer is well before you actually need one, and the best place to look for a new maintainer is among existing contributors to your package.
For this reason, it’s a good idea to make planning for succession part of your package design and maintenance strategy from the beginning.

We encourage package authors to write a “life cycle statement” to describe your medium- to long-term vision of package development maintenance.
This can be just a few sentences in a CONTRIBUTING.md or README.md file that outlines your intentions for development, including how long you anticipate maintaining the package.
Even if the future is uncertain, this helps set expectations for yourself as well as potential contributors.

Make the package contributor-friendly

If you want to attract contributors who can become maintainers in the short- or long-term, your package needs to be approachable.
Our Dev Guide has an entire chapter on making packages contributor-friendly and we also have a Community Call “Set Up Your Package to Foster a Community”. Essentially, here are some key points to consider.

Ask yourself:

• Could a new person understand how to build, test, and release this package from your repo alone?
• Is there enough documentation to make contributing clear and friendly?

Adding or improving contributing guidelines is a great way to lower barriers to someone starting to act like a maintainer, even before they officially take on the role.
A good CONTRIBUTING.md can cover:

• How to set up a development environment.
• Workflow preferences: Issue before a Pull Request?
• How you prefer to receive PRs (e.g., one feature per Pull Request, must include tests, etc.).
• Code style or formatting guidelines.
• Any tests and how to run them.
• Any release process notes, including scripts, CI workflows, or manual steps you take to release a new version.

The more you have documented clearly, the less hard it will feel for someone to say “yes” to maintaining.

Depending on your ability to do so, you can also actively invest in growing contributors in a number of ways, for example:

• Mentor a beginning contributor through their first pull request².
• Host a “bug bash” or “documentation sprint” to encourage contributions. Our guide on organizing events for first-time contributors has resources to help you plan.
• Highlight “good first issues” and “help wanted issues” in your issue tracker.

These activities help expand your community of contributors and potential future maintainers, but will be most effective if you start well ahead of package handover, when you still have plenty of time and energy to invest.

Clarify what you’re willing (and not willing) to do

Potential new maintainers will wonder:

• Will you still be around for questions?
• Will you keep some level of control, or are you fully handing over? (i.e. are you looking for a co-maintainer or a new maintainer?

Be explicit.
For example:

• “I’ll help out and will be available during the transition, but plan to fully remove myself as maintainer once the transition is complete.”
• “I’m fully handing over maintenance but am happy to answer a few questions during the transition.”
• “I’d like to hand over fully and remove myself as maintainer as soon as possible.”

Setting clear boundaries helps others decide whether to volunteer and prevents misunderstandings later.

Open an issue: “Seeking New Maintainer”

Once you’ve decided to look for new maintainers or co-maintainers, and how you plan to be involve with the project in the future, communicate that clearly.
A visible first step is to open an issue in your repository dedicated to this topic.

Create an issue with a clear title, such as: “Seeking new maintainer(s)”, “New maintainer wanted”, “New co-maintainer(s) welcome” or “Looking for co-maintainers”.

In the body, you can include:

• What level of maintenance is needed (bug fixes only, feature development, documentation, etc.).
• What you’re looking for in a new contributor/co-maintainer:
  • Familiarity with the language/ecosystem?
  • Experience with testing or CI?
  • Comfort with releasing new versions?
• How to express interest (comment on the issue, email you, etc.).
• Any timeline you have in mind for the transition.

Optionally you can also explain Why you’re stepping back (at a high level: time, interest, job change, etc.).

This issue becomes the central place to discuss ownership changes and can later serve as a public record of the transition.

The rentrez package “New Maintainer(s)” issue is a good example of content, resources and followup conversation.

If your repo is on GitHub you can pin this issue and it will be shown at the top of the Issues tab, making it more visible to visitors.

Update your README to reflect the package’s status

The README is the other place that many users will see.
Add a short, highly visible note near the top, for example:

⚠ **Project status:** we are looking for a new maintainer.
If you're interested in helping maintain this package,
please see [this issue](link-to-issue) or
get in touch at your_email@example.com.

This message will:

• Sets expectations for users.
• Invites potential maintainers directly from your repo front page.
• It reduces the chance that someone assumes the package is abandoned without explanation (this blog post list the sources of information we advise people to check to understand package status).

You can also add a “Project Status” section in the README that gives a bit more context (e.g., “maintenance mode,” “new features unlikely without new maintainers,” etc.).

Reach out to existing contributors and power users

The best candidates for new maintainers are often already nearby:

• People who have submitted PRs.
• People who have filed useful, detailed issues.
• People you know use the package in their work.

You can:

• Send a short, polite email or message to a few people who have been especially active. Even if they say no, they may know someone else who would be a good fit.
• If you don’t have an email or other way of contact then tag contributors directly in the “Seeking new maintainer” issue, like the rentrez package maintainer did.

Announce it where your users are

Now that your package repo has clear messages and a place to express interest and a clear way of communicate with you, is a good idea to spread the word beyond your repo.

Consider posting a brief announcement in places where your users or contributors are likely to see it:

• Community forums, mailing lists, Slack/Discord channels relevant to your language/ecosystem.
• Social media (e.g., Mastodon, Bluesky, LinkedIn) using specific hashtags like #RStats.

For example, rOpenSci lists “New maintainers” issues in our website, we share them on our social media and in our newsletter.

Add a package startup message

At certain point, you can consider adding a startup message that informs users about the maintainer search.

In this message you can link to the “Seeking new maintainer” issue and encourage users to check it out if they’re interested in helping.

This is an aggressive move and may annoy some users, so consider it only if your package has a lot of active users and you haven’t had much luck finding a new maintainer through other channels.

Last resort: archive your package

If after a reasonable amount of time you were not able to find a new maintainer for your package,
you might have to make the difficult decision to archive it, on your code forge, e.g. GitHub – and CRAN if relevant.
Archiving the package puts an, albeit sad, end on your maintenance efforts.

Before archiving your package, take time to add an explanatory comment in all issues and PRs and to close them all.
You can create a new README to explain the new status.
You could add how to get in touch with you in case someone would like to revive the repository and take on maintenance.

Maybe your software will be replaced by other packages,
maybe someone will end up reaching out to you to request you transfer the repository to them,
maybe someone will create a replacement with the same name (and hopefully correct authorship and licensing if they reuse your code).
In all cases, you will have done your best and the fate of the R package is out of your hands.

It’s okay to step back

Stepping down from maintaining a package is a normal part of the open source life cycle.

By:

• Make plans for succession from the beginning,
• Making the package contributor-friendly,
• Clarifying your own boundaries,
• Opening a clear “Seeking new maintainer” issue,
• Updating your README,
• Reaching out to contributors,
• Announcing the search in the right channels,
• and if needed, archiving your package,

you give your project the best chance to continue, while also respecting your own time and energy.

Do you have any other tips or ideas?
Please share them.
We would love to know!

Continue reading: How to Recruit a New Maintainer for Your Package

Maintaining Open Source Packages: A Guide on Recruiting New Maintainers

Maintaining an open source package is a rewarding yet intensive task that demands an ample investment of time and energy. Career change, shifting interests, or simple burnout might lead to the decision to stop maintaining a particular R package. In such situations, the best way to facilitate a smooth transition and ensure package longevity is to recruit a new maintainer. This HTML article provides useful insights into preparing for this transition and shares effective strategies to recruit and equip new maintainers based on the experiences gathered at rOpenSci.

Begin Early

The best time to initiate the search for a new maintainer is well before one is actually needed. The potential contributors to the package consist of the ideal candidates for this role. Thus, planning for succession from the project’s inception is beneficial. Package authors should consider outlining a ‘life cycle statement’ summarizing their envisioned package development and maintenance plans. This step will clarify expectations for both the author and potential contributors.

Create a Contributer-Friendly Package

To attract potential maintainers, it is important to make your package more approachable. High-quality documentation is paramount in aiding a new person to understand how to build, test, and release the package. A contributing guideline that is effective covers areas such as how to set up a development environment, preferred workflows, PR guidelines, code style and formatting directives, and details about tests and the release process. Advanced planning can significantly lower the barriers to starting as a maintainer.

Grow Contributors

Active involvement in fostering a robust community of contributors can pay huge dividends in the long run. Mentoring, organizing contribution events, and highlighting beginner-friendly issues can inspire more people to contribute and consider becoming maintainers. Notably, these initiatives are most effective when started well in advance of package handovers.

Define Boundaries

Potential package maintainers need to know the level of involvement you plan to maintain post-transition. Being explicit about your future role helps volunteers decide whether they are the right fit for the job and also eliminates future misunderstandings.

Broadcast the Search

Harnessing the power of social media and community forums helps you reach out to a broader base of potential package maintainers. Posting announcements relevant to your community increases the chances of your search catching the eyes of interested contributors.

Ready the Package for Transfer

Several nuances can complicate package transfer to a new maintainer, such as poorly documented code and cluttered issue trackers. Efforts should be made to ensure that the package is clean and easy to comprehend for a smooth transition.

Archiving as a Last Resort

In the unfortunate event of being unable to secure a new maintainer, archiving the package is a practical, albeit painful, step. Ensure that an explanatory note reveals the reason behind the archive, close all active PRs and issues, and update the README file with the status. This will inform users of the package status and also invite people interested in reviving it to get in touch with you.

Conclusion

Stepping back from maintaining an open source package is a normal part of the software’s life cycle. Taking proactive steps such as planning for succession from the beginning, making the package contributor-friendly, and announcing the search can give your project the best chance to thrive, while also respecting your personal time and energy.

Read the original article