-
-
Notifications
You must be signed in to change notification settings - Fork 700
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore: introduce new contibutor guide with triagers and committers #2959
Changes from 7 commits
0745f07
e829589
e2d8132
b04d7a5
8f6fb30
06e1116
1abd9a7
06d77a5
2ed012e
67d8bb7
f418f0d
b6a24a2
e2d678f
e7f6665
57f1014
5365e61
22e0f4f
0dda44e
5c6d392
eec8ebf
0174ab1
f0a21d9
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,13 +1,20 @@ | ||
# Contributing to AsyncAPI | ||
We love your input! We want to make contributing to this project as easy and transparent as possible. | ||
# Welcome to AsyncAPI | ||
|
||
## Contribution recogniton | ||
Welcome to our open-source project! We're excited to have you join our community and contribute to making our project better. To ensure a smooth contribution process and maintain the quality of our codebase and documentation, please follow this guide. | ||
|
||
We use [All Contributors](https://allcontributors.org/docs/en/specification) specification to handle recognitions. For more details read [this](https://github.com/asyncapi/community/blob/master/recognize-contributors.md) document. | ||
We encourage all contributors to familiarize themselves with these guidelines and actively participate in the project's growth. If you have any questions or need assistance, don't hesitate to reach out to the project maintainers or community members. | ||
|
||
## Summary of the contribution flow | ||
## Code of Conduct | ||
|
||
AsyncAPI has adopted a Code of Conduct (CoC) that we expect project participants to adhere to. Please [read the full CoC text](./CODE_OF_CONDUCT.md) so that you can understand what sort of behavior is expected. | ||
|
||
## Our Development Process | ||
|
||
We use Github to host code, track issues and feature requests, as well as accept pull requests. | ||
|
||
The following is a summary of the ideal contribution flow. Please, note that Pull Requests can also be rejected by the maintainers when appropriate. | ||
## Contribution flow | ||
|
||
The following is a summary of the ideal contribution flow. | ||
|
||
``` | ||
┌───────────────────────┐ | ||
|
@@ -36,28 +43,27 @@ The following is a summary of the ideal contribution flow. Please, note that Pul | |
└───────────────────────┘ | ||
``` | ||
|
||
## Code of Conduct | ||
AsyncAPI has adopted a Code of Conduct that we expect project participants to adhere to. Please [read the full text](./CODE_OF_CONDUCT.md) so that you can understand what sort of behaviour is expected. | ||
Issues and pull requests without activity from the creator within 14 days will be automatically closed. However, closure does not mean rejection. If you wish to revisit a closed issue or pull request, feel free to open a new one referencing the closed item. | ||
|
||
## Our Development Process | ||
We use Github to host code, to track issues and feature requests, as well as accept pull requests. | ||
### Issues | ||
|
||
## Issues | ||
[Open an issue](https://github.com/asyncapi/asyncapi/issues/new) **only** if you want to report a bug or a feature. Don't open issues for questions or support, instead join our [Slack workspace](https://www.asyncapi.com/slack-invite) and ask there. Don't forget to follow our [Slack Etiquette](https://github.com/asyncapi/community/blob/master/slack-etiquette.md) while interacting with community members! It's more likely you'll get help, and much faster! | ||
[Open an issue](https://github.com/asyncapi/asyncapi/issues/new) **only** if you want to report a bug or a feature. Don't open issues for questions or support, instead join our [AsyncAPI Slack workspace](https://www.asyncapi.com/slack-invite) and ask there. Don't forget to follow our [Slack Etiquette](https://github.com/asyncapi/community/blob/master/slack-etiquette.md) while interacting with community members! It's more likely you'll get help, and much faster! | ||
|
||
derberg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
## Bug Reports and Feature Requests | ||
### Bug Reports and Feature Requests | ||
|
||
Please use our issues templates that provide you with hints on what information we need from you to help you out. | ||
|
||
## Pull Requests | ||
### Pull Requests | ||
|
||
**Please, make sure you open an issue before starting with a Pull Request, unless it's a typo or a really obvious error.** Pull requests are the best way to propose changes to the specification. Get familiar with our document that explains [Git workflow](https://github.com/asyncapi/community/blob/master/git-workflow.md) used in our repositories. | ||
**Please make sure you open an issue before starting with a Pull Request unless it's a typo or a really obvious error.** Pull requests are the best way to propose changes to the specification. If there was no issue created first where maintainers discussed if a pull request is needed, the pull request may be rejected. | ||
|
||
derberg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Get familiar with our document that explains the [Git workflow](https://github.com/asyncapi/community/blob/master/git-workflow.md) used in our repositories. | ||
|
||
derberg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
## Conventional commits | ||
|
||
Our repositories follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification. Releasing to GitHub and NPM is done with the support of [semantic-release](https://semantic-release.gitbook.io/semantic-release/). | ||
Our repositories follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification. Releasing to GitHub and NPM is done with the support of [semantic-release](https://semantic-release.gitbook.io/semantic-release/). | ||
|
||
Pull requests should have a title that follows the specification, otherwise, merging is blocked. If you are not familiar with the specification simply ask maintainers to modify. You can also use this cheatsheet if you want: | ||
Pull requests should have a title that follows the specification; otherwise, merging is blocked. If you are not familiar with the specification, simply ask maintainers to modify it. You can also use this cheatsheet if you want: | ||
|
||
- `fix: ` prefix in the title indicates that PR is a bug fix and PATCH release must be triggered. | ||
- `feat: ` prefix in the title indicates that PR is a feature and MINOR release must be triggered. | ||
|
@@ -66,14 +72,40 @@ Pull requests should have a title that follows the specification, otherwise, mer | |
- `test: ` prefix in the title indicates that PR is only related to tests and there is no need to trigger release. | ||
- `refactor: ` prefix in the title indicates that PR is only related to refactoring and there is no need to trigger release. | ||
|
||
What about MAJOR release? just add `!` to the prefix, like `fix!: ` or `refactor!: ` | ||
What about a MAJOR release? Just add `!` to the prefix, like `fix!: ` or `refactor!: ` | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We don't have any release process inside the website. Do we need this point? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. yup, you;re right - will remove once we also clarify other comments |
||
Prefix that follows specification is not enough though. Remember that the title must be clear and descriptive with usage of [imperative mood](https://chris.beams.io/posts/git-commit/#imperative). | ||
A prefix that follows specification is not enough. Remember that the title must be clear and descriptive with the usage of [imperative mood](https://chris.beams.io/posts/git-commit/#imperative). | ||
|
||
Happy contributing :heart: | ||
Happy contributing! :heart: | ||
|
||
## License | ||
When you submit changes, your submissions are understood to be under the same [Apache 2.0 License](https://github.com/asyncapi/asyncapi/blob/master/LICENSE) that covers the project. Feel free to [contact the maintainers](https://www.asyncapi.com/slack-invite) if that's a concern. | ||
|
||
## References | ||
This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/master/CONTRIBUTING.md). | ||
## Contribution recognition | ||
|
||
We use the [All Contributors](https://allcontributors.org/docs/en/specification) specification to handle recognitions. For more details read the [`recognize contributors` document](https://github.com/asyncapi/community/blob/master/recognize-contributors.md). | ||
|
||
## Maintainers setup | ||
|
||
To streamline project management and facilitate onboarding, the maintainer's set up in the project includes two roles: `triager` and `committer`. | ||
|
||
There are also two separate areas of responsibility: docs and code. There can be a committer responsible for code only, and there can also be a triager responsible for docs only. There can also be a maintainer that holds all roles and participages in different areas. | ||
derberg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
We recognize that because of the size of the project and its complexity, areas of responsibility can also get more granular. For example, there can be a committer responsible for docs but only community docs or a committeer responsible only for project design. These exceptions are assessed and approved by project maintainers. | ||
derberg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
### Triager | ||
|
||
Triagers are responsible for labeling, commenting, and assisting with issue and pull request management. | ||
|
||
- Triagers assess newly-opened issues and pull requests. | ||
- Responsibilities include labeling issues and pull requests, commenting, closing, and reopening items as needed, and assisting users and novice contributors. | ||
- Triagers play a crucial role in enforcing the contributor guide and maintaining a clean backlog. | ||
- If a triager plans to become a committer, they should consult with existing committers to gradually gain more rights. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What should be the criteria for a triager to become a committer? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I guess doing the work of a committer for some time? not sure we are able to define, in the end someone has to gain trust of committer to become one - committer needs to be comfortable with another person to approve and merge so committer, in theory knows triager from their work, and more or less know what knowledge they are missing and what they need to work on - help define next steps 🤔 not sure if we are able to be more specific? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think the clear point to become a committer from triager, is to take their stance, opinions or give suggestions on some of the critical issues in the repo, or being the part/mentor of any big/critical project idea inside |
||
|
||
### Committer | ||
|
||
Committers are responsible for technical oversight, pull request approval, and onboarding of new maintainers. | ||
|
||
- Committers approve pull requests and oversee the technical direction of the project. | ||
- They are responsible for reviewing and approving pull requests for merging. | ||
- Committers also play a role in onboarding new maintainers and triagers. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What if maintainers fail to acknowledge the issue within 14 days?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I hope that never happens
so "automatically" I mean that triager or committer may automatically close the issue if it is not active
on our side
we could have maybe a sentence that if, let's say, there is no acknowledgement of maintainers in 7 or 14 days, they should use
/ptal
command. wdyt?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah
/ptal
can be a good option for the author of the issue. Kindly add this information in the doc.