CONTRBUTING.md

Contribution Guide

1. Code style

Code style

All Rust source code must be formatted with rustfmt and linted with Clippy linter, customized by project settings (.rustfmt.toml and .clippy.toml files).

Additional rules, not handled by rustfmt and Clippy are described below.

Attributes

Attributes on declarations must be sorted in alphabetic order. Items inside attribute must be sorted in alphabetic order too.

👍 Correct example

#[allow(clippy::mut_mut)]
#[derive(Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
struct User {
    #[serde(default)]
    id: u64,
}

🚫 Wrong examples

#[serde(deny_unknown_fields)]
#[derive(Debug, Deserialize, Serialize)]
#[allow(clippy::mut_mut)]
struct User {
    id: u64,
}

#[derive(Debug, Serialize, Deserialize)]
struct User {
    id: u64,
}

Markdown in docs

It's recommended to use H1 headers (# Header) in Rust docs as this way is widely adopted in Rust community. Blank lines before headers must be reduced to a single one.

Bold and italic text should be marked via ** and _ accordingly.

Other code definitions should be referred via [`Entity`] marking (intra-doc links).

👍 Correct example

/// Type of [`User`]'s unique identifier.
/// 
/// # Constraints
/// 
/// - It **must not be zero**.
/// - It _should not_ overflow [`i64::max_value`] due to usage in database.
struct UserId(u64);

🚫 Wrong examples

• H2 header is used at the topmost level:

  /// Type of [`User`]'s unique identifier.
  /// 
  /// ## Constraints
  /// 
  /// - It **must not be zero**.
  /// - It _should not_ overflow [`i64::max_value`] due to usage in database.
  struct UserId(u64);

• Code definition is not referred correctly:

  /// Type of User's unique identifier.
  /// 
  /// # Constraints
  /// 
  /// - It **must not be zero**.
  /// - It _should not_ overflow `i64::max_value` due to usage in database.
  struct UserId(u64);

• Incorrect bold/italic marking:

  /// Type of [`User`]'s unique identifier.
  /// 
  /// # Constraints
  /// 
  /// - It __must not be zero__.
  /// - It *should not* overflow [`i64::max_value`] due to usage in database.
  struct UserId(u64);