docs: how changes in the spec are introduced

[AceTheCreator]

Description
This PR contains well-detailed documentation of how changes in the specification are introduced

CC @jonaslagoni @fmvilas @derberg @alequetzalli

[derberg]

@AceTheCreator excellent input!

Not sure what @alequetzalli and @fmvilas think but I think it could easily be converted into an article. And then this document from this PR could be a bit "formalized".

I just think docs should be as short as possible. When someone looks into docs, they look for solution, not "story". This is what blog posts are for.

The only thing you can count on is change. That’s especially true in the world of product and system development. So if you are tasked with leading the charge for your company's product development, it is vital that you stay (or become) dynamic. That's why we at AsyncAPI always try to stay dynamic by introducing new changes based on users' requirement, either by adding new features or by removing existing/deprecated ones.

☝🏼 is perfect for article. The style of massage is great!

the same as documentation:

Changes in the specification are released on a regular basis, four times a year with the support of a dedicated release coordinator. Learn more from [the official release process instruction] (https://github.com/asyncapi/spec/blob/master/RELEASE_PROCESS.md).

Anyone can introduce changes. Every change needs a champion who wants to push the change through all the stages of an RFC (request for change) documented in details in [the official contribution guide for the spec](https://github.com/asyncapi/spec/blob/master/CONTRIBUTING.md).

@AceTheCreator you know what I mean?

@alequetzalli @fmvilas what are your thoughts?

[AceTheCreator]

@derberg are you suggesting I convert this to an article and extract the docs out of it?

[derberg]

@AceTheCreator yes, imho this could be a great article, and only the essence should be a documentation

but let's first see what others thing. I might be completely wrong

[quetzalliwrites]

I agree with @derberg, this PR is a great blog post; but docs should be succinct.

@AceTheCreator, here's some tips for your next iteration of these community docs on spec changes:

• think of the top workflows a spec contributor needs to follow & make those your main headers/sections
• question every sentence you want to add; longer doesn't mean better, it means a longer document to sift through 👀
• remove all sentences that ramble about "how we do stuff at AsyncAPI"; we should write sentences that are to the point and only discuss directions on how to introduce spec changes and the process
• this document has not been through Grammarly; all new written content should be run through Grammarly FIRST before being put up for review

[AceTheCreator]

@derberg and @alequetzalli kindly share your thoughts

[fmvilas]

Yeah, I agree this would make a great blog post. And also a good live stream! Just saying :)

[quetzalliwrites]

getting there! ✌🏽

[AceTheCreator]

@alequetzalli I basically copied the whole content and pasted it into the Grammarly essay checker. I resolved the suggested changes but it says there's more but I have to have access to their premium package :(

[quetzalliwrites]

another review 😄✌🏽 ✨✨✨✨ hehe

[AceTheCreator]

Thanks for the reviews @alequetzalli. Any other suggestions?

[quetzalliwrites]

looking good 😄

[AceTheCreator]

@derberg @fmvilas any suggestions?

[derberg]

diagram is awesome but it links wrong elements I think

cause it looks like, for example, that it is Specification that performs review, not Maintainer. Also looks like Specification looks for release coordinator, not Maintainers

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

[AceTheCreator]

Sorry @derberg what do you mean by the specification looks for release coordinator?

[AceTheCreator]

@derberg

[derberg]

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

[AceTheCreator]

what do you think about my proposal?

Makes sense. I'll update the PR

[AceTheCreator]

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

I think this would be a perfect opportunity for me. Thanks for bringing it up

[AceTheCreator]

Updated the PR @derberg @alequetzalli

[derberg]

@AceTheCreator just to confirm, so you want to merge it before you complete the release coordination task? isn't it better to do release 2.6 and then you will see if something needs approval here? we are not in rush right?

[AceTheCreator]

@AceTheCreator just to confirm, so you want to merge it before you complete the release coordination task? isn't it better to do release 2.6 and then you will see if something needs approval here? we are not in rush right?

You are right, I'm not merging it yet :)

[derberg]

btw initial first version, in blog post style was also good.

followup article about the topic from your perspective as release coordinator would be great 😉

[AceTheCreator]

btw initial first version, in blog post style was also good.

followup article about the topic from your perspective as release coordinator would be great 😉

I still have the draft of the initial version... So yeah, I'll probably turn it into an article :)