document zerocopy's relationship to Project Safe Transmute

Fixes #480

Author: jswrenn

README.md

@@ -107,6 +107,29 @@ memory model, and *any future memory model*. We ensure this by:
 [Miri]: https://github.com/rust-lang/miri
 [Kani]: https://github.com/model-checking/kani
 
+## Relationship to Project Safe Transmute
+
+[Project Safe Transmute] is an official initiative of the Rust Project to
+develop language-level support for safer transmutation. The Project consults
+with crates like zerocopy to identify aspects of safer transmutation that
+would benefit from compiler support, and has developed an [experimental,
+compiler-supported analysis][mcp-transmutability] of when a value of one
+type is soundly transmutable into another. Once this functionality is
+sufficiently mature, zerocopy intends to replace its internal
+transmutability analysis with the compiler-supported one. This change will
+likely be an implementation detail that is invisible to zerocopy's users.
+
+However, Project Safe Transmute will not replace the need for most of
+zerocopy's higher-level abstractions over transmutability. The experimental
+compiler analysis is a tool for checking the soundness of `unsafe` code—not
+a tool to avoid writing `unsafe` code altogether. For the foreseeable
+future, crates like zerocopy will still be required in order to provide
+higher-level abstractions on top of the building block provided by Project
+Safe Transmute.
+
+[Project Safe Transmute]: https://rust-lang.github.io/rfcs/2835-project-safe-transmute.html
+[mcp-transmutability]: https://github.com/rust-lang/compiler-team/issues/411
+
 ## Disclaimer
 
 Disclaimer: Zerocopy is not an officially supported Google product.

src/lib.rs

@@ -105,6 +105,29 @@
 //!
 //! [Miri]: https://github.com/rust-lang/miri
 //! [Kani]: https://github.com/model-checking/kani
+//! 
+//! # Relationship to Project Safe Transmute
+//! 
+//! [Project Safe Transmute] is an official initiative of the Rust Project to
+//! develop language-level support for safer transmutation. The Project consults
+//! with crates like zerocopy to identify aspects of safer transmutation that
+//! would benefit from compiler support, and has developed an [experimental,
+//! compiler-supported analysis][mcp-transmutability] of when a value of one
+//! type is soundly transmutable into another. Once this functionality is
+//! sufficiently mature, zerocopy intends to replace its internal
+//! transmutability analysis with the compiler-supported one. This change will
+//! likely be an implementation detail that is invisible to zerocopy's users.
+//! 
+//! However, Project Safe Transmute will not replace the need for most of
+//! zerocopy's higher-level abstractions over transmutability. The experimental
+//! compiler analysis is a tool for checking the soundness of `unsafe` code—not
+//! a tool to avoid writing `unsafe` code altogether. For the foreseeable
+//! future, crates like zerocopy will still be required in order to provide
+//! higher-level abstractions on top of the building block provided by Project
+//! Safe Transmute.
+//! 
+//! [Project Safe Transmute]: https://rust-lang.github.io/rfcs/2835-project-safe-transmute.html
+//! [mcp-transmutability]: https://github.com/rust-lang/compiler-team/issues/411
 
 // Sometimes we want to use lints which were added after our MSRV.
 // `unknown_lints` is `warn` by default and we deny warnings in CI, so without