Skip to main content

Maintainers

Best practices as maintainers


Create clear and welcoming documentation

Start with the basics: a comprehensive README file explaining your project, how to set it up, and how to contribute. Clear onboarding documentation should detail the mechanics of your project, what contributors can do, and which areas they should avoid. It's also highly recommended to include steps on how to get started.

Additionally, you can also create a CONTRIBUTION.md file to outline the contribution process. For example:

  • You can let contributors know that in order to be assigned to an issue, it is best to introduce themselves and share how they will approach the task.
  • If you have a telegram (or Discord) group - which we highly recommend - you can let contributors know to join the group for further discussions.
  • You can include a code of conduct to ensure a respectful community.

Label and detail your issues

To help contributors better understand the nature and complexity of tasks, use labels to categorize your issues.

This can be done by type (bug, feature, documentation…), difficulty (easy, medium, hard) and priority. We also advise you to use tags like “good first issue” to highlight introductory tasks for new contributors that are not yet familiar with your project. Overall, proper tagging ensures issues are easily discoverable, helping contributors find tasks that match their skills and interests.

When writing issue descriptions, be clear and detailed. Include the problem statement, steps to reproduce, expected behavior, and any relevant screenshots or logs. This helps contributors understand the issue fully and know how to help resolve it.

💡
A maintainer from Walnut that has successfully onboarded strong contributors suggests “to create issues and write descriptions in a way that someone new, who is not yet familiar with the repository or the project, can understand the bulk of it and knows what to do”.

Be responsive

After setting up documentation and issues, focus on onboarding new contributors. The key factor here is the responsiveness of maintainers. Contributors come from various backgrounds; some may be very talented but just starting out, so patience can be rewarding. However, if someone is wasting your time, it's okay to set boundaries. Keep communication open and guide contributors, especially during onboarding.

During onboarding, be reactive and answer questions promptly. This helps contributors get started and stay motivated. Regular follow-ups are recommended to check progress. If there's no progress, consider re-assigning the task.

We therefore highly recommend to create communication channels like Telegram or Discord to facilitate real-time communication and build a sense of community.

💡
You can encourage a friendly environment by asking contributors to introduce themselves for example, which can also help filter out less committed individuals. Publicly acknowledging and thanking contributors for their efforts also doesn’t hurt!
💡
Maintainers who have onboarded successfully new contributors highlight that it is important to be available to help, support and answer questions.

Assigning issues

Assign issues to those that you think the profile best fits the issue. On OnlyDust we have made this process easier by allowing contributors to apply for an issue they’d like to tackle and to give you more background info on themselves and how they would approach the problem.

Try to give people a chance. There may be a few beginners out there but that can be highly motivated and grow really fast. So even if a profile doesn’t fit 100%, give it a go.

And if when you follow-up you realise that it’s not going anywhere, you can re-assign.

💡
Please make sure that you have granted us with the latest GitHub permissions. This will allow you to assign issues smoothly and for us to automatically comment under your GitHub issue if a contributor comments on an issue outside of the platform.

review all applications easily

Have a better visibility of the contributor’s skills and motivation

Rewarding

All eligible contributions should be rewarded. We recommend $200 to $500 per day of work, adjusted by the quality of the work. Note that it can also be much higher if you deem it important and it be as small as the equivalent to $80 for a small task to much higher.

Same thing for rewarding maintainers who spend time to review code and work. Calculate according to how much time you spent per day to write up issues, review and onboard.