Introduction
This guide outlines strategies for mentoring and supporting new maintainers within the AsyncAPI project. By documenting and adopting these strategies, we aim to promote long-term sustainability, reduce the burden on existing maintainers, and ensure new maintainers thrive in their roles.
As we continue to emphasize the importance of onboarding new maintainers, we must also provide them with the necessary tools, guidance, and support to ensure their success. While this document is primarily intended for new maintainers, it also serves as a valuable resource for existing maintainers, contributors, and the broader AsyncAPI community.
How to Do Mentoring to Get the Best Results
The goal of mentoring is to guide, support, and empower, not to micromanage. A successful mentorship is built on clear expectations, shared goals, and consistent communication.
Here are strategies that help new maintainers onboard successfully:
-
Start with clear goals: Help new maintainers define what success looks like in their role. Set achievable short-term and long-term goals together.
-
One-on-One Mentorship: Pair new maintainers with experienced ones for dedicated guidance. Build trust and encourage open, judgment-free conversations.
-
Shadowing: Let new maintainers observe key activities such as PR reviews, issue triaging, and community calls. This builds confidence and real-world context.
-
Encourage questions early and often: Make it clear that questions are welcome at any time, and not only during meetings. Create a safe space for learning.
-
Recorded Walkthroughs: Share video walkthroughs of project architecture, common workflows, or release processes. These become reusable training resources.
-
Regular Check-Ins: Weekly or bi-weekly syncs are useful for tracking progress, giving feedback, and offering encouragement. These meetings don't replace async communication, both are important.
-
Use challenges as learning opportunities: When mistakes happen (they will!), treat them as learning moments. Debrief together and guide the next steps.
-
Celebrate milestones: Acknowledge small wins and progress. Positive reinforcement helps build momentum and confidence.
💡 Mentoring is a commitment. It requires patience, consistency, and empathy. Be supportive, but also encourage ownership and independence.
Roles and Responsibilities of a Maintainer
Maintainers are trusted stewards of the project. Their responsibilities include:
-
Guiding the technical direction of the project
Example: Propose and discuss new features, decide on major architectural changes, or push forward RFCs (Request for Comments). -
Reviewing and resolving issues and pull requests
Example: Offer constructive feedback on a contributor's PR, merge well-tested contributions, or close stale issues with a clear reason. -
Managing CI/CD workflows and automation
Example: Configure GitHub Actions to run tests or deploy documentation automatically when changes are pushed. -
Enforcing code quality and architectural consistency
Example: Ensure that all merged PRs follow the linting rules, use proper folder structures, and adhere to design patterns agreed upon by the team. -
Maintaining and improving documentation
Example: Update the README when project setup changes, or add diagrams and examples to explain new features in the docs. -
Identifying and mentoring future maintainers
Example: Invite an active contributor to shadow PR reviews or gradually assign them bigger responsibilities like triaging issues. -
Supporting contributors and nurturing participation
Example: Answer a contributor's question in Slack, help them understand project conventions, or guide them through their first issue. -
Recognizing and celebrating contributions
Example: Publicly thank contributors in Slack or GitHub, highlight notable contributions in community meetings, or nominate someone for GitHub Stars.
Being a maintainer is more than just fulfilling tasks; it's about ownership and leadership.
You're not just reviewing PRs; you're shaping the future of the project. Whether it's unblocking a stuck contributor, advocating for improvements in the roadmap, or leading releases, maintainers play a crucial role in keeping the project active and healthy.
Maintainers also lead by example not only by solving issues, but also explaining why decisions are made, and guiding others to think critically and collaboratively. It's about striking a balance between technical excellence and community empathy.
Ultimately, maintainers are the glue that holds everything together, ensuring smooth operations, maintaining community trust, and advancing AsyncAPI's vision.
Best Practices for Maintainers
Keep these best practices in mind as you mentor and lead:
-
💬 Communicate clearly and publicly. Use public channels so others can learn and contribute.
-
⚙️ Automate what you can. Use bots and CI to handle routine tasks and reduce manual overhead.
-
📝 Write things down. Document decisions, workflows, and open questions.
-
🧑🏫 Be an active mentor. Provide feedback, do code walkthroughs, and encourage learning moments.
-
🙌 Inspire contribution. Invite others to take ownership of issues or features.
-
✅ Set a high bar for quality. Encourage contributors to write clean, tested, and thoughtful code.
-
📅 Show up consistently. Attend meetings or community check-ins to stay aligned.
-
💚 Avoid burnout. Ask for help when needed and model healthy work boundaries.
"You are not just reviewing PRs, you are building people."
— Adapted from GSoC Mentor Guide
