policy: update docs on ordering derives
What the developer wrote
Authored by Nick Johnson
policy: update docs on ordering derives
`rust-ordering` is no longer recommended and was removed from the
workspace in #4065 (38c8c9).
There are types like `NetworkKind` which derive order and it is used
downstream in other workspace packages to also derive order (e.g. Xpub).
I believe this derive actually caused issues before in v0.32.4,
discussed in issue #4116. But it probably low risk going forward since
the enum is exhaustive and I don't think someone would change the
variant order just for fun.
This more general policy is discussed in #3865.
What changed, and why it matters
This commit only updates project documentation (docs/policy.md). It removes a recommendation to use a third-party 'ordered' crate and instead cautions developers about deriving standard Rust ordering traits on enums because variant order becomes part of the public API. There is no code change and no security fix or vulnerability introduced.
No security action required. Treat as a normal documentation/policy update.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff modifies a single documentation file, docs/policy.md. It replaces guidance recommending the ‘ordered’ crate with guidance warning that deriving PartialOrd/Ord on enums bakes variant order into the public API and can break compatibility if variants are inserted in the middle. No Rust source code, build scripts, tests, or dependencies are changed. The commit message references prior issues (#4065, #4116, #3865) but these are not supplied as verified references.
Changed components
docs/policy.mdInspect captured patch +4 / −3
diff --git a/docs/policy.md b/docs/policy.md
index 86c66606..fd8968d7 100644
--- a/docs/policy.md
+++ b/docs/policy.md
@@ -332,14 +332,15 @@ enum Foo {
```
For types that should not form a total or partial order, or that technically do but it does not
-make sense to compare them, we use the `Ordered` trait from the
-[`ordered`](https://crates.io/crates/ordered) crate. See `absolute::LockTime` for an example.
+make sense to compare them semantically, consider carefully before deriving `PartialOrd` or `Ord`.
+While deterministic sorting is useful for use with collections (e.g. `BTreeMap`), it bakes the
+enum variant order into the public API. Adding enum variants in the middle changes discriminants
+and breaks compatibility.
For error types you likely want to use `#[derive(Debug, Clone, PartialEq, Eq)]`.
See [Errors](#errors) section.
-
## Attributes
- `#[track_caller]`: Used on functions that panic on invalid arguments
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.