Contributing to AshArcadic

Copy Markdown View Source

Thank you for your interest in contributing to AshArcadic!

Prerequisites

  • Elixir 1.18+ and Erlang/OTP 27+ (deps resolve from hex, including arcadic)
  • ArcadeDB for integration tests: docker run -p 2480:2480 \ -e JAVA_OPTS="-Darcadedb.server.rootPassword=…" arcadedata/arcadedb:latest

Getting Started

git clone https://github.com/baselabs/ash_arcadic.git
cd ash_arcadic
mix deps.get
mix test

Development Workflow

  1. Create a feature branch from main.
  2. Make your changes with clear, descriptive commit messages.
  3. Ensure all checks pass before opening a PR:
mix format
mix credo --strict
mix compile --warnings-as-errors
mix test
mix dialyzer
  1. Update CHANGELOG.md under [Unreleased].
  2. Open a Pull Request against main.

Ash conventions

  • This is an Ash data layer — a Spark.Dsl.Extension implementing the Ash.DataLayer behaviour. Learn from ash_postgres, ash_sqlite, and the sibling ash_age.
  • Ship a usage-rules.md (agent/consumer usage rules) and generate DSL docs via mix spark.cheat_sheets once the arcade DSL section exists.
  • Read AGENTS.md before touching multitenancy, sensitive-data, or Cypher generation code — its Critical Rules are binding.

Code of conduct

This project follows the Contributor Covenant. By participating, you agree to uphold it.

Versioning & deprecations

The package follows Semantic Versioning (see the CHANGELOG header). The public surface is: the arcade do ... end and replicant do ... end DSL sections, the AshArcadic.* public functions and behaviours (AshArcadic.Client, AshArcadic.ReplicantSink, AshArcadic.ReplicantCheckpoint), telemetry event names and their measurements/metadata keys, and the config :ash_arcadic, ... keys documented in usage-rules.md.

Anything that would remove or change the meaning of that surface follows the deprecation discipline — no silent breaks:

  • The old form keeps working and is marked @deprecated (doc: the replacement and the version that deprecates it) in a minor release, with a CHANGELOG entry.
  • Removal happens no earlier than the next major release — a deprecated form survives at least one full minor cycle.
  • Deprecation warnings must be actionable and value-free (same boundary as errors: no interpolated values), and are never introduced in patch releases.

License

By contributing, you agree that your contributions will be licensed under the MIT License.