mab122
/
radicle-heartwood-lfs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CONTRIBUTING: document the use of the terms safe and unsafe

This commit is contained in:
Fintan Halpenny 2026-01-14 14:53:04 +00:00
parent 70c2f89bdf
commit 01df41bf01
1 changed files with 21 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
CONTRIBUTING.md
View File

@ -118,6 +118,27 @@ However, there are some instances where they are acceptable:
3. The presence of `Option::None` or `Result::Err` is truly an unexpected scenario
and you intend the program to panic.
#### Use of the terms "safe" and "safety"
As we are programming in Rust, the terms safe and unsafe are narrowly defined to
refer to the safety in the sense that is common to the Rust programming community,
i.e. "Safe Rust" and "Unsafe Rust", as mentioned in [The Rustonomicon].
With this in mind, we only accept the use of "safe" about code if it is related
to implementing something within the realm of Unsafe Rust, as well as upholding
guarantees demanded by Safe Rust. The comment must describe why the use of
Unsafe Rust is in fact safe (i.e. which invariants are considered), and under
which conditions.
We will not accept the use of "safe" to describe conditions under which code
will not panic, i.e. why it would be panic-free to use `unreachable!`, `unwrap`,
or `expect`. As we differentiate between "panic-free Rust" and Safe Rust.
We will, however, still recommend that those uses are documented – generally
using a `# Panics` header followed by an explanatory paragraph in a documenting
comment.
[The Rustonomicon]: https://doc.rust-lang.org/nomicon/meet-safe-and-unsafe.html
#### Module imports
Modules are declared at the top of the file, before the imports. Public modules