Contributing to Clarion

Copy Markdown View Source

Thanks for considering a contribution. Clarion is deliberately small in scope — see docs/design_decisions.md for what's intentionally out of v1 before proposing a feature that adds it back in.

Getting set up

mix deps.get
mix test

Before opening a PR

Run the same checks CI runs:

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

Expectations for changes

  • Tests must exercise real :logger/Logger behavior. Attach an actual :logger handler in setup and assert on what it receives — see test/clarion_test.exs for the pattern. Tests that only call Clarion's internal functions in isolation don't prove anything about the correctness property this library exists for.
  • Every public function/macro needs a @doc with a runnable doctest, and every plain function needs a @spec. Macros don't get @spec — see the note in docs/design_decisions.md on why (Dialyzer analyzes expanded call sites, not macro definitions; Logger itself follows the same convention).
  • No runtime dependencies beyond Elixir's own :logger/Logger. ex_doc, credo, and dialyxir are dev/test-only.
  • If a change touches how report_cb is stored, invoked, or not invoked, re-read docs/how_logging_actually_works.md first — that document is the reasoning this library's core guarantee is built on, and it should stay accurate if the implementation changes.

Reporting issues

Open a GitHub issue with a minimal reproduction. If it involves how a specific :logger handler or third-party formatter behaves, include the exact handler/formatter configuration — a lot of the subtlety this library cares about is handler-configuration-dependent.