# Contributing to AshArcadic

Thank you for your interest in contributing to AshArcadic!

## Prerequisites

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

## Getting Started

```bash
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:

```bash
mix format
mix credo --strict
mix compile --warnings-as-errors
mix test
mix dialyzer
```

4. Update `CHANGELOG.md` under `[Unreleased]`.
5. 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](CODE_OF_CONDUCT.md). By
participating, you agree to uphold it.

## Versioning & deprecations

The package follows [Semantic Versioning](https://semver.org) (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.