Contributing: remove derivation section
This commit is contained in:
parent
313ac7d4a8
commit
45dbaa7e26
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue