Contributing to ExRatatui

Copy Markdown View Source

Thanks for your interest in contributing!

ExRatatui is a Rust NIF project, so contributions touch both Elixir and Rust code.

This guide will help you get set up.

Setup

  1. Clone the repo:
git clone https://github.com/mcass19/ex_ratatui.git
cd ex_ratatui
  1. Install dependencies:
  • Elixir 1.17+ and Erlang/OTP 26+
  • Rust toolchain via rustup
  1. Fetch deps and compile from source:
mix deps.get
export EX_RATATUI_BUILD=true
mix compile

The EX_RATATUI_BUILD=true env var tells the library to compile the Rust NIF from source instead of downloading a precompiled binary.

Running Tests

# Elixir tests (includes doctests)
mix test

# Elixir tests with coverage report
mix test --cover

# Rust
mix rust.check

Note: CI enforces 100% test coverage on the Elixir side (NIF modules are excluded). If you add new public functions or branches, make sure to add corresponding tests. Run mix test --cover locally to check before pushing.

Distribution tests

Full cross-node integration tests for the Erlang distribution transport are tagged :distributed and excluded by default (they require the test node to be distributed). To run them:

# Run only distributed tests
elixir --sname test -S mix test --only distributed

# Run all tests (unit + distributed)
elixir --sname test -S mix test --include distributed

Regression tests

The :slow tag is reserved for heavyweight regression tests such as isolated parallel cold-compile checks that would otherwise dominate local test time.

# Run only slow tests
mix test --only slow

# Include slow tests alongside the default suite
mix test --include slow

Branching and Commits

  • Branch from main for all work.
  • Keep commits focused and atomic — one logical change per commit.
  • Prefix commit subjects with a type: feat:, fix:, docs:, test:, refactor:, chore:.

Pull Requests

Before submitting a PR, make sure the following pass:

mix format --check-formatted
mix compile --warnings-as-errors
mix credo --strict
mix dialyzer
mix test --cover
mix rust.check

PR Guidelines

  • Each PR should stay focused on a single feature or fix.
  • Add tests for any new functionality you introduce.
  • Follow the existing code style and patterns in the codebase.
  • Make sure CI passes before requesting review.

Documentation Expectations

  • Every new public function should include both a @doc and a @spec.
  • New widgets should include a @moduledoc with field descriptions and at least one usage example, along with an entry in the Building UIs guide.
  • Any new feature or changed behaviour should have a CHANGELOG entry under [Unreleased].
  • Breaking changes should include a "Migration" note in the CHANGELOG entry that explains what callers need to change.
  • If a feature introduces a guide-worthy topic, add or update a guide in guides/ and update the README accordingly.