I think the way most people will want to proceed is:

1. Switch to PEP 793 module initialization (https://peps.python.org/pep-0793/). This will hopefully be a fairly trivial change for most people.
2. Switch to using opaque objects and accessing all their type data through PyObject_GetTypeData. This will be a painful change for most people (and especially if they're starting from static types).
3. Follow the general free-threading C API advice in https://docs.python.org/3/howto/free-threading-extensions.html#container-thread-safety (e.g. avoid borrowed reference, use critical sections once they become available). My personal opinion is that it isn't worth duplicating the advice.
4. Decide if they want to mark their extension as thread-safe.

But steps 1 and 2 are the main ones and are almost not covered here.

Based on WIP PR: #148013

I don't understand why we are having this PR when the reference documentation is not merged. Can we revisit this later? I would have expected the PEP's author to write this.

I left it as a draft because I do not think it is time for it to be reviewed. Please wait for the PEP author first.

Please don't repeat text from free-threading HOWTO. This document should be about migrating from that to the stable ABI; anything that's relevant to free-threading in general should be explained there (and possibly linked from the new document).

Also don't repeat information from the reference docs. A migration guide should link to the docs, and perhaps point out how/why the new thing is different.

And please see here on how-to guides in general: https://diataxis.fr/how-to-guides/

Documentation build overview

📚 cpython-previews | 🛠️ Build #32725685 | 📁 Comparing 3b401db against main (be9c7cb)

  🔍 Preview build  

Thank you @clin1234. I'll take it from here.

Thank you @clin1234. I'll take it from here.

Any other major PRs as part of implementing PEP 803 that should be mentioned in the Migration Guide?

Continued in #150580.

Any other major PRs as part of implementing PEP 803 that should be mentioned in the Migration Guide?

Mentions should go in Release notes; a guide should rather be full of practical advice.
All the PRs should be attached to #146636 though.