Skip to content
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

Merged
merged 22 commits into from
Aug 30, 2024
Merged
Changes from 9 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
0745f07
chore: introduce new contibutor guide with triagers and committers
derberg May 13, 2024
e829589
revert codeowners changes
derberg May 13, 2024
e2d8132
Update CODEOWNERS
derberg May 13, 2024
b04d7a5
editorial cleanup
quetzalliwrites May 15, 2024
8f6fb30
Merge branch 'master' into newcontribguideaaabbbccc
quetzalliwrites May 18, 2024
06e1116
Merge branch 'master' into newcontribguideaaabbbccc
quetzalliwrites May 21, 2024
1abd9a7
Merge branch 'master' into newcontribguideaaabbbccc
akshatnema May 23, 2024
06d77a5
Merge branch 'master' into newcontribguideaaabbbccc
quetzalliwrites May 25, 2024
2ed012e
Merge branch 'master' into newcontribguideaaabbbccc
asyncapi-bot Jul 17, 2024
67d8bb7
adress feedaback from Akshat
derberg Jul 29, 2024
f418f0d
Merge branch 'master' into newcontribguideaaabbbccc
derberg Jul 29, 2024
b6a24a2
Merge branch 'master' into newcontribguideaaabbbccc
anshgoyalevil Jul 31, 2024
e2d678f
Merge branch 'master' into newcontribguideaaabbbccc
derberg Jul 31, 2024
e7f6665
Merge branch 'master' into newcontribguideaaabbbccc
derberg Jul 31, 2024
57f1014
Apply suggestions from code review
derberg Aug 1, 2024
5365e61
Apply suggestions from code review
derberg Aug 1, 2024
22e0f4f
Update CONTRIBUTING.md
derberg Aug 1, 2024
0dda44e
Update CONTRIBUTING.md
derberg Aug 28, 2024
5c6d392
Merge branch 'master' into newcontribguideaaabbbccc
derberg Aug 28, 2024
eec8ebf
editorial cleanup
quetzalliwrites Aug 30, 2024
0174ab1
Merge branch 'master' into newcontribguideaaabbbccc
quetzalliwrites Aug 30, 2024
f0a21d9
Merge branch 'master' into newcontribguideaaabbbccc
derberg Aug 30, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 54 additions & 22 deletions CONTRIBUTING.md
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.

```
┌───────────────────────┐
Expand Down Expand Up @@ -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.

Copy link
Member

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?

Copy link
Member Author

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?

Copy link
Member

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.

## 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.
Expand All @@ -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!: `

Copy link
Member

Choose a reason for hiding this comment

The 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?

Copy link
Member Author

Choose a reason for hiding this comment

The 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What should be the criteria for a triager to become a committer?

Copy link
Member Author

Choose a reason for hiding this comment

The 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?

Copy link
Member

@akshatnema akshatnema May 25, 2024

Choose a reason for hiding this comment

The 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 website. In that way, other committers can find enough skills inside the required triager to become a committer. Moreover, the activity of triager also determines whether the person can be an active committer or not.


### 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.
Loading