[📝 Docs]: Create a Migration page for the Specification docs

[kwennB]

What Docs changes are you proposing?

Create a single Migration page dedicated to upgrading and history for the drafts. It is hard for implementers of the migrate between drafts and would be better helpful if it had;

• It is challenging to identify which keywords have changed between dialects.
• Some keywords have retained their names but evolved across Schema versions. However, documentation must explain when these keywords were introduced or why they changed.
• Some keywords have changed their behavior while maintaining their syntax across schemas, causing confusion among users and highlighting the need for clear communication.
• Implementers would benefit from more guidance on upgrading implementations with changing keywords.

To facilitate smoother migration between drafts, this issue aims to add the following changes:

• Creating a detailed changelog of keyword modifications between versions
• Providing historical timelines for keyword introductions and changes
• Highlighting behavioral changes, especially when syntax remains unchanged
• Developing a robust set of migration examples and best practices

This is also in the efforts to https://github.com/json-schema-org/website/issues/791.

Thank you @jviotti, for your help listing these issues.

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[gregsdennis]

@jviotti I'd be interested in promoting your projects here instead of rehashing all the work you've done for this site.

[jviotti]

Makes sense. Let's discuss @kwennB. Some of these things are easy to add to learnjsonschema.com (or are already there), but some I'm not sure. For example:

• Creating a detailed changelog of keyword modifications between versions
• Providing historical timelines for keyword introductions and changes

These 2 might be trivial to add to learnjsonschema.com. We have some of the data already as YAML content, so it might just be about some clever Hugo rendering.

• Highlighting behavioral changes, especially when syntax remains unchanged
• Developing a robust set of migration examples and best practices

For these ones there are migration pages on the official site that we tap into, as they are already there.

[github-actions[bot]]

Hello! :wave:

This issue has been automatically marked as stale due to inactivity :sleeping:

It will be closed in 180 days if no further activity occurs. To keep it active, please add a comment with more details.

There can be many reasons why a specific issue has no activity. The most probable cause is a lack of time, not a lack of interest.

Let us figure out together how to push this issue forward. Connect with us through our slack channel : https://json-schema.org/slack

Thank you for your patience :heart: