<!-- Copyright 2023 The Fuchsia AuthorsLicensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MITlicense <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.This file may not be copied, modified, or distributed except according tothose terms. --># Zerocopy's Policies## SoundnessZerocopy is expressly designed for use in security-critical contexts. It is usedin hardware security firmware, cryptographic implementations, hypervisors, andmore. We understand that software in these contexts has a very high bar forcorrectness, and we take our responsibility to meet that bar very seriously.This section describes policies which are designed to ensure the correctness andsoundness of our code and prevent regressions.### Forwards-compatibilityRust does not currently have a formal memory model. As such, while Rust providesguarantees about the semantics of some operations, the semantics of manyoperations is up in the air and subject to change.Zerocopy strives to ensure that our code - and code emitted by our customderives - is sound under any version of Rust as early as our MSRV, and willcontinue to be sound under any future version of Rust. The policies in thissection are designed to help ensure that we live up to this goal.### Safety commentsEach non-test `unsafe` block must be annotated with a "safety comment" whichprovides a rationale for its soundness. In order to ensure that our soundness isforwards-compatible, safety comments must satisfy the following criteria:- Safety comments must constitute a (possibly informal) proof that all of Rust's  soundness rules are upheld.- Safety comments must only rely for their correctness on statements which  appear in the stable versions of the [Rust Reference] or standard library  documentation (ie, the docs for [core], [alloc], and [std]); arguments which  rely on text from the beta or nightly versions of these documents are not  considered complete.- All statements from the Reference or standard library documentation which are  relied upon for soundness must be quoted in the safety comment. This ensures  that there is no ambiguity as to what aspect of the text is being cited. This  is especially important in cases where the text of these documents changes in  the future. Such changes are of course required to be backwards-compatible,  but may change the manner in which a particular guarantee is explained.We use the [`clippy::undocumented_unsafe_blocks`] lint to ensure that `unsafe`blocks cannot be added without a safety comment. Note that there are a fewoutstanding uncommented `unsafe` blocks which are tracked in [#429]. Our goal isto reach 100% safety comment coverage and not regress once we've reached it.[Rust Reference]: https://doc.rust-lang.org/reference/[core]: https://doc.rust-lang.org/stable/core/[alloc]: https://doc.rust-lang.org/stable/alloc/[std]: https://doc.rust-lang.org/stable/std/[`clippy::undocumented_unsafe_blocks`]: https://rust-lang.github.io/rust-clippy/master/index.html#/undocumented_unsafe_blocks[#429]: https://github.com/google/zerocopy/issues/429#### Exceptions to our safety comment policyIn rare circumstances, the soundness of an `unsafe` block may depend uponsemantics which are widely agreed upon but not formally guaranteed. In order toavoid slowing down zerocopy's development to an unreasonable degree, a safetycomment may violate our safety comment policy so long as all of the followinghold:- The safety comment's correctness may rely on semantics which are not  guaranteed in official Rust documentation *so long as* a member of the Rust  team has articulated in an official communication (e.g. a comment on a Rust  GitHub repo) that Rust intends to guarantee particular semantics.- There exists an active effort to formalize the guarantee in Rust's official  documentation.### Target architecture supportZerocopy bases its soundness on guarantees made about the semantics of Rustwhich appear in the Rust Reference or standard library documentation; zerocopyis sound so long as these guarantees hold. There are known cases in which theseguarantees do not hold on certain target architectures (see[rust-lang/unsafe-code-guidelines#461]); on such target architectures, zerocopymay be unsound. We consider it outside of zerocopy's scope to reason about thesecases. Zerocopy makes no effort maintain soundness in cases where Rust'sdocumented guarantees do not hold.[rust-lang/unsafe-code-guidelines#461]: https://github.com/rust-lang/unsafe-code-guidelines/issues/461## MSRV<!-- Our policy used to be simply that MSRV was a breaking change in allcircumstances. This implicitly relied on syn having the same MSRV policy, whichit does not. See #1085 and #1088. -->Without the `derive` feature enabled, zerocopy's minimum supported Rust version(MSRV) is encoded the `package.rust-version` field in its `Cargo.toml` file. Forzerocopy, we consider an increase in MSRV to be a semver-breaking change, andwill only increase our MSRV during semver-breaking version changes (e.g., 0.1 ->0.2, 1.0 -> 2.0, etc).For zerocopy with the `derive` feature enabled, and for the zerocopy-derivecrate, we inherit the maximum MSRV any of our dependencies. As of this writing(2024-10-03), at least one dependency (syn) does *not* consider MSRV increasesto be semver-breaking changes. Thus, using the `derive` feature may result inthe effective MSRV increasing within a semver version train.## YankingWhenever a bug or regression is identified, we will yank any affected versionswhich are part of the current version train. For example, if the most recentversion is 0.10.20 and a bug is uncovered, we will release a fix in 0.10.21 andyank all 0.10.X versions which are affected. We *may* also yank versions inprevious version trains on a case-by-case basis, but we don't guarantee it.For information about a particular yanked or un-yanked version, see our [yanklog][yank-log].[yank-log]: https://github.com/google/zerocopy/blob/main/CHANGELOG.md#yanks-and-regressions