Contributing to RasterExRatatui

Copy Markdown View Source

Thanks for the interest in contributing!

RasterExRatatui is built on ExRatatui. Consider contributing to the upstream library too when a feature is missing or something is not working. Contributions are welcome everywhere!

This guide covers the setup.

Setup

  1. Clone the repo:
git clone https://github.com/mcass19/raster_ex_ratatui.git
cd raster_ex_ratatui
  1. Prerequisites:
  • Elixir 1.17+ and Erlang/OTP 26+.
  • No device: the library is pure Elixir, and every test runs on the host against a headless ExRatatui.CellSession.
  • No Rust toolchain: ex_ratatui ships a precompiled NIF. Make sure EX_RATATUI_BUILD is not set in the environment, or ex_ratatui will build its NIF from source instead.
  1. Fetch dependencies:
mix deps.get

Running Tests

mix test
mix test --cover        # must report 100.00% Total

The suite never touches a terminal or a display. Rasterisation is tested against cell diffs taken from a real ExRatatui.CellSession (created with font_size:, so Viewport3D and Image produce pixel regions), and the device helpers (RasterExRatatui.Framebuffer) take their file access as an injected module, so they are covered without /dev/fb0. Property-based invariants via stream_data run as part of the regular mix test.

Branching and Commits

  • Branch from main
  • Keep commits focused and atomic
  • Use descriptive commit message prefixes: 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
  • Keep PRs focused — one feature or fix per PR
  • Add tests for new functionality
  • Add @doc, @spec, and @moduledoc for new public functions and modules
  • Update documentation (moduledocs, guides, CHANGELOG, README if applicable)
  • For breaking changes, include migration notes in the CHANGELOG
  • Follow existing code style and patterns
  • Ensure CI passes before requesting review