Contributing: remove derivation section

This commit is contained in:
Dr Maxim Orlovsky 2022-01-10 12:15:13 +01:00
parent 313ac7d4a8
commit 45dbaa7e26
1 changed files with 0 additions and 64 deletions

View File

@ -19,7 +19,6 @@ changes to this document in a pull request.
* [Repository maintainers](#repository-maintainers) * [Repository maintainers](#repository-maintainers)
- [Coding conventions](#coding-conventions) - [Coding conventions](#coding-conventions)
* [Formatting](#formatting) * [Formatting](#formatting)
* [Derivation](#derivation)
* [MSRV](#msrv) * [MSRV](#msrv)
* [Naming conventions](#naming-conventions) * [Naming conventions](#naming-conventions)
* [Unsafe code](#unsafe-code) * [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 For the new code it is recommended to follow style of the existing codebase and
avoid any end-line space characters. 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 ### MSRV
The Minimal Supported Rust Version (MSRV) is 1.29; it is enforced by our CI. The Minimal Supported Rust Version (MSRV) is 1.29; it is enforced by our CI.