From 9b58449b46067b310aa7be45c25f7294a0513055 Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <sambhavgupta0705@gmail.com> Date: Wed, 13 Sep 2023 17:00:34 +0530 Subject: [PATCH 01/12] initialised the contribution guide with new changes --- CONTRIBUTING.md | 267 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 210 insertions(+), 57 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1334921..d3732c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,79 +1,232 @@ -# Contributing to AsyncAPI -We love your input! We want to make contributing to this project as easy and transparent as possible. +# AsyncAPI Extensions Catalog Contribution Guide -## Contribution recogniton +AsyncAPI is an evolving language. This repository contains the Extensions as well as Pull Requests with suggested improvements and contributions. -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. +Contributions that do not change the interpretation of the extensions but instead improve legibility, fix editorial errors, clear up ambiguity and improve examples are encouraged and are often merged by a extension Committer with little process. -## Summary of the contribution flow +However, contributions that _do_ meaningfully change the interpretation of the extensions must follow an RFC (Request For Comments) process through a series of *stages* intended to improve *visibility*, allow for *discussion* to reach the best solution, and arrive at *consensus*. This process becomes even more important as AsyncAPI's community broadens. -The following is a summary of the ideal contribution flow. Please, note that Pull Requests can also be rejected by the maintainers when appropriate. +When proposing or weighing-in on any issue or pull request, consider the +[Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md) +to better understand expected and unacceptable behavior. -``` - ┌───────────────────────┐ - │ │ - │ Open an issue │ - │ (a bug report or a │ - │ feature request) │ - │ │ - └───────────────────────┘ - ⇩ - ┌───────────────────────┐ - │ │ - │ Open a Pull Request │ - │ (only after issue │ - │ is approved) │ - │ │ - └───────────────────────┘ - ⇩ - ┌───────────────────────┐ - │ │ - │ Your changes will │ - │ be merged and │ - │ published on the next │ - │ release │ - │ │ - └───────────────────────┘ -``` -## 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. +## Contributing to AsyncAPI Libraries + +A common point of confusion for those who wish to contribute to AsyncAPI is where +to start. In fact, you may have found yourself here after attempting to make an +improvement to an AsyncAPI library. Should a new addition be made to the AsyncAPI +spec first or an AsyncAPI library first? Admittedly, this can become a bit of a +[chicken-or-egg](https://en.wikipedia.org/wiki/Chicken_or_the_egg) dilemma. + +AsyncAPI libraries seek to be "spec compliant", which means they discourage +changes that cause them to behave differently from the spec as written. However, +they also encourage pull requests for changes that accompany an RFC *proposal* +or RFC *draft*. In fact, a spec contribution RFC won't be *accepted* until it +has experience being implemented in an AsyncAPI library. + +To allow a library to remain spec compliant while also implementing *proposals* +and *drafts*, the library's maintainers may request that these new features are +disabled by default with opt-in option flags or they may simply wait to merge a +well-tested pull request until the spec proposal is *accepted*. + + +## Guiding Principles + +AsyncAPI's evolution is guided by a few principles. Suggested contributions +should use these principles to guide the details of an RFC and decisions to +move forward. + +* **Favor no change** + + As AsyncAPI is implemented in many languages under the collaboration + of a lot of individuals, incorporating any change has a high cost. + Accordingly, proposed changes must meet a very high bar of added value. + The burden of proof is on the contributor to illustrate this value. + +* **Enable new capabilities motivated by real use cases** + + Every change should intend on unlocking a real and reasonable use case. Real + examples are always more compelling than theoretical ones, and common + scenarios are more compelling than rare ones. RFCs should do more than offer + a different way to reach an already achievable outcome. + +* **Simplicity and consistency over expressiveness and terseness** + + "Possible but awkward" is often favored over more complex + alternatives. Simplicity (e.g. fewer concepts) is more important than + expressing more sophisticated ideas or writing less. + +* **Preserve option value** + + It's hard to know what the future brings; whenever possible, decisions should + be made that allow for more options in the future. Sometimes this is + unintuitive: spec rules often begin more strict than necessary with a future + option to loosen when motivated by a real use case. + +* **Understandability is just as important as correctness** + + The AsyncAPI spec, despite describing technical behavior, is intended to be + read by people. Use natural tone and include motivation and examples. + + +## RFC Contribution Champions + +Contributing to AsyncAPI requires a lot of dedicated work. To set clear +expectations and provide accountability, each proposed RFC (request for +comments) must have a *champion* who is responsible for addressing feedback and +completing next steps. An RFC may have multiple *champions*. The spec Committers +are not responsible for completing RFCs which lack a *champion* (though a +Committer may be a *champion* for an RFC). + +An RFC which does not have a *champion* may not progress through stages, and can +become stale. Stale proposals may be picked up by a new *champion* or may +be *rejected*. + + +## RFC Contribution Stages + +RFCs are guided by a *champion* through a series of stages: *strawman*, +*proposal*, *draft*, and *accepted* (or *rejected*), each of which has suggested +entrance criteria and next steps detailed below. RFCs typically advance one +stage at a time, but may advance multiple stages at a time. Stage +advancements occur on GitHub. -## Our Development Process -We use Github to host code, to track issues and feature requests, as well as accept pull requests. +In general, it's preferable to start with a pull request so that we can best +evaluate the RFC in detail. However, starting with an issue is also permitted if +the full details are not worked out. -## 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! +All RFCs start as either a *strawman* or *proposal*. -## Bug Reports and Feature Requests +## Stage 0: *Strawman* -Please use our issues templates that provide you with hints on what information we need from you to help you out. +An RFC at the *strawman* stage captures a described problem or +partially-considered solutions. A *strawman* does not need to meet any entrance +criteria. A *strawman's* goal is to prove or disprove a problem and guide +discussion towards either rejection or a preferred solution. A *strawman* may +be an issue or a pull request (though an illustrative pull request is preferrable). -## Pull Requests +*There is no entrance criteria for a Strawman* -**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. +As implied by the name [strawman](https://en.wikipedia.org/wiki/Straw_man_proposal), +the goal at this stage is to knock it down (*reject*) by considering other +possible related solutions, showing that the motivating problem can be solved +with no change to the specification, or that it is not aligned with the +*guiding principles*. -## Conventional commits +Once determined that the *strawman* is compelling, it should seek the entrance +criteria for *proposal*. -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/). -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: +## Stage 1: *Proposal* -- `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. -- `docs: ` prefix in the title indicates that PR is only related to the documentation and there is no need to trigger release. -- `chore: ` prefix in the title indicates that PR is only related to cleanup in the project and there is no need to trigger release. -- `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. +An RFC at the *proposal* stage is a solution to a problem with enough fidelity +to be discussed in detail. It must be backed by a willing *champion*. A +*proposal*'s goal is to make a compelling case for acceptance by describing +both the problem and the solution via examples and spec edits. A *proposal* +should be a pull request. -What about MAJOR release? just add `!` to the prefix, like `fix!: ` or `refactor!: ` +*Entrance criteria:* -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). +* Identified *champion* +* Clear explanation of problem and solution +* Illustrative examples +* Incomplete spec edits +* Identification of potential concerns, challenges, and drawbacks -Happy contributing :heart: +A *proposal* is subject to the same discussion as a *strawman*: ensuring that it +is well aligned with the *guiding principles*, is a problem worth solving, and +is the preferred solution to that problem. A *champion* is not expected to have +confidence in every detail at this stage and should instead focus on identifying +and resolving issues and edge-cases. To better understand the technical +ramifications of the *proposal*, a *champion* is encouraged to implement it in a +AsyncAPI library. -## 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. +Most *proposals* are expected to evolve or change and may be rejected. Therefore, +it is unwise to rely on a *proposal* in a production environment. AsyncAPI +libraries *may* implement *proposals*, though are encouraged to not enable the +*proposed* feature without explicit opt-in. + + +## Stage 2: *Draft* + +An RFC at the *draft* stage is a fully formed solution. There is +consensus the problem identified should be solved, and this particular solution +is preferred. A *draft's* goal is to precisely and completely describe the +solution and resolve any concerns through library implementations. A *draft* +must be a pull request. + +*Entrance criteria:* + +* Consensus the solution is preferred +* Resolution of identified concerns and challenges +* Precisely described with spec edits +* Compliant implementation in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas) (might not be merged) + +A *proposal* becomes a *draft* when the set of problems or drawbacks have been +fully considered and accepted or resolved, and the solution is deemed +desirable. A *draft*'s goal is to complete final spec edits that are ready to +be merged and implement the *draft* in AsyncAPI libraries along with tests to +gain confidence that the spec text is sufficient. + +*Drafts* may continue to evolve and change, occasionally dramatically, and are +not guaranteed to be accepted. Therefore, it is unwise to rely on a *draft* in a +production environment. AsyncAPI libraries *should* implement *drafts* to +provide valuable feedback, though are encouraged not to enable the *draft* +feature without explicit opt-in when possible. + + +## Stage 3: *Accepted* + +An RFC at the *accepted* stage is a completed solution. According to a spec +Committer it is ready to be merged as-is into the spec document. The RFC is +ready to be deployed in AsyncAPI libraries. An *accepted* RFC must be +implemented in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas). + +*Entrance criteria:* + +* Consensus the solution is complete +* Complete spec edits, including examples and prose +* Compliant implementation in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas) (fully tested and merged or ready to merge) + +A *draft* is *accepted* when the Committers have been convinced via +implementations and tests that it appropriately handles all edge cases; that the +spec changes not only precisely describe the new syntax and semantics but +include sufficient motivating prose and examples; and that the RFC includes +edits to any other affected areas of the spec. Once *accepted*, its *champion* +should encourage adoption of the RFC by opening issues or pull requests on other +popular AsyncAPI libraries. + +An *accepted* RFC is merged into the AsyncAPI spec's master branch by a Committer +and will be included in the next released revision. + + +## Stage X: *Rejected* + +An RFC may be *rejected* at any point and for any reason. Most rejections occur +when a *strawman* is proven to be unnecessary, is misaligned with the *guiding +principles*, or fails to meet the entrance criteria to become a *proposal*. +A *proposal* may become *rejected* for similar reasons as well as if it fails to +reach consensus or loses the confidence of its *champion*. Likewise a *draft* +may encounter unforeseen issues during implementations which cause it to lose +consensus or the confidence of its *champion*. + +RFCs which have lost a *champion* will not be *rejected* immediately, but may +become *rejected* if they fail to attract a new *champion*. + +Once *rejected*, an RFC will typically not be reconsidered. Reconsideration is +possible if a *champion* believes the original reason for rejection no longer +applies due to new circumstances or new evidence. + + +## Merging pull requests + +A pull request can be merged if all the following conditions are met: + +* There is, at least, a mininum of 3 approvals from the [repository code owners](./CODEOWNERS). +* Sufficient time has passed to let all code owners review the pull request. As of now, it should be a minimum of 1 week. If all code owners have already approved a pull request, it's ok not to wait for this period of time. + +``` ## 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). \ No newline at end of file +This document was adapted from the [GraphQL Specification Contribution Guide](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md). \ No newline at end of file From 93742f447a283afc47c6849122c169a2d6933ce1 Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <81870866+sambhavgupta0705@users.noreply.github.com> Date: Sat, 16 Sep 2023 21:47:09 +0530 Subject: [PATCH 02/12] updating the title Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3732c5..06405c7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# AsyncAPI Extensions Catalog Contribution Guide +# Contributing Extensions for AsyncAPI Specification AsyncAPI is an evolving language. This repository contains the Extensions as well as Pull Requests with suggested improvements and contributions. From 984c3db6fdcc80b01b8c2045e299e8dc0349ba00 Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <81870866+sambhavgupta0705@users.noreply.github.com> Date: Thu, 21 Sep 2023 07:45:29 +0530 Subject: [PATCH 03/12] Update CONTRIBUTING.md Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com> --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06405c7..840f23d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,8 +6,7 @@ Contributions that do not change the interpretation of the extensions but instea However, contributions that _do_ meaningfully change the interpretation of the extensions must follow an RFC (Request For Comments) process through a series of *stages* intended to improve *visibility*, allow for *discussion* to reach the best solution, and arrive at *consensus*. This process becomes even more important as AsyncAPI's community broadens. -When proposing or weighing-in on any issue or pull request, consider the -[Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md) +When proposing or weighing-in on any issue or pull request, consider the [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md) to better understand expected and unacceptable behavior. From 0584ec489ea2277fc8724cb4a3ac1d30e1962f6f Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <81870866+sambhavgupta0705@users.noreply.github.com> Date: Thu, 21 Sep 2023 07:45:41 +0530 Subject: [PATCH 04/12] Update CONTRIBUTING.md Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com> --- CONTRIBUTING.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 840f23d..d210113 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,24 +10,6 @@ When proposing or weighing-in on any issue or pull request, consider the [Code o to better understand expected and unacceptable behavior. -## Contributing to AsyncAPI Libraries - -A common point of confusion for those who wish to contribute to AsyncAPI is where -to start. In fact, you may have found yourself here after attempting to make an -improvement to an AsyncAPI library. Should a new addition be made to the AsyncAPI -spec first or an AsyncAPI library first? Admittedly, this can become a bit of a -[chicken-or-egg](https://en.wikipedia.org/wiki/Chicken_or_the_egg) dilemma. - -AsyncAPI libraries seek to be "spec compliant", which means they discourage -changes that cause them to behave differently from the spec as written. However, -they also encourage pull requests for changes that accompany an RFC *proposal* -or RFC *draft*. In fact, a spec contribution RFC won't be *accepted* until it -has experience being implemented in an AsyncAPI library. - -To allow a library to remain spec compliant while also implementing *proposals* -and *drafts*, the library's maintainers may request that these new features are -disabled by default with opt-in option flags or they may simply wait to merge a -well-tested pull request until the spec proposal is *accepted*. ## Guiding Principles From 3595b1b6428acd98fa00f458a1e93cd96edc6ee6 Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <81870866+sambhavgupta0705@users.noreply.github.com> Date: Tue, 26 Sep 2023 18:18:00 +0530 Subject: [PATCH 05/12] Update CONTRIBUTING.md Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com> --- CONTRIBUTING.md | 39 ++++----------------------------------- 1 file changed, 4 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d210113..0aa18a4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,41 +14,10 @@ to better understand expected and unacceptable behavior. ## Guiding Principles -AsyncAPI's evolution is guided by a few principles. Suggested contributions -should use these principles to guide the details of an RFC and decisions to -move forward. - -* **Favor no change** - - As AsyncAPI is implemented in many languages under the collaboration - of a lot of individuals, incorporating any change has a high cost. - Accordingly, proposed changes must meet a very high bar of added value. - The burden of proof is on the contributor to illustrate this value. - -* **Enable new capabilities motivated by real use cases** - - Every change should intend on unlocking a real and reasonable use case. Real - examples are always more compelling than theoretical ones, and common - scenarios are more compelling than rare ones. RFCs should do more than offer - a different way to reach an already achievable outcome. - -* **Simplicity and consistency over expressiveness and terseness** - - "Possible but awkward" is often favored over more complex - alternatives. Simplicity (e.g. fewer concepts) is more important than - expressing more sophisticated ideas or writing less. - -* **Preserve option value** - - It's hard to know what the future brings; whenever possible, decisions should - be made that allow for more options in the future. Sometimes this is - unintuitive: spec rules often begin more strict than necessary with a future - option to loosen when motivated by a real use case. - -* **Understandability is just as important as correctness** - - The AsyncAPI spec, despite describing technical behavior, is intended to be - read by people. Use natural tone and include motivation and examples. +- Make sure that extension is well documented with good examples, +- Explain the use case, +- Try to improve existing extensions, before you contribute a competing one, +- Start discussion with an issue. Don't start with pull request first. ## RFC Contribution Champions From c16d0ec2966f3d6dada025bf299e7ff57f61571a Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <81870866+sambhavgupta0705@users.noreply.github.com> Date: Tue, 26 Sep 2023 18:24:57 +0530 Subject: [PATCH 06/12] changes in contributing.md --- CONTRIBUTING.md | 173 +----------------------------------------------- 1 file changed, 3 insertions(+), 170 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0aa18a4..9cf61ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,182 +1,15 @@ # Contributing Extensions for AsyncAPI Specification -AsyncAPI is an evolving language. This repository contains the Extensions as well as Pull Requests with suggested improvements and contributions. - -Contributions that do not change the interpretation of the extensions but instead improve legibility, fix editorial errors, clear up ambiguity and improve examples are encouraged and are often merged by a extension Committer with little process. - -However, contributions that _do_ meaningfully change the interpretation of the extensions must follow an RFC (Request For Comments) process through a series of *stages* intended to improve *visibility*, allow for *discussion* to reach the best solution, and arrive at *consensus*. This process becomes even more important as AsyncAPI's community broadens. +Extensions catalog is like a waiting room for main specification features. Goal for the extensions catalog is to enable easier and faster contribution process than you see in [AsyncAPI Specification](https://github.com/asyncapi/spec/blob/master/CONTRIBUTING.md). When proposing or weighing-in on any issue or pull request, consider the [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md) to better understand expected and unacceptable behavior. - - - ## Guiding Principles - Make sure that extension is well documented with good examples, - Explain the use case, - Try to improve existing extensions, before you contribute a competing one, - Start discussion with an issue. Don't start with pull request first. - - -## RFC Contribution Champions - -Contributing to AsyncAPI requires a lot of dedicated work. To set clear -expectations and provide accountability, each proposed RFC (request for -comments) must have a *champion* who is responsible for addressing feedback and -completing next steps. An RFC may have multiple *champions*. The spec Committers -are not responsible for completing RFCs which lack a *champion* (though a -Committer may be a *champion* for an RFC). - -An RFC which does not have a *champion* may not progress through stages, and can -become stale. Stale proposals may be picked up by a new *champion* or may -be *rejected*. - - -## RFC Contribution Stages - -RFCs are guided by a *champion* through a series of stages: *strawman*, -*proposal*, *draft*, and *accepted* (or *rejected*), each of which has suggested -entrance criteria and next steps detailed below. RFCs typically advance one -stage at a time, but may advance multiple stages at a time. Stage -advancements occur on GitHub. - -In general, it's preferable to start with a pull request so that we can best -evaluate the RFC in detail. However, starting with an issue is also permitted if -the full details are not worked out. - -All RFCs start as either a *strawman* or *proposal*. - -## Stage 0: *Strawman* - -An RFC at the *strawman* stage captures a described problem or -partially-considered solutions. A *strawman* does not need to meet any entrance -criteria. A *strawman's* goal is to prove or disprove a problem and guide -discussion towards either rejection or a preferred solution. A *strawman* may -be an issue or a pull request (though an illustrative pull request is preferrable). - -*There is no entrance criteria for a Strawman* - -As implied by the name [strawman](https://en.wikipedia.org/wiki/Straw_man_proposal), -the goal at this stage is to knock it down (*reject*) by considering other -possible related solutions, showing that the motivating problem can be solved -with no change to the specification, or that it is not aligned with the -*guiding principles*. - -Once determined that the *strawman* is compelling, it should seek the entrance -criteria for *proposal*. - - -## Stage 1: *Proposal* - -An RFC at the *proposal* stage is a solution to a problem with enough fidelity -to be discussed in detail. It must be backed by a willing *champion*. A -*proposal*'s goal is to make a compelling case for acceptance by describing -both the problem and the solution via examples and spec edits. A *proposal* -should be a pull request. - -*Entrance criteria:* - -* Identified *champion* -* Clear explanation of problem and solution -* Illustrative examples -* Incomplete spec edits -* Identification of potential concerns, challenges, and drawbacks - -A *proposal* is subject to the same discussion as a *strawman*: ensuring that it -is well aligned with the *guiding principles*, is a problem worth solving, and -is the preferred solution to that problem. A *champion* is not expected to have -confidence in every detail at this stage and should instead focus on identifying -and resolving issues and edge-cases. To better understand the technical -ramifications of the *proposal*, a *champion* is encouraged to implement it in a -AsyncAPI library. - -Most *proposals* are expected to evolve or change and may be rejected. Therefore, -it is unwise to rely on a *proposal* in a production environment. AsyncAPI -libraries *may* implement *proposals*, though are encouraged to not enable the -*proposed* feature without explicit opt-in. - - -## Stage 2: *Draft* - -An RFC at the *draft* stage is a fully formed solution. There is -consensus the problem identified should be solved, and this particular solution -is preferred. A *draft's* goal is to precisely and completely describe the -solution and resolve any concerns through library implementations. A *draft* -must be a pull request. - -*Entrance criteria:* - -* Consensus the solution is preferred -* Resolution of identified concerns and challenges -* Precisely described with spec edits -* Compliant implementation in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas) (might not be merged) - -A *proposal* becomes a *draft* when the set of problems or drawbacks have been -fully considered and accepted or resolved, and the solution is deemed -desirable. A *draft*'s goal is to complete final spec edits that are ready to -be merged and implement the *draft* in AsyncAPI libraries along with tests to -gain confidence that the spec text is sufficient. - -*Drafts* may continue to evolve and change, occasionally dramatically, and are -not guaranteed to be accepted. Therefore, it is unwise to rely on a *draft* in a -production environment. AsyncAPI libraries *should* implement *drafts* to -provide valuable feedback, though are encouraged not to enable the *draft* -feature without explicit opt-in when possible. - - -## Stage 3: *Accepted* - -An RFC at the *accepted* stage is a completed solution. According to a spec -Committer it is ready to be merged as-is into the spec document. The RFC is -ready to be deployed in AsyncAPI libraries. An *accepted* RFC must be -implemented in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas). - -*Entrance criteria:* - -* Consensus the solution is complete -* Complete spec edits, including examples and prose -* Compliant implementation in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas) (fully tested and merged or ready to merge) - -A *draft* is *accepted* when the Committers have been convinced via -implementations and tests that it appropriately handles all edge cases; that the -spec changes not only precisely describe the new syntax and semantics but -include sufficient motivating prose and examples; and that the RFC includes -edits to any other affected areas of the spec. Once *accepted*, its *champion* -should encourage adoption of the RFC by opening issues or pull requests on other -popular AsyncAPI libraries. - -An *accepted* RFC is merged into the AsyncAPI spec's master branch by a Committer -and will be included in the next released revision. - - -## Stage X: *Rejected* - -An RFC may be *rejected* at any point and for any reason. Most rejections occur -when a *strawman* is proven to be unnecessary, is misaligned with the *guiding -principles*, or fails to meet the entrance criteria to become a *proposal*. -A *proposal* may become *rejected* for similar reasons as well as if it fails to -reach consensus or loses the confidence of its *champion*. Likewise a *draft* -may encounter unforeseen issues during implementations which cause it to lose -consensus or the confidence of its *champion*. - -RFCs which have lost a *champion* will not be *rejected* immediately, but may -become *rejected* if they fail to attract a new *champion*. - -Once *rejected*, an RFC will typically not be reconsidered. Reconsideration is -possible if a *champion* believes the original reason for rejection no longer -applies due to new circumstances or new evidence. - - -## Merging pull requests - -A pull request can be merged if all the following conditions are met: - -* There is, at least, a mininum of 3 approvals from the [repository code owners](./CODEOWNERS). -* Sufficient time has passed to let all code owners review the pull request. As of now, it should be a minimum of 1 week. If all code owners have already approved a pull request, it's ok not to wait for this period of time. - -``` - -## References -This document was adapted from the [GraphQL Specification Contribution Guide](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md). \ No newline at end of file +- Pull request with new or improved extension will be merged only if there is compliant implementation in the the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas), [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI React component](https://github.com/asyncapi/asyncapi-react). +- You do not have to fulfil all the requirements upon pull request creation. First focus on documentation and a use case. Once maintainers of the catalog tell you that it is the right time to work on tooling implementation, then start doing it or fund volunteers that can help. From a1415d1c07ff61f59f7ef1d41f026eceaae1c300 Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <81870866+sambhavgupta0705@users.noreply.github.com> Date: Thu, 9 Nov 2023 12:55:52 +0530 Subject: [PATCH 07/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9cf61ea..cafbbe4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,5 +11,6 @@ to better understand expected and unacceptable behavior. - Explain the use case, - Try to improve existing extensions, before you contribute a competing one, - Start discussion with an issue. Don't start with pull request first. +- All the extensions file must be place in [Extensions folder](https://github.com/asyncapi/extensions-catalog/tree/master/extensions) - Pull request with new or improved extension will be merged only if there is compliant implementation in the the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas), [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI React component](https://github.com/asyncapi/asyncapi-react). - You do not have to fulfil all the requirements upon pull request creation. First focus on documentation and a use case. Once maintainers of the catalog tell you that it is the right time to work on tooling implementation, then start doing it or fund volunteers that can help. From 0ef3bdb3e928330c3015d842d663dd9cf8d05356 Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <81870866+sambhavgupta0705@users.noreply.github.com> Date: Thu, 9 Nov 2023 13:00:19 +0530 Subject: [PATCH 08/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cafbbe4..475d383 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,6 +11,7 @@ to better understand expected and unacceptable behavior. - Explain the use case, - Try to improve existing extensions, before you contribute a competing one, - Start discussion with an issue. Don't start with pull request first. -- All the extensions file must be place in [Extensions folder](https://github.com/asyncapi/extensions-catalog/tree/master/extensions) +- All the extensions file must be place in [extensions folder](https://github.com/asyncapi/extensions-catalog/tree/master/extensions) +- Follow the correct file name structure starting with the name of the extension in lowercase. - Pull request with new or improved extension will be merged only if there is compliant implementation in the the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas), [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI React component](https://github.com/asyncapi/asyncapi-react). - You do not have to fulfil all the requirements upon pull request creation. First focus on documentation and a use case. Once maintainers of the catalog tell you that it is the right time to work on tooling implementation, then start doing it or fund volunteers that can help. From 1e8953398c245b9670452826b39e39b01b83eae8 Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <81870866+sambhavgupta0705@users.noreply.github.com> Date: Sat, 11 Nov 2023 15:35:43 +0530 Subject: [PATCH 09/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 475d383..17f1c30 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ to better understand expected and unacceptable behavior. - Explain the use case, - Try to improve existing extensions, before you contribute a competing one, - Start discussion with an issue. Don't start with pull request first. -- All the extensions file must be place in [extensions folder](https://github.com/asyncapi/extensions-catalog/tree/master/extensions) -- Follow the correct file name structure starting with the name of the extension in lowercase. +- Every extension file needs to be located in [extensions folder](https://github.com/asyncapi/extensions-catalog/tree/master/extensions) +- Observe the proper file naming convention, which calls for the lowercase name of the extension first. - Pull request with new or improved extension will be merged only if there is compliant implementation in the the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas), [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI React component](https://github.com/asyncapi/asyncapi-react). - You do not have to fulfil all the requirements upon pull request creation. First focus on documentation and a use case. Once maintainers of the catalog tell you that it is the right time to work on tooling implementation, then start doing it or fund volunteers that can help. From 6a478380e72a7739d3e9973a6c2b23a444fa8f18 Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <81870866+sambhavgupta0705@users.noreply.github.com> Date: Fri, 19 Jan 2024 12:30:46 +0530 Subject: [PATCH 10/12] Update CONTRIBUTING.md Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 17f1c30..c5221f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,5 +13,5 @@ to better understand expected and unacceptable behavior. - Start discussion with an issue. Don't start with pull request first. - Every extension file needs to be located in [extensions folder](https://github.com/asyncapi/extensions-catalog/tree/master/extensions) - Observe the proper file naming convention, which calls for the lowercase name of the extension first. -- Pull request with new or improved extension will be merged only if there is compliant implementation in the the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas), [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI React component](https://github.com/asyncapi/asyncapi-react). +- Pull request with new or improved extension will be merged only if there is compliant implementation in the the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas), and the [AsyncAPI React component](https://github.com/asyncapi/asyncapi-react). - You do not have to fulfil all the requirements upon pull request creation. First focus on documentation and a use case. Once maintainers of the catalog tell you that it is the right time to work on tooling implementation, then start doing it or fund volunteers that can help. From 5e1a1ab49fa87087c06714601dc0a7a6de28c9ca Mon Sep 17 00:00:00 2001 From: Sambhav Gupta <sambhavgupta0705@gmail.com> Date: Thu, 15 Feb 2024 11:09:46 +0530 Subject: [PATCH 11/12] feat: added the version of the x extension --- extensions/x.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/extensions/x.md b/extensions/x.md index 48c0d03..2eb5f19 100644 --- a/extensions/x.md +++ b/extensions/x.md @@ -4,6 +4,9 @@ This document defines how to use `twitter` extension in AsyncAPI documents. ## Overview This extension allows you to provide the Twitter username of the account representing the team/company of the API. +## Version +Current version is `0.1.0`. + ## Extension Definition ### Type: String From 814c2c026700eb0aff58ee1d0b4a3719459fdb2d Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki <lpgornicki@gmail.com> Date: Thu, 18 Apr 2024 11:22:16 +0200 Subject: [PATCH 12/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c5221f7..5d1a884 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,5 +13,5 @@ to better understand expected and unacceptable behavior. - Start discussion with an issue. Don't start with pull request first. - Every extension file needs to be located in [extensions folder](https://github.com/asyncapi/extensions-catalog/tree/master/extensions) - Observe the proper file naming convention, which calls for the lowercase name of the extension first. -- Pull request with new or improved extension will be merged only if there is compliant implementation in the the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas), and the [AsyncAPI React component](https://github.com/asyncapi/asyncapi-react). +- Pull request with new or improved extension will be merged only if there is compliant implementation in the the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas). - You do not have to fulfil all the requirements upon pull request creation. First focus on documentation and a use case. Once maintainers of the catalog tell you that it is the right time to work on tooling implementation, then start doing it or fund volunteers that can help.