Migration: improve the migration guide

[louismaximepiton]

Prerequisites

• [X] I have searched for duplicate or closed feature requests
• [X] I have read the contributing guidelines

Proposal

Improve as much as possible the documentation for migration. Feel free to add comments below or edit this comment.

Solutions

Here are some proposal I could see on other sites:

• An external migrator project such as angular. IMO, it would be the greatest but the toughest way to do it, BUT we have an open-source example with the link. Furthermore, I'm not sure that this model could be applied on our framework.
• A separated guide for each minor and major versions (this is the one I've seen the most, symfony, strapi, ...). Could be a quick win solution but might be combined with some other presented solutions.
• A refactoring with more meta titles such as tailwind. Could be a quick win solution but might be combined with some other presented solutions.
• An external redirection to a Markdown file (such as release note), but we'll loose many information IMO. (example)
• No guide (Such as many frameworks that I will silence the names).

Content

Thoughts about the content that could be contained inside the migration guide:

• Meta doc/sass/js changes (for exemple the rebranding, design tokens, etc..)
• Deprecated classes/variables/mixins/javascript/(markup)/
• Breaking and non-breaking changes in classes/variables/mixins/javascript/markup grouped by categories
• Changes in dependencies (like swiperjs in v4)
• New functionalities in the framework
• The bugs fixed
• Browser support

Meta info on migration guide

Migration guide should:

• Be in each version? (e.g. migration guide between v4 and v5 should be in both 4.x doc and 5.x (or even 4.6.2 and 5.0.0?))
• Maybe show the differences between the before and after markup? with ```diff ```
• Be more user friendly with for example a step by step process to follow
• Maybe a toast to alert that a new version is available if the new version has less than one or two weeks? (might be painful to change actually)
• Mix Boosted and Bootstrap changes to avoid the final user to change between 2 guides
• Display each part inside a collapse to make it more readable?
• Have the same structure between versions

Motivation and context

Folks are migrating to v5 and we have some feedbacks from users.

[MewenLeHo]

Following Change of syntax in migration guide #1782 and its related pull request , we found some inconsistencies in miggtaion guide syntax.

Remaining topics:

• [ ] should we change the syntax of the v5.1.0 part?
• [ ] should we change the syntax to start using h2, h3 and h4?

Things to keep in mind:

• Too many titles levels will make the table of content gigantic.
• Not really easy to deal with accessibility using markdown.