Contributing to Ramal

Copy Markdown View Source

Thanks for looking. Ramal is pre-alpha, so the most useful contributions right now are design review, tests that break the overlay, and reports of Ash features the hooks do not handle. Read docs/DESIGN.md first; the section "How reads are patched" is the one that decides whether a change is correct.

Setup

mise install                     # Erlang and Elixir pinned in mise.toml
docker compose up -d db          # Postgres 16 on port 5435
mix deps.get
mix ci                           # format, compile --warnings-as-errors, credo, tests

Ground rules

Everything in CLAUDE.md applies to humans too: small branches, one topic per PR, mix ci green, a changelog line for every user-facing change, docs in the same PR as the code.

Reporting a bug

Open an issue with the resource definition, the action, the call inside the branch, what you expected the branch to see, and what it saw. A failing test in test/ is the best report.

Proposing a design change

Open an issue first. If we agree, the PR adds an ADR under docs/adr/ and updates docs/DESIGN.md.

Releasing

A maintainer with a Hex account does this; CI has no Hex key.

  1. A PR bumps @version in mix.exs and in ramal_live/mix.exs (the two packages share a version) and turns Unreleased in CHANGELOG.md into the version with its date.
  2. After it merges, tag the merge commit vX.Y.Z (the docs link to source at that tag).
  3. Check mix hex.build and mix docs, read the file list and dependencies hex.build prints, then mix hex.publish. The package ships lib, mix.exs, the README, the license, the changelog and the logo; nothing under priv/ or test/.
  4. Publish ramal_live after ramal, since it depends on it: Hex refuses a path dependency, so run it with RAMAL_LIVE_HEX=1 (RAMAL_LIVE_HEX=1 mix deps.get, mix hex.build, mix hex.publish, all inside ramal_live/). Do not commit the mix.lock change that makes.
  5. Replace "Not on Hex yet" in the README install section, and in ramal_live/README.md and RamalLive's module doc.

Code of conduct

Participation is governed by the Code of Conduct: be kind, be specific, assume good faith. Maintainers will remove anyone who is not. Security reports go through SECURITY.md, never a public issue.