docs: add v3 migration guide (#2008)

Co-authored-by: akshatnema <akshatnema.school@gmail.com>%0ACo-authored-by: Alejandra Quetzalli <alejandra.olvera.novack@gmail.com>

components/data/buckets.js

@@ -4,6 +4,7 @@ import IconUseCases from '../icons/UseCases'
 import IconGuide from '../icons/Guide'
 import IconSpec from '../icons/Spec'
 import IconUsers from '../icons/Users'
+import IconMigration from '../icons/Migration'
 
 export const buckets = [
   {
@@ -51,7 +52,16 @@ export const buckets = [
     borderClassName: 'border-yellow-200',
     Icon: IconSpec,
   },
-    {
+  {
+    name: 'migration',
+    title: 'Migration',
+    description: 'Our migration guides on how to upgrade to newer AsyncAPI versions.',
+    link: '/docs/migration',
+    className: 'bg-blue-400',
+    borderClassName: 'border-blue-400',
+    Icon: IconMigration,
+  },
+  {
     name: 'community',
     title: 'Community',
     description: 'Our Community section documents the community guidelines and resources.',
@@ -61,7 +71,7 @@ export const buckets = [
     Icon: IconUsers,
   },
 ].map(bucket => {
-  // we need such a mapping for some parts of website, e.g navigation blocks use the `icon` property, not `Icon` etc. 
+  // we need such a mapping for some parts of website, e.g navigation blocks use the `icon` property, not `Icon` etc.
   return {
     ...bucket,
     href: bucket.link,

components/icons/Migration.js

@@ -0,0 +1,15 @@
+export default function IconUsers({ ...rest }) {
+  // <!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
+  return (
+    <svg
+    width="800px"
+    height="800px"
+    viewBox="0 0 1024 1024"
+    version="1.1"
+    xmlns="http://www.w3.org/2000/svg"
+    {...rest}
+    >
+      <path d="M550.208 960H209.28A81.792 81.792 0 0 1 128 877.76V146.24A81.92 81.92 0 0 1 209.344 64h613.632a81.92 81.92 0 0 1 81.28 82.432v405.76a29.824 29.824 0 1 1-59.584 0V146.56a22.272 22.272 0 0 0-21.76-22.656H209.408a22.08 22.08 0 0 0-21.696 22.528v731.52a21.76 21.76 0 0 0 21.44 22.464h341.056a29.824 29.824 0 0 1 0.064 59.584z m196.352-600.96H285.824a29.824 29.824 0 1 1 0-59.712h460.8a29.824 29.824 0 1 1 0 59.712z m-204.8 156.8H285.824a29.824 29.824 0 1 1 0-59.712h255.936a29.824 29.824 0 1 1 0 59.648z m179.2 391.936c-101.12 0-183.424-83.84-183.424-186.624a29.824 29.824 0 1 1 59.712 0c0 70.016 55.552 126.976 123.584 126.976 17.408 0 34.24-3.712 50.048-10.88a29.888 29.888 0 0 1 24.768 54.336c-23.552 10.688-48.64 16.192-74.688 16.192z m153.6-156.8a29.824 29.824 0 0 1-29.824-29.824c0-70.016-55.552-126.976-123.648-126.976-16.32 0-32.384 3.2-47.36 9.6a29.888 29.888 0 0 1-23.424-54.912 180.224 180.224 0 0 1 70.784-14.336c101.12 0 183.424 83.84 183.424 186.624a30.016 30.016 0 0 1-29.952 29.824z m-204.8-104.576h-51.264a29.76 29.76 0 0 1-25.28-14.08 30.144 30.144 0 0 1-1.536-28.928l25.6-52.352a29.696 29.696 0 0 1 53.632 0l25.6 52.352a29.696 29.696 0 0 1-1.472 28.928 29.504 29.504 0 0 1-25.28 14.08z m127.552 269.568h-1.024a29.696 29.696 0 0 1-24.896-14.848l-25.6-44.288a29.888 29.888 0 0 1 23.808-44.672l58.048-4.032c11.392-0.704 22.144 5.12 27.904 14.848a30.016 30.016 0 0 1-1.024 31.616l-32.448 48.256a29.824 29.824 0 0 1-24.768 13.12z" fill="#000000" />
+    </svg>
+  );
+}

components/icons/Users.js

@@ -1,14 +1,14 @@
 export default function IconUsers({ ...rest }) {
   return (
-    <svg 
-      xmlns="http://www.w3.org/2000/svg" 
-      width="24" 
-      height="24" 
-      viewBox="0 0 24 24" 
-      fill="none" 
-      stroke="currentColor" 
-      strokeWidth="1.3" 
-      strokeLinecap="round" 
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.3"
+      strokeLinecap="round"
       strokeLinejoin="round"
       {...rest}
     >

components/navigation/learningItems.js

@@ -4,12 +4,14 @@ import IconPlant from '../icons/Plant'
 import IconGuide from '../icons/Guide'
 import IconPaper from '../icons/Paper'
 import IconUsers from '../icons/Users'
+import IconMigration from '../icons/Migration'
 
 export default [
   { href: '/docs/concepts', icon: IconRocket, className: 'bg-secondary-200', title: 'Concepts', description: 'Our Concepts section defines the concepts of AsyncAPI features and capabilities.' },
   { href: '/docs/tutorials', icon: IconGradCap, className: 'bg-pink-100', title: 'Tutorials', description: 'Our Tutorials section teaches beginner processes with AsyncAPI, guiding you from Point A to Point B.' },
   { href: '/docs/tools', icon: IconPlant, className: 'bg-green-200', title: 'Tools', description: 'Our Tools section documents the AsyncAPI tools ecosystem.' },
   { href: '/docs/guides', icon: IconGuide, className: 'bg-primary-200', title: 'Guides', description: `Our Guides section teaches AsyncAPI's capabilities at a high level.` },
   { href: '/docs/reference', icon: IconPaper, className: 'bg-yellow-200', title: 'Reference', description: `Our Reference section documents the AsyncAPI specification.` },
+  { href: '/docs/migration', icon: IconMigration, className: 'bg-blue-400', title: 'Migrations', description: `Our migration guides on how to upgrade to newer AsyncAPI versions.` },
   { href: '/docs/community', icon: IconUsers, className: 'bg-red-200', title: 'Community', description: `Our Community section documents the community guidelines and resources.` },
 ]

cypress/test/Asyncapi3Comparison.cy.js

@@ -0,0 +1,40 @@
+import { mount } from '@cypress/react'
+import {Asyncapi3Comparison, Asyncapi3ChannelComparison, Asyncapi3IdAndAddressComparison, Asyncapi3MetaComparison, Asyncapi3OperationComparison, Asyncapi3SchemaFormatComparison, Asyncapi3ServerComparison} from '../../components/Asyncapi3Comparison'
+
+describe('Asyncapi3Comparison.cy', () => {
+  describe('Asyncapi3Comparison', () => {
+    it('renders without errors', () => {
+      mount(<Asyncapi3Comparison />);
+    });
+  });
+  describe('Asyncapi3ChannelComparison', () => {
+    it('renders without errors', () => {
+      mount(<Asyncapi3ChannelComparison />);
+    });
+  });
+  describe('Asyncapi3IdAndAddressComparison', () => {
+    it('renders without errors', () => {
+      mount(<Asyncapi3IdAndAddressComparison />);
+    });
+  });
+  describe('Asyncapi3MetaComparison', () => {
+    it('renders without errors', () => {
+      mount(<Asyncapi3MetaComparison />);
+    });
+  });
+  describe('Asyncapi3OperationComparison', () => {
+    it('renders without errors', () => {
+      mount(<Asyncapi3OperationComparison />);
+    });
+  });
+  describe('Asyncapi3SchemaFormatComparison', () => {
+    it('renders without errors', () => {
+      mount(<Asyncapi3SchemaFormatComparison />);
+    });
+  });
+  describe('Asyncapi3ServerComparison', () => {
+    it('renders without errors', () => {
+      mount(<Asyncapi3ServerComparison />);
+    });
+  });
+});

pages/docs/community/_section.md

@@ -1,4 +1,4 @@
 ---
 title: 'Community'
-weight: 6
----
+weight: 7
+---

pages/docs/migration/_section.md

@@ -0,0 +1,4 @@
+---
+title: Migrations
+weight: 6
+---

pages/docs/migration/index.md

@@ -0,0 +1,15 @@
+---
+title: "Overview"
+---
+Migration to a new major version is always difficult, and AsyncAPI is no exception, but we want to provide as smooth a transition as possible.
+
+If you are just looking to update your AsyncAPI document, then we suggest you use the [AsyncAPI converter](https://github.com/asyncapi/converter-js). You can do this directly in the CLI with:
+
+```bash
+asyncapi convert asyncapi.json --output=new_asyncapi.json --target-version=x.x.x
+```
+
+For a detailed read-through about all the changes (non-breaking as well), please do [read the release notes](https://www.asyncapi.com/blog?tags=Release+Notes) for the desired version before hand, as it will give you some more context about the changes.
+
+Here are all the migration guides:
+- [Migrating to v3](/docs/migration/migrating-to-v3)