AsyncAPI v3 related changes and website freeze

[jonaslagoni]

Reason/Context

In the last spec 3.0 meeting we discussed how we could slowly make changes to the website to fit it for v3 while still giving users access to v2 resources. We landed on the following suggestions:

• We create a temporary branch called next_major_spec (this is what all other tools are using) to merge any related v3 changes into. Once we release v3, we merge that branch into master.
• We will then deploy the latest commit before the merge on a sub-domain as frozen resources (never changes), where all the resources on v2 can be found, for example, v2.asyncapi.com.

What do you think?

[derberg]

I don't think there is a better solution.

we just need to remember to not SEO v2.asyncapi.com. Then in asyncapi.com/docs we only have 3.0.0 under Reference bucket with some additional panel where v2 can be found. Probably better to have a more generic panel about v2 or just some version switcher

@alequetzalli @akshatnema we need your input and agreement

[fmvilas]

Minor comment: it should be next-major-spec, to match the rest of the repos.

And yeah as I said in the meeting I agree with that.

[akshatnema]

Will v2.asyncapi.com work as an normal website of AsyncAPI as well? If yes, we are creating a duplicacy of website content if it is not consistent with asyncapi.com.

[jonaslagoni]

Will v2.asyncapi.com work as an normal website of AsyncAPI as well

Depends on how you want to achieve it, in the meeting we discussed that it could just be a read-only format, where we could have adapted it to link to v3 in all the relevant pages.

[derberg]

with robot.txt we can make sure v2.asyncapi.com is not traversed and there can be a big banner on every page that it is old. Even certain navigation items can be removed, including content.

Idea is that it is just one-time created old view of old docs. Just for reference

[akshatnema]

I agree with the @derberg's idea here and we can look forward to make this implementation soon in the website.

[quetzalliwrites]

Yes, versioning and specifying a unique URL for the old v2 docs is the best practice.

[jonaslagoni]

Can one of you create the branch next-major-spec so we can start applying changes to the website? 🙂

[quetzalliwrites]

Wait, I am missing some context here 😅 .. why do you need us to create a branch? Why can't you do it yourself? @jonaslagoni I feel like there is a secret I don't know about hehe 🙃

[jonaslagoni]

It's one way we can collaborate on spec 3.0 changes to the website and slowly progress the change, we discussed it a bit in the last meeting.

The best way forward we saw was to:

1. Create the branch from current state of the website
2. I would go through all the related docs we had and filter out anything that is spec 2.0 specific and would need an update. Write the docs down that is filtered out so we can use it for [📑 Docs]: Create docs for spec 3.0 release  #1433
3. Create a PR with those changes targeting this branch
4. We can now start applying all relevant changes we need to do to the website and having them merged
5. Re-target chore: add migration guide for 3.0 #660 to this branch (then I can finish this ASAP, have it reviewed, and merged)
6. Re-target chore(blog): add release notes for 3.0 #659 to this branch (then I can finish this ASAP, have it reviewed, and merged)

This enables us to merge all website 3.0 changes progressively without waiting for the specification to release, cause it's still unknown when that will happen. So whenever the spec is finally released, whatever documentation we have for spec 3.0 can be released by just merging next-major-spec into master 🙂 This is the same approach we use for all other tooling, so I don't see why it shouldn't work for the website 😄

At least that's the idea 😄

[quetzalliwrites]

Yes, using a feature branch called next-major-spec and the process you described definitely makes sense to me. 👍

But I'm still confused about why you needed me or Lukasz specifically to create that branch? 😂 😅 Wouldn't it make more sense for you to create the branch if you are the one making changes? (please excuse me if I am still missing something obvious!)

@jonaslagoni

[jonaslagoni]

But I'm still confused about why you needed me or Lukasz specifically to create that branch? 😂 😅 Wouldn't it make more sense for you to create the branch if you are the one making changes? (please excuse me if I am still missing something obvious!)

I can only create a branch in my fork, which is by no means optimal for a feature branch. I would love to do it myself, however I am not a codeowner in the website 😄

It is much better to have the branch created here cause it's easier for everyone to access.

[jonaslagoni]

Let me know if that made sense @alequetzalli 🙂

[quetzalliwrites]

Ooooooh! I haven't created a feature branch yet and was unfamiliar with the process, so that was my confusion.

Yes, I think I finally understood you now. I will research how feature branches work and create one next week. I may ask Lucasz if I get stuck.😂🤪

[jonaslagoni]

@alequetzalli it is very simple (takes 10 seconds), if you go to https://github.com/asyncapi/website/branches

You can create the branch next-major-spec using master as the base branch - and that's it 😄

[quetzalliwrites]

Is this all good? 😄

https://github.com/asyncapi/website/branches

[jonaslagoni]

@alequetzalli yep, perfect 👌

[derberg]

just leaving a note for future. Let's make sure this will not be needed, but might be that we will later on in the process rename next-major-spec to v2 and persist it as a long living branch

as opposite to initial assumption: We will then deploy the latest commit before the merge on a sub-domain as frozen resources (never changes)

I know we do not want to invest long term in old docs, but this repo is not only docs but also server configuration, redirects, and other stuff that we might need to adjust later

---

minimum is to add a v2 tag at least, that we can use to create a branch if needed

[derberg]

well, it doesn't make sense what I wrote ☝🏼 just forget it

in general, for context https://youtu.be/dRu9itGfJ1E?t=668

additional stuff that needs to be done NOW:

• create v2 branch out of master
• adjust Algolia search config
• add robot.txt to back off crowlers. Block entire website by default, otherwise people will be confused that in search they get results from different versions. When I did research about Kubernetes and previous releases, this was the case - confusion in the community that search engines show old stuff.
• as a response to ☝🏼 we can have a version switcher on v3 website (docs view only) and in specification document even a dedicated panel that will refer to v2 page
  
• add panel to all pages that says where latest docs are. Example from Kubernetes 👇🏼
  
• hide all the navigation items except for Docs
  
• netlify setup to get v2.asyncapi.com in place

additional stuff that needs to be done BEFORE RELEASE:

• make sure v2 reflects latest master before merge

cc @jonaslagoni @alequetzalli

[quetzalliwrites]

I think I got it, but I will definitely have some questions in my 1:1 to make sure I don't mess up the new plans for the next-major-spec branch. 😅

Question: Why does your latest comment say "create v2 branch out of master" but the previous one says we will rename next-major-spec to v2? Which one of those do you actually wanna do? 😄

[derberg]

please look at my first sentence: well, it doesn't make sense what I wrote ☝🏼 just forget it 😄

in short: but the previous one says we will rename next-major-spec to v2 -> what I wrote, that it is needed, is a complete rubbish 😆

[quetzalliwrites]

ah! NOW I follow you better 😂

So we are going to create a new feature branch called v2. Yes? 😅

p.s. everything else you mention looked correct to me

[derberg]

yes, v2 that will stay there forever and will be hosting old website. And it will be modified as I suggested above

[derberg]

https://v2.asyncapi.com/ is here 🥳

[derberg]

done