From b13ac2149bb23ba65428f75d9b370180e460d7d5 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto <5731772+marandaneto@users.noreply.github.com> Date: Fri, 17 Apr 2026 11:00:10 +0100 Subject: [PATCH] docs: add contributing guides --- CONTRIBUTING.md | 51 ++++++++++++++++++++++++++ README.md | 48 +----------------------- sdk_compliance_adapter/CONTRIBUTING.md | 44 ++++++++++++++++++++++ sdk_compliance_adapter/README.md | 40 +------------------- 4 files changed, 98 insertions(+), 85 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 sdk_compliance_adapter/CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..41a0dd6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,51 @@ +# Contributing + +Thanks for your interest in improving the PostHog Elixir SDK. + +## 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" +``` + +## 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. diff --git a/README.md b/README.md index e727e7e..e773ef5 100644 --- a/README.md +++ b/README.md @@ -253,52 +253,6 @@ and using a different HTTP library entirely. If your app works with multiple PostHog projects, PostHog can accommodate you. For setup instructions, consult the [advanced configuration guide](guides/advanced-configuration.md). -## Developing locally - -You should be able to fetch dependencies and run tests right away: - -``` -mix deps.get -mix test -``` - -To run 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` config that will be used for integration tests: - -``` -cp config/integration.example.exs config/integration.exs -``` - -3. Put API key into `config/integration.exs` -4. Run integration tests - -``` -mix test --only integration -``` - -If you want to play with PostHog events in IEx, just create -`config/dev.override.exs` and tweak it to point to the instance of your liking. -This config will be gitignored. Here's 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" -``` - ## Contributing -We welcome contributions! Here's how to get started: - -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 - -For changeset and release instructions, see [RELEASING.md](RELEASING.md). +See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, integration test, and pull request guidelines. diff --git a/sdk_compliance_adapter/CONTRIBUTING.md b/sdk_compliance_adapter/CONTRIBUTING.md new file mode 100644 index 0000000..0824151 --- /dev/null +++ b/sdk_compliance_adapter/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing + +This package contains the PostHog Elixir SDK compliance adapter used with the PostHog SDK Test Harness. + +## Running tests + +Tests run automatically in CI via GitHub Actions. + +### Locally with Docker Compose + +Run the full compliance suite from the `sdk_compliance_adapter` directory: + +```bash +docker-compose up --build --abort-on-container-exit +``` + +This will: + +1. Build the Elixir SDK adapter +2. Pull the test harness image +3. Run all compliance tests +4. Show the results + +### Manually with Docker + +```bash +# Create network +docker network create test-network + +# Build and run adapter +docker build -f sdk_compliance_adapter/Dockerfile -t posthog-elixir-adapter . +docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-elixir-adapter + +# Run test harness +docker run --rm \ + --name test-harness \ + --network test-network \ + ghcr.io/posthog/sdk-test-harness:latest \ + run --adapter-url http://sdk-adapter:8080 --mock-url http://test-harness:8081 + +# Cleanup +docker stop sdk-adapter && docker rm sdk-adapter +docker network rm test-network +``` diff --git a/sdk_compliance_adapter/README.md b/sdk_compliance_adapter/README.md index ac0bdb9..ab3a018 100644 --- a/sdk_compliance_adapter/README.md +++ b/sdk_compliance_adapter/README.md @@ -2,45 +2,9 @@ This adapter wraps the posthog-elixir SDK for compliance testing with the [PostHog SDK Test Harness](https://github.com/PostHog/posthog-sdk-test-harness). -## Running Tests +## Contributing -Tests run automatically in CI via GitHub Actions. See the test harness repo for details. - -### Locally with Docker Compose - -```bash -# From the posthog-elixir/sdk_compliance_adapter directory -docker-compose up --build --abort-on-container-exit -``` - -This will: - -1. Build the Elixir SDK adapter -2. Pull the test harness image -3. Run all compliance tests -4. Show results - -### Manually with Docker - -```bash -# Create network -docker network create test-network - -# Build and run adapter -docker build -f sdk_compliance_adapter/Dockerfile -t posthog-elixir-adapter . -docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-elixir-adapter - -# Run test harness -docker run --rm \ - --name test-harness \ - --network test-network \ - ghcr.io/posthog/sdk-test-harness:latest \ - run --adapter-url http://sdk-adapter:8080 --mock-url http://test-harness:8081 - -# Cleanup -docker stop sdk-adapter && docker rm sdk-adapter -docker network rm test-network -``` +See [CONTRIBUTING.md](CONTRIBUTING.md) for local build and compliance test instructions. ## Implementation