Thanks for contributing! This SDK is generated from an OpenAPI specification, which changes what a useful contribution looks like.
Development setup
Tool versions are pinned in .tool-versions (asdf/mise). Then:
mix deps.get
mix test
The golden rule: generated vs. persistent files
lib/ and mix.exs are regenerated from the spec by
./scripts/regenerate.sh — never hand-edit them; your change will be
overwritten. Fixes belong in one of the persistent sources:
| To change… | Edit |
|---|---|
| The API surface | openapi-spec.yaml (or its upstream source) |
| A defect in the upstream spec | an idempotent patch in spec-patches/ |
| How code is generated | .openapi-generator/templates/ (complete vendored set — never delete files from it) |
| Post-generation behavior | scripts/post-generate.sh |
| Tests, config, docs, CI | test/, config/, *.md, .github/ (all protected) |
After changing the spec or templates, run ./scripts/regenerate.sh and
review the diff.
Quality gate
Run the full gate before pushing — it mirrors CI:
mix check # unused deps, warnings-as-errors, format, credo --strict, tests
mix dialyzer # type check (separate; slower)
Coverage is enforced at the floor set in coveralls.json. The
reflection-driven surface tests in test/unit/ cover the generated code
automatically; add behavior-specific tests (using the MockServer harness
in test/support/) for anything you touch.
Commits and releases
- Use Conventional Commit messages (
feat:,fix:,chore:,feat!:for breaking changes). PR titles are validated in CI; squash merges make them the commit history. - Releases are automated from that history via git_ops: run the Release
workflow (or
mix git_ops.releaselocally — the very first release tags the current version manually instead; see the workflow docs). Never edit@versionin mix.exs by hand. - The committed SBOM (
bom.cdx.json) is regenerated by the pre-commit hook when dependencies change — enable it withgit config core.hooksPath .githooksif you cloned fresh.