Debian Codegraph @

.cargo/vendor/zerocopy/POLICIES.md

raw
1 <!-- Copyright 2023 The Fuchsia Authors
2
3 Licensed 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
5 license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
6 This file may not be copied, modified, or distributed except according to
7 those terms. -->
8
9 # Zerocopy's Policies
10
11 ## Soundness
12
13 Zerocopy is expressly designed for use in security-critical contexts. It is used
14 in hardware security firmware, cryptographic implementations, hypervisors, and
15 more. We understand that software in these contexts has a very high bar for
16 correctness, and we take our responsibility to meet that bar very seriously.
17
18 This section describes policies which are designed to ensure the correctness and
19 soundness of our code and prevent regressions.
20
21 ### Forwards-compatibility
22
23 Rust does not currently have a formal memory model. As such, while Rust provides
24 guarantees about the semantics of some operations, the semantics of many
25 operations is up in the air and subject to change.
26
27 Zerocopy strives to ensure that our code - and code emitted by our custom
28 derives - is sound under any version of Rust as early as our MSRV, and will
29 continue to be sound under any future version of Rust. The policies in this
30 section are designed to help ensure that we live up to this goal.
31
32 ### Safety comments
33
34 Each non-test `unsafe` block must be annotated with a "safety comment" which
35 provides a rationale for its soundness. In order to ensure that our soundness is
36 forwards-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
51 We use the [`clippy::undocumented_unsafe_blocks`] lint to ensure that `unsafe`
52 blocks cannot be added without a safety comment. Note that there are a few
53 outstanding uncommented `unsafe` blocks which are tracked in [#429]. Our goal is
54 to 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
65 In rare circumstances, the soundness of an `unsafe` block may depend upon
66 semantics which are widely agreed upon but not formally guaranteed. In order to
67 avoid slowing down zerocopy's development to an unreasonable degree, a safety
68 comment may violate our safety comment policy so long as all of the following
69 hold:
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
79 Zerocopy bases its soundness on guarantees made about the semantics of Rust
80 which appear in the Rust Reference or standard library documentation; zerocopy
81 is sound so long as these guarantees hold. There are known cases in which these
82 guarantees do not hold on certain target architectures (see
83 [rust-lang/unsafe-code-guidelines#461]); on such target architectures, zerocopy
84 may be unsound. We consider it outside of zerocopy's scope to reason about these
85 cases. Zerocopy makes no effort maintain soundness in cases where Rust's
86 documented 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
93 circumstances. This implicitly relied on syn having the same MSRV policy, which
94 it does not. See #1085 and #1088. -->
95
96 Without 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
98 zerocopy, we consider an increase in MSRV to be a semver-breaking change, and
99 will only increase our MSRV during semver-breaking version changes (e.g., 0.1 ->
100 0.2, 1.0 -> 2.0, etc).
101
102 For zerocopy with the `derive` feature enabled, and for the zerocopy-derive
103 crate, we inherit the maximum MSRV any of our dependencies. As of this writing
104 (2024-10-03), at least one dependency (syn) does *not* consider MSRV increases
105 to be semver-breaking changes. Thus, using the `derive` feature may result in
106 the effective MSRV increasing within a semver version train.
107
108 ## Yanking
109
110 Whenever a bug or regression is identified, we will yank any affected versions
111 which are part of the current version train. For example, if the most recent
112 version is 0.10.20 and a bug is uncovered, we will release a fix in 0.10.21 and
113 yank all 0.10.X versions which are affected. We *may* also yank versions in
114 previous version trains on a case-by-case basis, but we don't guarantee it.
115
116 For information about a particular yanked or un-yanked version, see our [yank
117 log][yank-log].
118
119 [yank-log]: https://github.com/google/zerocopy/blob/main/CHANGELOG.md#yanks-and-regressions