docs: expand community docs: contributor - simple contribution flow a… #1730
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,82 @@ | ||||||
| --- | ||||||
| title: Simple contribution flow for contributors | ||||||
| weight: 130 | ||||||
| --- | ||||||
|
|
||||||
| # Simple Contribution Flow | ||||||
|
Comment on lines
+1
to
+6
There was a problem hiding this comment. 🛠️ Refactor suggestion Align front matter title with H1 heading |
||||||
| This guide explains how to contribute effectively to AsyncAPI. It guides you through the contribution process and provides a checklist to ensure high-quality contributions. | ||||||
|
|
||||||
| ## Making a Contribution | ||||||
| We welcome your contributions to AsyncAPI, whether you have suggestions, improvements, or new ideas. | ||||||
|
|
||||||
| At AsyncAPI, we value **quality over quantity**. This guide will help you make meaningful contributions that benefit the community. | ||||||
|
|
||||||
| ### Before You Start Contributing | ||||||
| - If you are joining AsyncAPI through [Slack](https://asyncapi.com/slack-invite) or an event, take your time to explore the [AsyncAPI website](https://www.asyncapi.com/). | ||||||
| - Read our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md). | ||||||
| - [Attend meetings](https://www.asyncapi.com/community/events) and engage in discussions in the [`#11_contributing` Slack channel](https://asyncapi.com/slack-invite). | ||||||
| - Read the [documentation](https://www.asyncapi.com/docs) to learn more about AsyncAPI. | ||||||
|
|
||||||
| ### Before Making a Contribution | ||||||
| - Read the [onboarding contributor guide](https://www.asyncapi.com/docs/community/onboarding-guide). | ||||||
| - If you are contributing to the community repository, review the [documentation onboarding checklist](https://www.asyncapi.com/docs/community/onboarding-guide/docs-onboarding-checklist). | ||||||
|
Comment on lines
+21
to
+22
There was a problem hiding this comment. Fix broken onboarding guide links The links in the “Before Making a Contribution” section point to - Read the [onboarding contributor guide](https://www.asyncapi.com/docs/community/onboarding-guide).
- review the [documentation onboarding checklist](https://www.asyncapi.com/docs/community/onboarding-guide/docs-onboarding-checklist).
+ Read the [onboarding contributor guide](https://www.asyncapi.com/docs/onboarding-guide).
+ review the [documentation onboarding checklist](https://www.asyncapi.com/docs/onboarding-guide/docs-onboarding-checklist).
|
||||||
| - For other repositories, refer to the [general contribution guidelines](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md). | ||||||
thulieblack marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| - Look through existing issues and pull requests to understand the repository better. | ||||||
| - Check the [general roadmap](https://www.asyncapi.com/roadmap). | ||||||
|
|
||||||
| ### Steps to making a good contribution | ||||||
|
There was a problem hiding this comment. Please make a numbered list in this section, not bullets, because the order here actually matters. |
||||||
| 1. Set up your workflow environment using the [git workflow guide](/asyncapi/community/blob/master/git-workflow.md). | ||||||
| 2. Search for [good first issues](https://github.com/issues?page=1&q=is%3Aopen+org%3Aasyncapi+sort%3Aupdated-desc+label%3A%22good+first+issue%22). | ||||||
|
There was a problem hiding this comment. Scope "good first issues" search to AsyncAPI repo The current URL points to GitHub’s global issues but is not scoped to AsyncAPI. It should target the community repository: - https://github.com/issues?page=1&q=is%3Aopen+org%3Aasyncapi+sort%3Aupdated-desc+label%3A%22good+first+issue%22
+ https://github.com/asyncapi/community/issues?q=is%3Aopen+label%3A%22good+first+issue%22📝 Committable suggestion
Suggested change
|
||||||
| 3. When you do find one, request to be assigned. | ||||||
| 4. If you noticed a bug, typo, or needed improvement, feel free to create an issue. | ||||||
| 5. **Make a PR only after a maintainer assigned the issue to you** even if you created the issue yourself. | ||||||
| 6. Follow the [conventional commits guide](conventional-commits) to write a good PR title. | ||||||
thulieblack marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| 7. Follow the [git workflow document](/asyncapi/community/blob/master/git-workflow.md) when working on your changes and making a PR. | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. It will open once merged so don't worry There was a problem hiding this comment. @thulieblack Hmm, the link to the git workflow document was correct, could you please elaborate on this suggestion? There was a problem hiding this comment. The link shouldn't take them to the folder in GitHub but to the doc on the website. For example, how we did with the checklist https://github.com/asyncapi/community/blob/master/docs/onboarding-guide/docs-onboarding-checklist.md?plain=1 There was a problem hiding this comment. Ok, I got it. But this link was referring to the git workflow document that isn't listed on the docs website, that's why it was a direct link to GitHub markdown. Conventional commits is a different document, I believe we will confuse readers with such a substitution. There was a problem hiding this comment. Then should we bring git workflow under the onboarding docs then? @bandantonio There was a problem hiding this comment. @thulieblack you may be using wrong link here. It should be git-workflow instead of conventional-commits |
||||||
| 8. After making a PR, patiently wait for reviews. | ||||||
| 9. Make sure all your PR checks pass (turn green) to speed up the merging process. | ||||||
| 10. If your PR hasn’t been reviewed after **a week and a half**, you can gently remind a maintainer on Slack or GitHub. Delays can happen for various reasons, but no one is ignoring you! 🙏🏼 . | ||||||
|
|
||||||
| ## Important Contribution Rules | ||||||
| To help maintain a welcoming and productive environment, we have outlined a few important contribution rules that all contributors, especially new ones, must follow. | ||||||
|
|
||||||
| These rules are here to help you succeed and to support the maintainers and community as we all work together. Not following them can lead to consequences, such as being blocked from submitting PRs or being removed from the community. | ||||||
|
|
||||||
| ### ✅ What You Should Always Do | ||||||
|
|
||||||
| - **Be patient**. Maintainers are volunteers with their jobs, families, and responsibilities. It may take time for your PR or issue to be reviewed. | ||||||
| - **Use the right Slack channels**. If you're unsure where to post, ask politely or take a moment to check. | ||||||
| - **Keep Slack tidy**. Use threads for conversations, avoid tagging `@maintainers` unless truly necessary, and don’t spam. | ||||||
| - **Follow our [Slack etiquette](/asyncapi/community/blob/master/slack-etiquette.md)** **and [Code of Conduct](/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md)**. | ||||||
thulieblack marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| - **Respect others**. Treat everyone with kindness and patience. We are all here to learn and grow together. | ||||||
|
|
||||||
| ### ❌ What You Should Never Do | ||||||
| - Ignore essential onboarding materials and contribution guidelines. | ||||||
| - Tag maintainers repeatedly or demanding attention. | ||||||
| - Post the same message in multiple places. | ||||||
| - Expect instant replies. | ||||||
|
|
||||||
| ### ⚠️ What Happens If You Break the Rules | ||||||
|
|
||||||
| We're friendly and welcoming, but we also value focus and respect. If rules are ignored: | ||||||
|
|
||||||
| - You may be muted or temporarily removed from Slack. | ||||||
| - Repeated behavior could lead to permanent removal from the community. | ||||||
| - PRs or issues may be closed or rejected if the behavior affects maintainers or the community. | ||||||
|
|
||||||
| These rules are not meant to scare anyone - they're here to make sure everyone can enjoy a healthy and respectful space. When in doubt, be thoughtful, ask questions politely, and refer to our onboarding and etiquette docs. | ||||||
|
|
||||||
| Let's keep AsyncAPI a community where people enjoy contributing. 👏🏼 | ||||||
|
|
||||||
|
|
||||||
| ## Contribution Checklist | ||||||
| Before submitting your contribution, ask yourself: | ||||||
| - [ ] Is my contribution relevant to AsyncAPI? | ||||||
| - [ ] Have I explained why this contribution is necessary? | ||||||
| - [ ] Is my writing clear, concise, and well-structured? | ||||||
| - [ ] Did I follow the [documentation style guide](https://github.com/asyncapi/community/tree/master/docs/styleguide)? | ||||||
| - [ ] Have my code examples been tested, and are they functional? | ||||||
| - [ ] Have I linked any relevant issues, discussions, or existing docs? | ||||||
| - [ ] Did I provide a description of the changes in my PR? | ||||||
| - [ ] Am I open to feedback and revisions? | ||||||
|
|
||||||
| If you answered **yes** to all these questions, you are ready to submit your PR or create an issue! 🚀 | ||||||
Uh oh!
There was an error while loading. Please reload this page.