1<!-- Copyright 2023 The Fuchsia Authors
2
3Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
4<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
5license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
6This file may not be copied, modified, or distributed except according to
7those terms. -->
8
9# Zerocopy's Policies
10
11## Soundness
12
13Zerocopy is expressly designed for use in security-critical contexts. It is used
14in hardware security firmware, cryptographic implementations, hypervisors, and
15more. We understand that software in these contexts has a very high bar for
16correctness, and we take our responsibility to meet that bar very seriously.
17
18This section describes policies which are designed to ensure the correctness and
19soundness of our code and prevent regressions.
20
21### Forwards-compatibility
22
23Rust does not currently have a formal memory model. As such, while Rust provides
24guarantees about the semantics of some operations, the semantics of many
25operations is up in the air and subject to change.
26
27Zerocopy strives to ensure that our code - and code emitted by our custom
28derives - is sound under any version of Rust as early as our MSRV, and will
29continue to be sound under any future version of Rust. The policies in this
30section are designed to help ensure that we live up to this goal.
31
32### Safety comments
33
34Each non-test `unsafe` block must be annotated with a "safety comment" which
35provides a rationale for its soundness. In order to ensure that our soundness is
36forwards-compatible, safety comments must satisfy the following criteria:
37- Safety comments must constitute a (possibly informal) proof that all of Rust's
38  soundness rules are upheld.
39- Safety comments must only rely for their correctness on statements which
40  appear in the stable versions of the [Rust Reference] or standard library
41  documentation (ie, the docs for [core], [alloc], and [std]); arguments which
42  rely on text from the beta or nightly versions of these documents are not
43  considered complete.
44- All statements from the Reference or standard library documentation which are
45  relied upon for soundness must be quoted in the safety comment. This ensures
46  that there is no ambiguity as to what aspect of the text is being cited. This
47  is especially important in cases where the text of these documents changes in
48  the future. Such changes are of course required to be backwards-compatible,
49  but may change the manner in which a particular guarantee is explained.
50
51We use the [`clippy::undocumented_unsafe_blocks`] lint to ensure that `unsafe`
52blocks cannot be added without a safety comment. Note that there are a few
53outstanding uncommented `unsafe` blocks which are tracked in [#429]. Our goal is
54to reach 100% safety comment coverage and not regress once we've reached it.
55
56[Rust Reference]: https://doc.rust-lang.org/reference/
57[core]: https://doc.rust-lang.org/stable/core/
58[alloc]: https://doc.rust-lang.org/stable/alloc/
59[std]: https://doc.rust-lang.org/stable/std/
60[`clippy::undocumented_unsafe_blocks`]: https://rust-lang.github.io/rust-clippy/master/index.html#/undocumented_unsafe_blocks
61[#429]: https://github.com/google/zerocopy/issues/429
62
63#### Exceptions to our safety comment policy
64
65In rare circumstances, the soundness of an `unsafe` block may depend upon
66semantics which are widely agreed upon but not formally guaranteed. In order to
67avoid slowing down zerocopy's development to an unreasonable degree, a safety
68comment may violate our safety comment policy so long as all of the following
69hold:
70- The safety comment's correctness may rely on semantics which are not
71  guaranteed in official Rust documentation *so long as* a member of the Rust
72  team has articulated in an official communication (e.g. a comment on a Rust
73  GitHub repo) that Rust intends to guarantee particular semantics.
74- There exists an active effort to formalize the guarantee in Rust's official
75  documentation.
76
77### Target architecture support
78
79Zerocopy bases its soundness on guarantees made about the semantics of Rust
80which appear in the Rust Reference or standard library documentation; zerocopy
81is sound so long as these guarantees hold. There are known cases in which these
82guarantees do not hold on certain target architectures (see
83[rust-lang/unsafe-code-guidelines#461]); on such target architectures, zerocopy
84may be unsound. We consider it outside of zerocopy's scope to reason about these
85cases. Zerocopy makes no effort maintain soundness in cases where Rust's
86documented guarantees do not hold.
87
88[rust-lang/unsafe-code-guidelines#461]: https://github.com/rust-lang/unsafe-code-guidelines/issues/461
89
90## MSRV
91
92<!-- Our policy used to be simply that MSRV was a breaking change in all
93circumstances. This implicitly relied on syn having the same MSRV policy, which
94it does not. See #1085 and #1088. -->
95
96Without the `derive` feature enabled, zerocopy's minimum supported Rust version
97(MSRV) is encoded the `package.rust-version` field in its `Cargo.toml` file. For
98zerocopy, we consider an increase in MSRV to be a semver-breaking change, and
99will only increase our MSRV during semver-breaking version changes (e.g., 0.1 ->
1000.2, 1.0 -> 2.0, etc).
101
102For zerocopy with the `derive` feature enabled, and for the zerocopy-derive
103crate, we inherit the MSRV of our sole external dependency, syn. As of this
104writing (2024-07-02), syn does *not* consider MSRV increases to be
105semver-breaking changes. Thus, using the `derive` feature may result in the
106effective MSRV increasing within a semver version train.
107
108## Yanking
109
110Whenever a bug or regression is identified, we will yank any affected versions
111which are part of the current version train. For example, if the most recent
112version is 0.10.20 and a bug is uncovered, we will release a fix in 0.10.21 and
113yank all 0.10.X versions which are affected. We *may* also yank versions in previous
114version trains on a case-by-case basis, but we don't guarantee it.
115