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

docs: how changes in the spec are introduced #488

Merged
merged 57 commits into from
Mar 14, 2023
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
57 commits
Select commit Hold shift + click to select a range
b93329f
added a new documentation
AceTheCreator Oct 7, 2022
d0e4985
Merge branch 'master' into docs
quetzalliwrites Oct 12, 2022
0edff5d
ehnaced docs
AceTheCreator Oct 12, 2022
00ce177
Merge branch 'master' into docs
quetzalliwrites Oct 17, 2022
6de33e5
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Oct 18, 2022
3027eb1
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Oct 18, 2022
0d82923
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Oct 18, 2022
8f6be9e
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Oct 18, 2022
59c57c3
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Oct 18, 2022
ebbbb75
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Oct 18, 2022
fdb5f02
Updated How changes in spec are introduced file
AceTheCreator Oct 18, 2022
6b1f18b
.
AceTheCreator Oct 18, 2022
f4efc63
Merge branch 'master' into docs
quetzalliwrites Oct 19, 2022
1aedfe9
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 7, 2022
08f1e37
Merge branch 'master' into docs
quetzalliwrites Nov 9, 2022
b85233e
updated docs
AceTheCreator Nov 11, 2022
11b44e0
Merge branch 'docs' of github.com:AceTheCreator/community into docs
AceTheCreator Nov 11, 2022
9ffa5b8
Merge branch 'master' into docs
quetzalliwrites Nov 15, 2022
274232b
enhanced the doc
AceTheCreator Nov 18, 2022
9570e24
Merge branch 'docs' of github.com:AceTheCreator/community into docs
AceTheCreator Nov 18, 2022
064543b
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
6b4932d
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
3b9ac8f
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
8e634da
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
5c16bdd
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
1953acf
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
00a9727
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
5dda8d8
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
5d9e1ac
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
2522b6a
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
46dfc2d
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
3040466
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
05dc526
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
791cc4b
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Nov 21, 2022
444b5ed
updated mermaid diagram with valid syntax
AceTheCreator Nov 21, 2022
9ccc457
Merge branch 'master' into docs
quetzalliwrites Nov 22, 2022
fb68107
edits
quetzalliwrites Nov 22, 2022
037a13c
more edits
quetzalliwrites Nov 22, 2022
e7bfcf2
Merge branch 'master' into docs
quetzalliwrites Nov 23, 2022
44e2229
docs readme
AceTheCreator Nov 25, 2022
bc79afc
.
AceTheCreator Nov 25, 2022
4280c3f
Merge branch 'master' into docs
quetzalliwrites Dec 3, 2022
0cfcf5d
Update docs/README.md
AceTheCreator Dec 5, 2022
6b48046
Merge branch 'master' into docs
quetzalliwrites Dec 10, 2022
614911c
Update docs/README.md
AceTheCreator Dec 12, 2022
32a340d
Update docs/README.md
AceTheCreator Dec 12, 2022
8e8874e
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Dec 12, 2022
cccd4b8
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Dec 12, 2022
68df1b4
Update docs/how-changes-in-the-spec-are-introduced.md
AceTheCreator Dec 12, 2022
f2a9a95
Merge branch 'master' into docs
quetzalliwrites Dec 14, 2022
46f790f
Merge branch 'master' into docs
quetzalliwrites Dec 20, 2022
87a1459
Merge branch 'master' of github.com:AceTheCreator/community into docs
AceTheCreator Jan 17, 2023
89b99e4
updated mermaid diagram
AceTheCreator Jan 17, 2023
eab8f24
Merge branches 'docs' and 'docs' of github.com:AceTheCreator/communit…
AceTheCreator Jan 17, 2023
9f13c57
Merge branch 'master' into docs
AceTheCreator Jan 18, 2023
db9a6b9
Merge branch 'master' into docs
quetzalliwrites Jan 23, 2023
ffbf9b6
Merge branch 'master' into docs
AceTheCreator Mar 14, 2023
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
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
__docs__ folder for community related documentation.
Copy link
Member

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?

Copy link
Member Author

@AceTheCreator AceTheCreator Nov 21, 2022

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

Copy link
Member

@quetzalliwrites quetzalliwrites Nov 22, 2022

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 :)

Copy link
Member Author

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 :)

Copy link
Member Author

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 😄

34 changes: 34 additions & 0 deletions docs/how-changes-in-the-spec-are-introduced.md
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
Copy link
Member

Choose a reason for hiding this comment

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

Choose a reason for hiding this comment

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

AsyncAPI member kinda suggests you need to become some kind of member to be a champion. But anyone can be a champion really


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

Choose a reason for hiding this comment

The 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.**