CONTRIBUTING.md

Contribution Guide

We love contributions from everyone, whether it's raising an issue, reporting a bug, adding a feature, or helping improve a documentation. Maintaining the medea-jason for all the platforms is not an easy task, so everything you do is support for the project.

1. Code style
   • Rust
   • Dart

Code style

Rust

All Rust source code must be formatted with rustfmt and linted with Clippy linter (see cargo.fmt and cargo.lint commands in Makefile), 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 (in the same manner they're sorted by rustfmt inside use statement).

👍 Correct example

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

🚫 Wrong examples

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

#[derive(Debug, smart_default::SmartDefault, 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);

Dart

All Dart source code must be formatted with dartfmt (see flutter.fmt command in Makefile).