SDL3/MigrationGuide: Added.

[SDLWikiBot]

This edit was made by @Perry-chouteau.

Live page is here: https://wiki.libsdl.org/SDL3/MigrationGuide

If this user should be blocked from further edits, an admin should go to https://wiki.libsdl.org/Perry-chouteau/block
If this user should be trusted to make direct pushes to main, without a pull request, an admin should go to https://wiki.libsdl.org/Perry-chouteau/trust

[Perry-chouteau]

I edit some error on the website and it create a lot of pull_request sorry

[icculus]

No worries! One thing I want to do (but haven't started) is have additional edits add to the same pull request instead of generating a new one each time, but we understand the multiple-pull-request thing happens from time to time right now.

We are still deciding what to do about a migration guide, though. The changes from SDL 1.2 to SDL2 involved a lot more work on changing how the app should approach problems, whereas an SDL2 to SDL3 guide would be more about adjustments to APIs. I think you have the start of the right approach here: build your app, see if there's an error about SDL_x_renamed_to_SDL_y and work forward from there. Maybe the 2-to-3 migration guide should be about the techniques one should use to migrate instead of the specific technical details!

[icculus]

Since this discussion, we've talked a lot about what the migration guide should look like, and decided that (unlike 1.2 to 2.0, where there were a lot of philosophical changes in how the API operates), most of the 2.0 to 3.0 work is mechanical in nature.

So we ended up with just the technical, point-by-point documentation at https://wiki.libsdl.org/SDL3/README-migration, a coccinelle script that will do a lot of the basic transformations for you, and made some YouTube videos of real-world examples of putting both to use.

We also updated the 1.2-to-2.0 page from SDL2 for 1.2 developers that want to jump straight to 3.0:

https://wiki.libsdl.org/SDL3/SDL12MigrationGuide

So I think we're good here (but feedback on, and improvements to, those pages are always worth considering!).