Remove spec docs duplication

[derberg]

Reason/Context

With specification, we have at the moment the following situation.
1 https://github.com/asyncapi/spec/blob/2.0.0/versions/2.0.0/asyncapi.md is the location of official specification
2 https://github.com/asyncapi/spec/blob/2021-06-release/spec/asyncapi.md is the candidate for next release
3 https://github.com/asyncapi/website/blob/master/pages/docs/specifications/2.0.0.md 2.0 spec duplicate that should not be edited in website but automatically updated from spec repo

Description

In short, on every release in spec (no matter if official or pre-release) update website through PR so after automerge it is automatically published.

not in scope
Automation of spec release. The creation of GitHub releases for latest and candidates. Just assume it will be in place, so automation from this task should be based on GitHub release event. How you can tell that release is a release candidate? it is marked as Pre-release and the release tag will look something like v2.1.0-2021-06-release.1 (some example from another project https://github.com/asyncapi/asyncapi-react/releases/tag/v1.0.0-next.2)

Website repo

• this link https://www.asyncapi.com/docs/specifications/latest should always display the latest spec version
• link in the left-hand side navigation should point to the latest only
• versions >=2.0.0 should be available on website too, there must be a toggle/dropdown that you can use to switch between versions. Direct links should also be available.
• next version, the release candidate should also be available in the UI, marked as release candidate for next version, with release date
• Edit this page on Github should not take you to website but to spec repository where spec is located and actually ug fixes can be suggested

Spec repo

• we need update in the spec in https://github.com/asyncapi/spec/blob/2021-06-release/spec/asyncapi.md to support website features, frontmatter and anchors in sections
• now how to get updates from spec repo into website? I suggest push approach rather then pull. In other words, spec repo pushes changes to website repo instead of website repo pulling for changes from spec. We need GitHub Action workflow that would be triggered on every release, it would pick up changes either from master (in case of official release when tag is createdor from the release branch (in case there is a pre-release). In the workflow you would need to pullwebsite`, add proper files there and then open a PR using proper GH action. Auto approve and merge is already in place, because you will use asyncapi bot here.

hints

• feel free to ping me or @magicmatatjahu that also recently played a lot with workflows related to release candidates, and had to figure out how to check release type in the workflow https://github.com/asyncapi/asyncapi-react/blob/master/.github/workflows/release-wc-and-playground.yml#L15
• in case there will need to be some custom js code used in workflow:
  • if there is not much of it needed, then get inspiration from https://github.com/asyncapi/.github/blob/master/.github/workflows/release-announcements.yml#L29
  • otherwise see this workflow https://github.com/asyncapi/generator/blob/master/.github/workflows/templates-list-validation.yml where we have a simple action that is not published on official list of GH actions https://github.com/asyncapi/generator/tree/master/.github/templates-list-validator

[fmvilas]

this link https://www.asyncapi.com/docs/specifications/2.0.0 should always display the latest spec version

I guess you meant https://www.asyncapi.com/docs/specifications/latest, right? it's currently being redirected here: https://github.com/asyncapi/website/blob/master/public/_redirects#L8. Also, let's make sure it never redirects using 301 because this will make the redirect permanent and will be cached by browsers.

there must be a google that you can use to switch between versions.

a google? 🤔

[derberg]

a google?

toggle, drop down, come version chooser component 😛

I guess you meant https://www.asyncapi.com/docs/specifications/latest, right?

right, updated, thanks. I also think https://www.asyncapi.com/docs/specifications should redirect to latest

[aayushmau5]

I would like to work on this.(Just commenting here for the Issue)

[derberg]

just for your information, I realized we do not need a feature toggle as we have left nav anyway and all specs will be listed there, so no need to add additional navigation element - toggle

[aayushmau5]

Do we have any specific design to show that a spec is "Pre-release"?

For the time being, I'm just doing

[derberg]

this is fixed by @aayushmau5 now

[aayushmau5]

I guess, we should close this issue now. :D