Radish alpha
h
Radicle Heartwood Protocol & Stack
Radicle
Git (anonymous pull)
Log in to clone via SSH
CONTRIBUTING: document the use of the terms safe and unsafe
Fintan Halpenny committed 3 months ago
commit 186c9ca9255e9482ff15ae1a1e4416a4a5a47ab3
parent c1fddf078d1e0de1e271f35d784ed1ce81790e75
1 file changed +21 -0
modified CONTRIBUTING.md
@@ -100,6 +100,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