docs: add onboarding maintainers guide #1638
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Aahil13
requested review from
quetzalliwrites,
derberg,
asyncapi-bot-eve and
thulieblack
as code owners
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
Aahil13
changed the title
Aahil13
changed the title
14 tasks
bandantonio
suggested changes
Jan 13, 2025
Comment on lines
5
to
9
| This guide is designed to provide you with everything you need to begin your journey as a maintainer within the AsyncAPI ecosystem. Whether you’re managing workflows, mentoring new contributors, or ensuring that the project stays on track, your role is essential to the success of the community. | ||
|
|
||
| Maintainers are the backbone of any open-source project. You help ensure that processes run smoothly, contributors are supported, and the project evolves sustainably. This guide will help you navigate your responsibilities, from managing code contributions to creating workflows and fostering a healthy, productive community. | ||
|
|
||
| Before we go into getting you started, let's try and clarify just *who* a maintainer is. |
There was a problem hiding this comment.
The introduction has some overlapping statements basically repeating the same things. I would suggest rewriting the following two paragraphs into a shorter version, something like this:
Suggested change
| This guide is designed to provide you with everything you need to begin your journey as a maintainer within the AsyncAPI ecosystem. Whether you’re managing workflows, mentoring new contributors, or ensuring that the project stays on track, your role is essential to the success of the community. | |
| Maintainers are the backbone of any open-source project. You help ensure that processes run smoothly, contributors are supported, and the project evolves sustainably. This guide will help you navigate your responsibilities, from managing code contributions to creating workflows and fostering a healthy, productive community. | |
| Before we go into getting you started, let's try and clarify just *who* a maintainer is. | |
| This document provides you with guidelines about everything you need to know to begin your journey as a maintainer within the AsyncAPI ecosystem. Maintainers are the backbone of any open-source project, helping with different activities that help the project to stay on track and foster a healthy, productive community. |
The idea here is to give a high-level introduction to the role without overwhelming readers with diving deep into too much of context right from the start about responsibilities and activities (They were partially repeated twice in these paragraphs and later on within the dedicated section: Who is an AsyncAPI Maintainer).
Comment on lines
13
to
23
| A maintainer is an individual who plays a crucial role in overseeing and guiding the development and growth of an open-source project. As a maintainer for AsyncAPI, you will manage pull requests, resolve issues, enforce coding standards, and ensure the community thrives by helping contributors. | ||
|
|
||
| As a maintainer, you'll be responsible for: | ||
|
|
||
| - Overseeing the technical direction of the project | ||
| - Managing workflows and GitHub Actions to automate tasks | ||
| - Identifying and appointing new maintainers | ||
| - Mentoring new contributors and helping them navigate their journey | ||
| - Recognizing and rewarding contributions to foster community engagement | ||
|
|
||
| Basically, you're the *glue* that holds the project together and ensures that everything runs smoothly. |
There was a problem hiding this comment.
Suggested change
| A maintainer is an individual who plays a crucial role in overseeing and guiding the development and growth of an open-source project. As a maintainer for AsyncAPI, you will manage pull requests, resolve issues, enforce coding standards, and ensure the community thrives by helping contributors. | |
| As a maintainer, you'll be responsible for: | |
| - Overseeing the technical direction of the project | |
| - Managing workflows and GitHub Actions to automate tasks | |
| - Identifying and appointing new maintainers | |
| - Mentoring new contributors and helping them navigate their journey | |
| - Recognizing and rewarding contributions to foster community engagement | |
| Basically, you're the *glue* that holds the project together and ensures that everything runs smoothly. | |
| A maintainer is an individual who plays a crucial role in overseeing and guiding the development and growth of an open-source project. As a maintainer for AsyncAPI, you'll be responsible for: | |
| - Overseeing the technical direction of the project | |
| - Helping with reviewing and resolving issues and pull requests | |
| - Managing workflows and GitHub Actions to automate tasks | |
| - Enforcing coding standards | |
| - Identifying and appointing new maintainers | |
| - Mentoring new contributors and helping them navigate their journey | |
| - Recognizing and rewarding contributions to foster community engagement | |
| Essentially, you serve as a person that binds the project together and guarantees that everything runs smoothly. |
Comment on lines
31
to
37
| - **Join existing PR reviews**: If you're not sure where to start, begin by reviewing open [pull requests](https://github.com/asyncapi/community/pulls). This will give you an understanding of the code and where your contributions might fit in. | ||
|
|
||
| - **Look for "*good first issue*" labels**: These [issues](https://github.com/asyncapi/community/issues) are beginner-friendly and will help you get familiar with the project’s structure. Additionally, you can check out the [#97_bot-github-new-issues-prs](https://asyncapi.slack.com/archives/C01J06RL10X) channel on Slack for new issues and PRs. | ||
|
|
||
| - **Participate in live streams**: AsyncAPI maintainers sometimes host [live streams](https://www.asyncapi.com/community/events) where they walk through parts of the project. You can request a session on the specific area you want to contribute to. | ||
|
|
||
| > **NOTE**: Make sure whatever issue you pick isn't marked "Do-not-merge" else your PR won't be merged. |
There was a problem hiding this comment.
Suggested change
| - **Join existing PR reviews**: If you're not sure where to start, begin by reviewing open [pull requests](https://github.com/asyncapi/community/pulls). This will give you an understanding of the code and where your contributions might fit in. | |
| - **Look for "*good first issue*" labels**: These [issues](https://github.com/asyncapi/community/issues) are beginner-friendly and will help you get familiar with the project’s structure. Additionally, you can check out the [#97_bot-github-new-issues-prs](https://asyncapi.slack.com/archives/C01J06RL10X) channel on Slack for new issues and PRs. | |
| - **Participate in live streams**: AsyncAPI maintainers sometimes host [live streams](https://www.asyncapi.com/community/events) where they walk through parts of the project. You can request a session on the specific area you want to contribute to. | |
| > **NOTE**: Make sure whatever issue you pick isn't marked "Do-not-merge" else your PR won't be merged. | |
| - **Join existing PR reviews**: If you're not sure where to start, begin by reviewing open [pull requests](https://github.com/pulls?q=is%3Aopen+org%3Aasyncapi+sort%3Aupdated-desc+archived%3Afalse+) within the organization. This will give you a high-level understanding of the projects and where your contributions might fit in. | |
| - **Look for "*good first issue*" labels**: These [issues](https://github.com/issues?page=1&q=is%3Aopen+org%3Aasyncapi+sort%3Aupdated-desc+label%3A%22good+first+issue%22) are beginner-friendly and will help you get familiar with the project’s structure. Additionally, you can check out the [#97_bot-github-new-issues-prs](https://asyncapi.slack.com/archives/C01J06RL10X) channel on Slack for new issues and PRs. | |
| - **Participate in live streams**: AsyncAPI maintainers sometimes host [live streams](https://www.asyncapi.com/community/events) where they walk through parts of the project. You can request a session on the specific area you want to contribute to. | |
| > [!NOTE] | |
| > Make sure the issue you pick isn't marked "Do-not-merge" otherwise your PR won't be merged. |
Comment on lines
41
to
49
| For a comprehensive guide on how to open a pull request, refer to the [AsyncAPI Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md). | ||
|
|
||
| - **Fork the repository**: Fork the repository you want to contribute to and create a new branch for your changes. | ||
|
|
||
| - **Make changes**: Implement the changes required to resolve the issue you picked. Ensure your code adheres to the project’s coding standards. | ||
|
|
||
| - **Submit a Pull Request**: Once you’re done, submit a pull request to the main repository. Make sure to include a detailed description of your changes. | ||
|
|
||
| - **Participate in discussions**: Engage with maintainers and other contributors in the PR comments section. This will help you understand the project better and improve your contributions. |
There was a problem hiding this comment.
Suggested change
| For a comprehensive guide on how to open a pull request, refer to the [AsyncAPI Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md). | |
| - **Fork the repository**: Fork the repository you want to contribute to and create a new branch for your changes. | |
| - **Make changes**: Implement the changes required to resolve the issue you picked. Ensure your code adheres to the project’s coding standards. | |
| - **Submit a Pull Request**: Once you’re done, submit a pull request to the main repository. Make sure to include a detailed description of your changes. | |
| - **Participate in discussions**: Engage with maintainers and other contributors in the PR comments section. This will help you understand the project better and improve your contributions. | |
| For a comprehensive guide on how to create a fork and start contributing, refer to the [AsyncAPI Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md). | |
| - **Fork the repository**: Fork the repository you want to contribute to and create a new branch for your changes. | |
| - **Make changes**: Implement the changes required to resolve the issue you picked. Ensure your code adheres to the project’s coding standards. | |
| - **Submit a Pull Request**: Once you’re done with the changes, submit a pull request to the main repository. Make sure to include a detailed description of your changes. | |
| - **Participate in discussions**: Engage with maintainers and other contributors in the PR comments section. This will help you understand the project better and improve your contributions. |
Comment on lines
53
to
57
| - After submitting a pull request, it’s time for the maintainers to review it. | ||
|
|
||
| - If you notice no one reviewing your PR (which is rare) or if you need a review urgently, don’t hesitate to ping the maintainers on Slack or GitHub | ||
|
|
||
| - Make sure all the checks (tests, style checks, etc.) turn green for a smooth merge. |
There was a problem hiding this comment.
Suggested change
| - After submitting a pull request, it’s time for the maintainers to review it. | |
| - If you notice no one reviewing your PR (which is rare) or if you need a review urgently, don’t hesitate to ping the maintainers on Slack or GitHub | |
| - Make sure all the checks (tests, style checks, etc.) turn green for a smooth merge. | |
| - **Pull Request Review Process**: After submitting a pull request, maintainers need to review it. | |
| - **Contact Maintainers**: If a pull request is not being reviewed (which is rare) or needs urgent review, contact maintainers on Slack or GitHub. | |
| - **Ensure Smooth Merge**: Ensure all checks (tests, style checks, etc.) pass before merging your PR. |
Comment on lines
61
to
63
| - **Recognition**: After contributing consistently, the maintainers will invite you to join the team. This invitation is a recognition of your contributions and dedication. | ||
|
|
||
| - If you feel you've made enough contributions, but haven't received an invitation, you can open an issue in the relevant repository to discuss your contributions with the maintainers. You can see an example of such an issue [here](https://github.com/asyncapi/cli/issues/1616). |
There was a problem hiding this comment.
Suggested change
| - **Recognition**: After contributing consistently, the maintainers will invite you to join the team. This invitation is a recognition of your contributions and dedication. | |
| - If you feel you've made enough contributions, but haven't received an invitation, you can open an issue in the relevant repository to discuss your contributions with the maintainers. You can see an example of such an issue [here](https://github.com/asyncapi/cli/issues/1616). | |
| - **Recognition**: After contributing consistently, the maintainers will invite you to join the team. This invitation is a recognition of your contributions and dedication. | |
| - **Inquiry about Recognition**: If you feel you've made enough contributions, but haven't received an invitation yet, you can open an issue in the corresponding repository to discuss your contributions with the maintainers. Check an [example of such an issue](https://github.com/asyncapi/cli/issues/1616). |
Comment on lines
61
to
63
| - **Recognition**: After contributing consistently, the maintainers will invite you to join the team. This invitation is a recognition of your contributions and dedication. | ||
|
|
||
| - If you feel you've made enough contributions, but haven't received an invitation, you can open an issue in the relevant repository to discuss your contributions with the maintainers. You can see an example of such an issue [here](https://github.com/asyncapi/cli/issues/1616). |
There was a problem hiding this comment.
If you feel you've made enough contributions
How many contributions are considered "enough"? I would rather rephrase it to something like that to get rid of ambiguity:
If you haven't received an invitation despite contributing consistently, you can open an issue in the corresponding repository to discuss your contributions with the maintainers. Check an example of such an issue.
Comment on lines
65
to
69
| ## Some Useful Links | ||
|
|
||
| - [AsyncAPI Contributor’s Guide](https://github.com/asyncapi/cli/blob/master/CONTRIBUTING.md): Learn how to set up, contribute, and work on pull requests. | ||
| - [GitHub Workflow Setup Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md): A detailed walkthrough of setting up GitHub Actions and managing workflows. | ||
| - [AsyncAPI Slack Community](https://www.asyncapi.com/slack-invite): Join the community and interact with fellow contributors and maintainers. |
There was a problem hiding this comment.
I would consider deleting this section as links 1 and 3 are available in the community home page, and the link 2 is available in the section 2: Open a Pull Request. But here, it is misleading, it's not about GitHub Actions.
Suggested change
| ## Some Useful Links | |
| - [AsyncAPI Contributor’s Guide](https://github.com/asyncapi/cli/blob/master/CONTRIBUTING.md): Learn how to set up, contribute, and work on pull requests. | |
| - [GitHub Workflow Setup Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md): A detailed walkthrough of setting up GitHub Actions and managing workflows. | |
| - [AsyncAPI Slack Community](https://www.asyncapi.com/slack-invite): Join the community and interact with fellow contributors and maintainers. |
|
@quetzalliwrites @thulieblack I have a question related to the location of this guide. My rough idea is to create a page or section with a clear navigation that would act as a single point of reference for all the contribution-related links. Whereas this guide can either replace the old one (or be merged with it) or marked, for example, "in progress", to proceed with the reorganization later on (I like this option more because reorganization with 90% probability will break incoming links to these guides from other repos). What do you think? |
|
Hey @bandantonio, Thank you so much for your review! Gosh, these comments really hit home for me. I didn't even take note of the tab spaces I used on the lists :). I have made the necessary changes now. Please take a look and tell me what you think. |
bandantonio
suggested changes
Jan 15, 2025
There was a problem hiding this comment.
@Aahil13 Please review all my previous comments again more closely as you missed some important changes that I proposed in suggestions.
| - Identifying and appointing new maintainers | ||
| - Mentoring new contributors and helping them navigate their journey | ||
| - Recognizing and rewarding contributions to foster community engagement | ||
|
|
||
| Basically, you're the *glue* that holds the project together and ensures that everything runs smoothly. | ||
| Essentially, you serve as a person that *binds* the project together and guarantees that everything runs smoothly. |
There was a problem hiding this comment.
Not sure that we need bold formatting here
|
|
||
| ## Steps to becoming a Maintainer | ||
|
|
||
| Before you can become a **maintainer**, you need to start as a **contributor**. The journey from contributor to maintainer is a rewarding one, and it involves the following steps: | ||
|
|
||
| ### 1. **Pick an Issue** | ||
|
|
||
| - **Join existing PR reviews**: If you're not sure where to start, begin by reviewing open [pull requests](https://github.com/asyncapi/community/pulls). This will give you an understanding of the code and where your contributions might fit in. | ||
| - **Join existing PR reviews**: If you're not sure where to start, begin by reviewing open [pull requests](https://github.com/asyncapi/community/pulls). This will give you an understanding of the code and where your contributions might fit in. |
There was a problem hiding this comment.
Please note the updated link I mentioned in my comment. The current link points to pull requests within the community repository only. As you're talking about "This will give you an understanding of the code", the community repository contains only documentation in Markdown and no code. My updated link points to all the repos within the AsyncAPI organization that include pull requests related to code as well.
|
|
||
| - **Look for "*good first issue*" labels**: These [issues](https://github.com/asyncapi/community/issues) are beginner-friendly and will help you get familiar with the project’s structure. Additionally, you can check out the [#97_bot-github-new-issues-prs](https://asyncapi.slack.com/archives/C01J06RL10X) channel on Slack for new issues and PRs. | ||
| - **Look for "*good first issue*" labels**: These [issues](https://github.com/asyncapi/community/issues) are beginner-friendly and will help you get familiar with the project’s structure. Additionally, you can check out the [#97_bot-github-new-issues-prs](https://asyncapi.slack.com/archives/C01J06RL10X) channel on Slack for new issues and PRs. |
There was a problem hiding this comment.
The same with the issues link
|
|
||
| > **NOTE**: Make sure whatever issue you pick isn't marked "Do-not-merge" else your PR won't be merged. | ||
| > **NOTE**: Make sure whatever issue you pick isn't marked "Do-not-merge" else your PR won't be merged. |
There was a problem hiding this comment.
Please note the updated formatting for the note in my comment.
|
|
||
| > **NOTE**: Make sure whatever issue you pick isn't marked "Do-not-merge" else your PR won't be merged. | ||
| > **NOTE**: Make sure whatever issue you pick isn't marked "Do-not-merge" else your PR won't be merged. | ||
|
|
||
| ### 2. **Open a Pull Request** | ||
|
|
||
| For a comprehensive guide on how to open a pull request, refer to the [AsyncAPI Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md). |
Comment on lines
41
to
47
| - **Fork the repository**: Fork the repository you want to contribute to and create a new branch for your changes. | ||
|
|
||
| - **Make changes**: Implement the changes required to resolve the issue you picked. Ensure your code adheres to the project’s coding standards. | ||
| - **Make changes**: Implement the changes required to resolve the issue you picked. Ensure your code adheres to the project’s coding standards. | ||
|
|
||
| - **Submit a Pull Request**: Once you’re done, submit a pull request to the main repository. Make sure to include a detailed description of your changes. | ||
| - **Submit a Pull Request**: Once you’re done, submit a pull request to the main repository. Make sure to include a detailed description of your changes. | ||
|
|
||
| - **Participate in discussions**: Engage with maintainers and other contributors in the PR comments section. This will help you understand the project better and improve your contributions. | ||
| - **Participate in discussions**: Engage with maintainers and other contributors in the PR comments section. This will help you understand the project better and improve your contributions. |
There was a problem hiding this comment.
Missed suggestions here as well.
Comment on lines
51
to
55
| - After submitting a pull request, it’s time for the maintainers to review it. | ||
|
|
||
| - If you notice no one reviewing your PR (which is rare) or if you need a review urgently, don’t hesitate to ping the maintainers on Slack or GitHub | ||
| - If you notice no one reviewing your PR (which is rare) or if you need a review urgently, don’t hesitate to ping the maintainers on Slack or GitHub | ||
|
|
||
| - Make sure all the checks (tests, style checks, etc.) turn green for a smooth merge. | ||
| - Make sure all the checks (tests, style checks, etc.) turn green for a smooth merge. |
Comment on lines
62
to
61
|
|
||
| - If you feel you've made enough contributions, but haven't received an invitation, you can open an issue in the relevant repository to discuss your contributions with the maintainers. You can see an example of such an issue [here](https://github.com/asyncapi/cli/issues/1616). | ||
|
|
||
| ## Some Useful Links | ||
| - **Recognition**: After contributing consistently, the maintainers will invite you to join the team. This invitation is a recognition of your contributions and dedication. | ||
|
|
||
| - [AsyncAPI Contributor’s Guide](https://github.com/asyncapi/cli/blob/master/CONTRIBUTING.md): Learn how to set up, contribute, and work on pull requests. | ||
| - [GitHub Workflow Setup Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md): A detailed walkthrough of setting up GitHub Actions and managing workflows. | ||
| - [AsyncAPI Slack Community](https://www.asyncapi.com/slack-invite): Join the community and interact with fellow contributors and maintainers. | ||
| - If you haven't received an invitation despite contributing consistently, you can open an issue in the corresponding repository to discuss your contributions with the maintainers. You can see an example of such an issue [here](https://github.com/asyncapi/cli/issues/1616). |
|
Hello @bandantonio, I've made the necessary changes now. Please, would you mind taking another look? |
|
#1638 (comment) I agree with reorganizing it into a folder/section for easy access. Let's create an issue separate from the PR, and it'll also be easy to involve other code owners. Thanks, @bandantonio, for the suggestion |
bandantonio
approved these changes
Jan 18, 2025
There was a problem hiding this comment.
@Aahil13 LGTM.
BUT my only comment here is to keep wording consistent. Throughout the document there are at least two terms that are used chaotically: pull request and PR. As an example, check the "Pick an Issue" section where different bullets have different terms used.
My suggestion is to make them consistent by making the first term (seems like it would be on line 14) like this: pull requests (PR) and then use only the "PR" term.
I approved the changes, but I would wait for another commit from you with consistent terms.
1 task
|
Hello @bandantonio, Thank you for this comment. I've gone through the document and made all the necessary changes. |
|
@Aahil13 LGTM, thank you for quick updates. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.