-
-
Notifications
You must be signed in to change notification settings - Fork 111
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
Changes from 4 commits
b93329f
d0e4985
0edff5d
00ce177
6de33e5
3027eb1
0d82923
8f6be9e
59c57c3
ebbbb75
fdb5f02
6b1f18b
f4efc63
1aedfe9
08f1e37
b85233e
11b44e0
9ffa5b8
274232b
9570e24
064543b
6b4932d
3b9ac8f
8e634da
5c16bdd
1953acf
00a9727
5dda8d8
5d9e1ac
2522b6a
46dfc2d
3040466
05dc526
791cc4b
444b5ed
9ccc457
fb68107
037a13c
e7bfcf2
44e2229
bc79afc
4280c3f
0cfcf5d
6b48046
614911c
32a340d
8e8874e
cccd4b8
68df1b4
f2a9a95
46f790f
87a1459
89b99e4
eab8f24
9f13c57
db9a6b9
ffbf9b6
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 |
---|---|---|
@@ -0,0 +1 @@ | ||
__docs__ folder for community related documentation. | ||
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
# How changes in the spec are made | ||
derberg marked this conversation as resolved.
Show resolved
Hide resolved
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. you still do not link to main contributing guide |
||
AsyncAPI initiative always focus on the problems and not so much on the solution. The reason for this is that generally, you are rather single-minded when you already have a solution in mind to a problem. Instead of fully diving into the problem and seeing alternatives and finding the best solution. | ||
|
||
## RFCs & Champions | ||
AceTheCreator marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Many changes, including bug fixes and documentation improvements, can be implemented and reviewed via the normal GitHub pull request workflow. | ||
|
||
Some changes, however, are “substantial”, and we ask that these be put through a bit of a design process and produce a consensus among the AsyncAPI core team. The “RFC” (request for comments) process is intended to provide a consistent and controlled path for new features to enter the project. | ||
|
||
### What is RFC? | ||
AceTheCreator marked this conversation as resolved.
Show resolved
Hide resolved
|
||
An RFC is a document that proposes an idea and serves as high-level documentation of the idea and the thinking behind it. | ||
|
||
AsyncAPI finds this RFC useful because it makes prototyping an idea with words easy and flexible rather than immediately diving into an idea, and RFCs forces champions to first explore the idea, document it, and create a proposal for bringing it to life. | ||
### Who is a champion? | ||
AceTheCreator marked this conversation as resolved.
Show resolved
Hide resolved
|
||
A Champion is any AsyncAPI member that takes ownership of an idea and follows the proposed process to make the idea a reality. | ||
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.
|
||
|
||
## The spec changes lifecycle | ||
Before the introduction of new spec changes, the changes have to go through various stages. | ||
### RFCs proposal | ||
AceTheCreator marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Many changes to the AsyncAPI specification have been proposed, and contributing to AsyncAPI requires a lot of dedicated work. So, in order to set clear expectations and provide accountability, and advance through the AsyncAPI specification review process, each proposed RFC (request for comments) must have a _champion_ who is responsible for addressing feedback and completing the next steps. | ||
### Implementing RFCs | ||
AceTheCreator marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Once the RFC becomes active(by active I mean once an RFC starts getting engagement by fellow contributors), the authors may implement it and submit the feature as a pull request to the spec repo or start with an issue if the full details are not worked out. | ||
AceTheCreator marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
The author of an RFC is not obligated to implement it. The RFC author (like any other developer) is welcome to post implementations for review after the RFC has been accepted. | ||
|
||
If you are interested in working on the implementation for an ‘active’ RFC, but cannot determine if someone else is already working on it, feel free to ask (e.g. by leaving a comment on the associated issue). | ||
### Contributors/Maintainers engagement | ||
Modifications to active RFCs can be done by contributing to the discussion/commenting on it. We strive to write each RFC in a manner that will reflect the final design of the feature; but the nature of the process means that we cannot expect every accepted RFC to actually reflect what the end result will be at the time of the next major release; therefore we try to keep each RFC document somewhat in sync with the language feature as planned, tracking such changes via followup changes to the document. | ||
|
||
### Reviewing RFCs | ||
AceTheCreator marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Maintainers and contributors will attempt to review some set of open RFC discussions frequently and a group of maintainers and contributors come together bi-weekly before the next major release of the specification with a common goal/deliverables. Note that these meetings are not specifically for major versions, it basically comes down to what is needed, and what the release coordinator/other thinks. | ||
|
||
Every accepted feature should have a core team champion, who will represent the feature and its progress. | ||
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 do you mean by core team champion? |
||
|
||
**AsyncAPI has an active and mutually beneficial relationship with its many implementations. The AsyncAPI specification is continuously evolving under the care of the community, which consists of AsyncAPI spec experts, contributors, and implementers. At any given time, AsyncAPI specification updates are a combination of anticipatory planning with documentation of patterns and behaviors that are already proven in production, sometimes at a very large scale.** |
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, I don't understand why this file is being added?
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.
To indicate that the docs folder basically holds all docs related to the community
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.
but why do are have a readme page with only a phrase written on it? that doesn't seem complete...sorry lmk if my question makes more sense now :)
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, it does makes sense :)
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.
Btw, I couldn't think of a long readME for the docs 😄