From 45dbaa7e26184ce5fc4a1eaf8050d1fe4305b51f Mon Sep 17 00:00:00 2001 From: Dr Maxim Orlovsky Date: Mon, 10 Jan 2022 12:15:13 +0100 Subject: [PATCH] Contributing: remove derivation section --- CONTRIBUTING.md | 64 ------------------------------------------------- 1 file changed, 64 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d51dcb0..9c38ea51 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,6 @@ changes to this document in a pull request. * [Repository maintainers](#repository-maintainers) - [Coding conventions](#coding-conventions) * [Formatting](#formatting) - * [Derivation](#derivation) * [MSRV](#msrv) * [Naming conventions](#naming-conventions) * [Unsafe code](#unsafe-code) @@ -186,69 +185,6 @@ and [how it is planned to coordinate it with crate refactoring](https://github.c For the new code it is recommended to follow style of the existing codebase and avoid any end-line space characters. -### Derivation - -Derivations applied to a data structures should be standardized: - -1. All non-error types should opportunistically derive, where it is possible, - the following traits: - - `Copy` (except iterators) - - `Clone` - - `PartialEq` and `Eq` - - `PartialOrd` and `Ord` - - `Hash` - - `Debug` - - By "where possible" we mean that by default a code line - ```rust - #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)] - ``` - must be placed before each struct, and then those of these traits, which - can't be auto-derived because of the member field restrictions should be - removed. - -2. `Eq`, `PartialEq`, `Ord`, `PartialOrd` derivation must be skipped/removed - from pt. 1 in the following situations: - - for types that don't have reflexive equality/ordering - - types which have a lexicographic ordering defined as a part of a standard - must provide a manual implementation - - types which may be more efficiently compared with bitcoin-specific rules - should provide a manual implementation - -3. `Debug` must not be derived on structs and enums which may contain secret - data, and a manual `Debug` implementation should be provided instead. - -4. `Default` derivation should be performed whenever there is a rationale to - have default constructor initializing "empty" data structure, i.e. this - empty structure has a real use in the business logic *outside of the scope - of testing or creating dumb data*. For instance, if the structure consists - only of collection types which may be empty it should derive `Default` trait. - -5. **Error types** (both structs and enums) must implement `Display` and `Error` - traits manually, and should provide `Error::source` function if some of the - error cases contain other error type. - -6. `Display` should be implemented for all data types which may be presented to - the end user (not developers!), for instance in command line or as a part of - GUI. Here are some guidelines: - - Normally, `Display` implementation should not just repeat `Debug` and - structure the data in some visually-acceptable way. - - One should pay attention to the ability of providing alternative ways of - data formatting with `{:#}` formatting string option, detectable by - `std::fmt::Formatter::alternate()` function. Other important options to - look at are `align`, `fill`, `pad`, `precision` and `width`. - - When displaying the member fields it is important to consider the ability - to pass them display formatting options; thus, - `Display::fmt(&self.field, f)?;` is preferable over - `write!(f, "{}", self.field)?;` - -7. Serde serializers should be implemented for all data types which may persist - or may be presented in the UI or API as JSON/YAML and other kinds of data - representations (in fact, these are all data types). - -The discussion about trait derivation can be read at -[the tracking issue](https://github.com/rust-bitcoin/rust-bitcoin/issues/555). - ### MSRV The Minimal Supported Rust Version (MSRV) is 1.29; it is enforced by our CI.