Skip to content

Latest commit

 

History

History
180 lines (122 loc) · 4.94 KB

CONTRIBUTING_CODE.md

File metadata and controls

180 lines (122 loc) · 4.94 KB

Contributing to Malachite

Thank you for your interest in contributing to Malachite, a Byzantine Fault Tolerant (BFT) consensus engine written in Rust.

This document provides guidelines and instructions to help you set up your development environment and contribute to the project.

Table of Contents

Scope of Contributions

Please make sure to read the corresponding section in CONTRIBUTING.md.

Setup

Prerequisites

To build and test Malachite, you need the following tools:

  • Rust: Install the latest stable Rust toolchain using rustup
  • Node.js: Required for running Quint
  • Quint: A formal specification language used for our model-based tests
  • cargo-nextest: An improved test runner for Rust

Environment Setup

  1. Install Rust:

    Via rustup.rs:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

  2. Install Node.js: (only required for running model-based tests)

    Follow the instructions at nodejs.org or use a version manager:

    # Using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 21
nvm use 21

  3. Install Quint: (only required for running model-based tests)

    npm install -g @informalsystems/quint

  4. Install cargo-nextest:

    cargo install cargo-nextest

  5. Fork and clone the repository:

    git clone https://github.com/USERNAME/malachite.git
cd malachite/code

Note

If you do not intend to contribute code and just want to play around with the codebase, you can just clone the repository directly: git clone https://github.com/informalsystems/malachite.git

Building the Project

To build the project, run:

cargo build

Running Tests

We have several categories of tests that help ensure the quality and correctness of our code.

Unit and Integration Tests

cargo all-tests

Or run specific integration tests:

  1. Discovery:

    cargo nextest run -p informalsystems-malachitebft-discovery-test

  2. Starknet app:

    cargo nextest run -p informalsystems-malachitebft-starknet-test

  3. Test app:

    cargo nextest run -p informalsystems-malachitebft-test

Important

For the integration tests to run successfully it is important to ensure that only one integration test is running at a time, by supplying the --test-threads=1 flag to cargo-nextest. This is done automatically via the code/.config/nextest.toml configuration file, but can be overridden from the command line if needed.

Tip

If you are on a Linux-based system, you can use cargo-maelstrom to run each test in isolation, concurrently.

cargo install cargo-maelstrom
cargo maelstrom --slots 16

Model-Based Tests (MBT)

Model-based tests use formal specifications to generate test scenarios and validate system behavior against them.

To run model-based tests:

cargo mbt

Code Style and Guidelines

We follow Rust's official style guidelines. Before submitting your code, please ensure:

  1. Format your code using rustfmt:

    cargo fmt

  2. Run Clippy to catch common mistakes and ensure code quality:

    cargo lint

Pull Request Process

  1. Fork the repository and create your branch from main.
  2. Make your changes and ensure all tests pass.
  3. Update documentation as needed.
  4. Submit a pull request with a clear description of the changes and any relevant issue numbers.
  5. Address any feedback from code reviewers.

When submitting a PR, our CI will automatically run all tests, Clippy checks, and formatting verification.

Continuous Integration

We use GitHub Actions for continuous integration. The following checks run on every PR:

  • Unit Tests: Ensures individual components work correctly.
  • Integration Tests: Validates component interactions.
  • Model-Based Tests: Checks against formal specifications.
  • Clippy: Catches common Rust mistakes and enforces best practices.
  • Formatting: Ensures consistent code style with rustfmt.

Thank you for contributing to Malachite! If you have any questions, feel free to open an issue or ask the maintainers.