static_mut_refs: Need edition migration guide documentation

[ehuss]

The change for static_mut_refs in the 2024 Edition needs to have documentation (here) for how a user can perform a manual migration.

This documentation should have a more complete explanation of why it is forbidden. Currently it just mentions use in multiple threads, but I don't think that is a complete description.

It also needs to explain to the user how to rewrite their code to make it work. My understanding is that someone can convert &STATIC to &*addr_of!(STATIC), which is equivalent, but still runs afoul of the exact same aliasing problems and undefined behavior, so I don't know if it makes sense to recommend that.

• Why is &*addr_of!(…) allowed?
• What situations are there where addr_of! is appropriate?
• If addr_of! isn't the correct route, what should a user do to update their code?
  • Do they have to switch to interior mutability? How? What other options are there?

See also discussion at #114447 and
https://rust-lang.zulipchat.com/#narrow/stream/213817-t-lang/topic/static_mut_refs

[traviscross]

cc @obeis @scottmcm @RalfJung @est31

[eggyal]

I opened rust-lang/edition-guide#299 as a step towards this.

[traviscross]

We talked about this in the edition meeting today. The page that we merged to the edition guide in rust-lang/edition-guide#299 is a good start, but we still want to see a bit more.

We're hoping for the guide to cover an example showing why this is unsound, and then show how the simple cases could be rewritten using raw pointers, and maybe show a more complicated case showing where using a custom type instead would make sense.

Looking in the recent crater results (#125384), it seems there are a lot of calls to libc here. Perhaps we could show an example of that and how these could be addressed with raw pointers.