# Contributing

Thanks for your interest in improving the PostHog Elixir SDK.

## Commit signing

This repo requires all commits to be signed. To configure commit signing, see the [PostHog handbook](https://posthog.com/handbook/engineering/security#commit-signing). Set `commit.gpgsign` to `true` in your git config so that every commit is signed, not only the ones you sign by hand.

## Developing locally

Fetch dependencies and run the test suite from the repository root:

```bash
mix deps.get
mix test
```

### Integration tests

To run the integration test suite that sends real events to the API:

1. Create a test PostHog project and obtain an API key.
2. Create `config/integration.exs` from the example file:

   ```bash
   cp config/integration.example.exs config/integration.exs
   ```

3. Put your API key into `config/integration.exs`.
4. Run the integration tests:

   ```bash
   mix test --only integration
   ```

### Local development config

If you want to play with PostHog events in IEx, create `config/dev.override.exs` and point it at the instance of your choosing. This file is gitignored. A minimal example:

```elixir
# config/dev.override.exs
import Config

config :posthog,
  enable: true,
  api_host: "https://us.i.posthog.com",
  api_key: "phc_XXXX"
```

## Public API changes

Public API is hard to change once it ships, so agree on it before writing the implementation. Our [SDK guidelines](https://posthog.com/handbook/engineering/sdks/guidelines) explain how we design it.

This section is for external contributors. PostHog maintainers (members of the PostHog GitHub org) agree on API shape in the PR itself, so they don't need a separate issue.

- **Before you start:** if you need something the SDK doesn't support and it would add or change a public option, method, or type, open an issue describing your use case. Wait for a maintainer to agree on the API shape there before you implement it. Context is more useful to us than code at this stage.
- **Already specified?** If a published [sdk-spec](https://github.com/PostHog/sdk-specs) defines the API, that's the agreement, so you don't need an issue.
- **Already have a PR open?** Don't stop or rewrite it. Call out the public API change at the top of the PR description, and link or open an issue so we can discuss the shape there.
- Check first whether an existing option or hook, such as `before_send`, already covers the use case. We avoid offering two ways to do the same thing.
- If a reviewer suggests a different API on your PR, confirm it with them before re-implementing. Treat it as a question, not an instruction.

## Pull requests

1. Fork the repository and create your feature branch.
2. Make your changes and ensure tests pass with `mix test`.
3. Run `mix format` and `mix credo --strict` to ensure code quality.
4. Open a pull request.