Added migration page overview

[kwennB]

What kind of change does this PR introduce?

Documentation

Issue Number:

• Closes #897
• Related to #791

This is the overview page for Migration, which is part of the effort to create an easy transition between dialect upgrades.

Does this PR introduce a breaking change?

No

[github-actions[bot]]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
website	✅ Ready (View Log)	Visit Preview	9bbb1c2481deb260b933337ebb53b3af1c1f5bc0

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 100.00%. Comparing base (5c0ef1b) to head (9bbb1c2). Report is 210 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1061   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10        10           
  Lines          373       396   +23     
  Branches        94       106   +12     
=========================================
+ Hits           373       396   +23     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jviotti]

@Era-cell, assuming you still remember a lot of it, if you have some time to spare, your review would definitely be appreciated! 🙏🏻

[suprith-hub]

@jviotti @kwennB for some keywords like maximumCanEqual -> exclusiveMaximum, optional -> required, although there is no semantic change there is syntactic change, should this change be mentioned

[kwennB]

I see you chose to remove the (legacy) keyword entries. That's a perfectly fine choice, but if you remove them, it doesn't make sense to keep referencing them in the "Changed" column. Without the (legacy) keyword entries, "Replaced by"/"Replaced" doesn't make sense.

I think it would make sense to use the draft identifier of the release where the change was introduced similar to how we are using the "Removed" column. Depending on how much information you want to put in that column, you could also include a short sentence describing the change or a link to a resource describing the change in detail.

Are you suggesting removing the entire 'Changed' column or to put dashes in places that carry 'Replace, or Replaced by'.

[jdesrosiers]

Are you suggesting removing the entire 'Changed' column or to put dashes in places that carry 'Replace, or Replaced by'.

No, not at all. The only entries I was suggesting you change are the ones that reference a (legacy) keyword such as Replaced $ref (legacy). You can't say it replaced $ref (legacy) because you removed the listing for $ref (legacy). Here's an example of what my suggestion was. It uses the draft identifier for when the keyword changed in the "Changed" column.

| All Keywords | Specification | Draft introduction | Removed | Changed                                                    |
| ------------ | ------------- | ------------------ | ------- | ---------------------------------------------------------- |
| `$ref`       | Core          | 03                 | No      | 2019-09 (???)                                              |
| `type`       | Validation    | 01                 | No      | 03 (???)                                                   |
| `format`     | Validation    | 01                 | No      | 04 (???), 06 (???), 07 (???), 2019-09 (???), 2020-12 (???) |

This communicates the draft the keyword was introduced, the draft(s) the keyword changed, and the draft the keyword was removed (if it was removed). (???) is a placeholder if you want to put a short description of what changed. If not, you can just list the draft identifiers.

[github-actions[bot]]

Hi @kwennB! Thanks a lot for your contribution!

I noticed that the following required information is missing or incomplete: issue reference

Please update the PR description to include this information. You can find placeholders in the PR template for these items.

Thanks a lot!

[github-actions[bot]]

Hi @kwennB! Thanks a lot for your contribution!

I noticed that the following required information is missing or incomplete: issue reference

Please update the PR description to include this information. You can find placeholders in the PR template for these items.

Thanks a lot!

[github-actions[bot]]

Hi @kwennB! Thanks a lot for your contribution!

I noticed that the following required information is missing or incomplete: issue reference

Please update the PR description to include this information. You can find placeholders in the PR template for these items.

Thanks a lot!

[kwennB]

I don't think the migration notes for each release are working out. They still need a lot of work to fix errors and include enough detail to be useful. They're nowhere near ready to replace the release notes.

I suggest narrowing the scope of this PR. Let's just do the overview for now with links to the existing release notes. Then we can figure out what to do for the individual migration guides separately.

Hello @jdesrosiers do you think the current overview is not accurate as well?

I do agree that the migration for specific pages can be better on review now. But if we want to de-scope this to the overview only, are we not there?

[jdesrosiers]

I think the overview is mostly fine except you still haven't addressed https://github.com/json-schema-org/website/pull/1061#pullrequestreview-3056550828 ...

please note that the following keywords are missing from the main overview: minimum, maximum, minLength, and maxLength.