-
-
Notifications
You must be signed in to change notification settings - Fork 112
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
docs: how changes in the spec are introduced #488
Merged
Merged
Changes from 50 commits
Commits
Show all changes
57 commits
Select commit
Hold shift + click to select a range
b93329f
added a new documentation
AceTheCreator d0e4985
Merge branch 'master' into docs
quetzalliwrites 0edff5d
ehnaced docs
AceTheCreator 00ce177
Merge branch 'master' into docs
quetzalliwrites 6de33e5
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 3027eb1
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 0d82923
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 8f6be9e
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 59c57c3
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator ebbbb75
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator fdb5f02
Updated How changes in spec are introduced file
AceTheCreator 6b1f18b
.
AceTheCreator f4efc63
Merge branch 'master' into docs
quetzalliwrites 1aedfe9
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 08f1e37
Merge branch 'master' into docs
quetzalliwrites b85233e
updated docs
AceTheCreator 11b44e0
Merge branch 'docs' of github.com:AceTheCreator/community into docs
AceTheCreator 9ffa5b8
Merge branch 'master' into docs
quetzalliwrites 274232b
enhanced the doc
AceTheCreator 9570e24
Merge branch 'docs' of github.com:AceTheCreator/community into docs
AceTheCreator 064543b
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 6b4932d
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 3b9ac8f
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 8e634da
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 5c16bdd
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 1953acf
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 00a9727
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 5dda8d8
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 5d9e1ac
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 2522b6a
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 46dfc2d
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 3040466
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 05dc526
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 791cc4b
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 444b5ed
updated mermaid diagram with valid syntax
AceTheCreator 9ccc457
Merge branch 'master' into docs
quetzalliwrites fb68107
edits
quetzalliwrites 037a13c
more edits
quetzalliwrites e7bfcf2
Merge branch 'master' into docs
quetzalliwrites 44e2229
docs readme
AceTheCreator bc79afc
.
AceTheCreator 4280c3f
Merge branch 'master' into docs
quetzalliwrites 0cfcf5d
Update docs/README.md
AceTheCreator 6b48046
Merge branch 'master' into docs
quetzalliwrites 614911c
Update docs/README.md
AceTheCreator 32a340d
Update docs/README.md
AceTheCreator 8e8874e
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator cccd4b8
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator 68df1b4
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator f2a9a95
Merge branch 'master' into docs
quetzalliwrites 46f790f
Merge branch 'master' into docs
quetzalliwrites 87a1459
Merge branch 'master' of github.com:AceTheCreator/community into docs
AceTheCreator 89b99e4
updated mermaid diagram
AceTheCreator eab8f24
Merge branches 'docs' and 'docs' of github.com:AceTheCreator/communit…
AceTheCreator 9f13c57
Merge branch 'master' into docs
AceTheCreator db9a6b9
Merge branch 'master' into docs
quetzalliwrites ffbf9b6
Merge branch 'master' into docs
AceTheCreator File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
## Community Documentation | ||
|
||
The community documentation directory helps the community collaboratively maintain a collection of helpful community-related documentation. From becoming an AsyncAPI contributor to becoming a TSC member, and beyond. |
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,71 @@ | ||
|
||
## How spec changes are introduced | ||
AsyncAPI Initiative always concentrates on the problems rather than the solution. This is because you are generally rather single-minded when you already have a solution in mind to a problem instead of fully diving into the issue, seeing alternatives, and finding the best solution. | ||
|
||
### RFCs & champions | ||
Some changes, however, are "substantial," We ask that these be put through a bit of a design process and produce a consensus among the AsyncAPI contributors/maintainers. The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features to enter the project. | ||
|
||
#### What is an RFC? | ||
RFC is a document that proposes an idea and serves as high-level documentation of the concept and its thinking. | ||
|
||
AsyncAPI finds this valuable because it makes prototyping an idea with words easy and flexible rather than immediately diving into an idea. RFCs force champions to explore the idea, document it and create a proposal for bringing it to life. | ||
|
||
#### Who is a champion? | ||
A Champion takes ownership of an idea and follows the proposed process to make the idea a reality. | ||
|
||
## Spec changes lifecycle | ||
The motivation for the Changes process is to raise the visibility of planned changes and make coordination and planning efforts easier. It is nearly impossible to follow all changes in a big project such as AsyncAPI spec. By providing a mechanism for sharing changes, it is easier for contributors to know what is coming and to ensure that we can address the impacts of changes well before the release date. The spec changes lifecycle consist of 2 parts, as seen below. | ||
|
||
### Change process | ||
|
||
- The author submits the change proposal by creating a discussion about the proposed changes. The person or group proposing the change is responsible for providing the first draft of the changes. Ideally, it's preferable to make this draft available as a pull request before submitting the Change proposal so the community can evaluate the change. However, starting with an issue is also permitted if the full details are not worked out. | ||
|
||
- The contributors/maintainers reviews the proposed change request. The goal of this check is to prove or disprove a problem and guide the discussion toward either rejection or a preferred solution. | ||
|
||
- Implement the change. The author doesn't have to be the one to implement the change proposed but keep in mind that it might take a while before someone else does. | ||
|
||
- Possibly iterate/refine as the community gets experience with your proposed changes. There may be some additional feedback about design choices that might be adjusted. | ||
|
||
- Test implementation to gain confidence. When your change implementation is baked enough, and the solution seems desirable, there will be a compliant implementation with the AsyncAPI libraries and a test to gain confidence. | ||
|
||
### How changes are introduced in spec: example | ||
|
||
#### feat: added server variable object as a reusable object | ||
Let's see how Daniel Kocot proposed and championed a feature for the next spec release. | ||
- He started a discussion on why his proposal was made. [#707](https://github.com/asyncapi/spec/issues/707) | ||
- He opened a PR for his proposed change, which was reviewed by the contributors/maintainers. [#717](https://github.com/asyncapi/spec/pull/717) | ||
- After review and potential improvement, he did a compliant implementation of his feature with [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and [spec-json-schemas](https://github.com/asyncapi/spec-json-schemas/pull/250) simply because it's a critical requirement. | ||
- Since the implementation was a success, his proposed change got approved and made it to the next release. | ||
|
||
Check out our [how to contribute guide](https://github.com/asyncapi/spec/blob/master/CONTRIBUTING.md) to learn more. | ||
|
||
### Release process | ||
This part of the lifecycle aims to describe all details of the process so that any community member can jump in and help coordinate. | ||
|
||
- We have four cycles a year for release, and they have a single coordinator. | ||
- Your contribution is made against the `next-spec` branch in 3 repositories. | ||
- The coordinator at the beginning of the cycle checks if there are any release candidates. You know, like PRs that are in the advanced stage and have potential. | ||
- The coordinator keeps a closed watch on what is merged, documents it in release notes, and engages contributors and maintainers of the spec to collaborate on a release. | ||
- Maintainers trigger release when ready, release notes are published, and the world of open source won again. | ||
|
||
Learn more about the [release process](https://github.com/asyncapi/spec/blob/master/RELEASE_PROCESS.md#what). | ||
|
||
### Release process visual | ||
The image below visualizes the whole process of how changes are introduced to the spec in a single glance. | ||
|
||
```mermaid | ||
sequenceDiagram | ||
Contributor->>+Specification: Propose RFC as an issue/PR | ||
Specification-->>+Contributor: Initial review and request for Champion | ||
Contributor->>+Specification: Further contribution through different stages to different repositories | ||
Specification-->>-Contributor: Possible multiple review rounds | ||
Contributor->>+Specification: Potential improvement and compliant implementation | ||
Specification-->>-Contributor: Proposal acceptance and preperation for next release | ||
Specification->>+Release Coordinator: Request for a release coordinator | ||
Release Coordinator-->>-Specification: Review of possible release candidates | ||
Release Coordinator-->>+Contributor: Indicate what is missing to have things release in current cycle | ||
Release Coordinator->>+Maintainer: Ping maintainers so they are aware of the release | ||
Maintainer-->>-Specification: Publish Release | ||
Release Coordinator->>+Maintainer: Ping tools maintainers about new release | ||
Release Coordinator ->>+ Community: Notify Community about new release | ||
``` |
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.
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.
diagram is awesome but it links wrong elements I think
cause it looks like, for example, that it is
Specification
that performs review, notMaintainer
. Also looks likeSpecification
looks for release coordinator, notMaintainers
how about https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqlVMFu2zAM_RVC1zXY3Yde0hXYYUPgXnNhZDomZkkeJSULiv57KSduvGxpAzSAA5kmHx_fo_1sbGjIVCbS70ze0gPjVtCtPehvGXwS3uQUZHF__-VpIMstW0wcfAUrCUOIBPXjEjACeuAYM31d1cfqH8g-6UUSF6V8hlbBd8-JsQehHdNeixs9KoWYoA0Cyw7doF0mHs5lLTh8Gue9eR6zpI4E7JSlUUidhLztoOG2JSGfICbcUoQUZjEhVYIVlineMPwqxMibnsDlPvGghxN97eWb-OHQN9a_a15ISrwox26QsCNX5ijy2eCGnlHv9Ek_xseaW-YaN0Ix0VoaEuo-jZCD6kMyooyuePpTNOsJI_0LO6KeZq-gnrmJU5GSDNKwR20Lu9Bnn4jkCFWfUpazlIIJM9CfIXF7OEfUZkxKa39ucLAqq3otKV7FXfxH2ProRGhhmFx6w1QtuMFEHyBeLHhTsAn2hSJHcPqWsd-WBexwR0pd7-JbE_Zgs4xbOc5wvZV2msmu7hVUd45ADApOB0BRG_flX6fSyNWBLpfjcufypufYTWQ-YRduQv7LL3NnHImSb_Rb9lyQ10aZOlqbSo8Nyq-1WfsXzctDYfytKa-rqVrsI90ZVLGfDt6aKkmmKen0MTxlvbwC8Mbb5A
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.
Sorry @derberg what do you mean by the specification looks for release coordinator?
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.
@derberg
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 do you think about my proposal?
also, since you work on this one, and we also plan to release spec 2.6 this months, and we do not have release coordinator, maybe you consider being one, so you will see in action the process? just a hint, no obligation
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.
Makes sense. I'll update the PR
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 think this would be a perfect opportunity for me. Thanks for bringing it up