diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..499e7dd3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# Contributing + +Thanks for your interest in improving the PostHog .NET SDK. + +## Building + +From the repository root, restore dependencies and build the solution: + +```bash +dotnet restore +dotnet build +``` + +## Running samples + +Sample projects live in the `samples` directory. + +To run the samples, set your PostHog project API key from the repository root: + +```bash +bin/user-secrets set PostHog:ProjectApiKey YOUR_API_KEY +``` + +The main ASP.NET Core sample app can then be started with: + +```bash +bin/start +``` + +You can also run the samples from your preferred IDE or editor. + +## Testing + +Run the test suite from the repository root: + +```bash +dotnet test +``` + +### Test target frameworks + +The test projects target both `net8.0` and `netcoreapp3.1`. While .NET Core 3.1 reached end-of-life in December 2022, we continue to test against it because: + +- It was the first runtime to fully support .NET Standard 2.1 +- It serves as our minimum test baseline to ensure the `netstandard2.1` library works correctly on older runtimes +- It helps catch compatibility issues that might not surface on newer runtimes + +This testing approach ensures broad compatibility without requiring users to install legacy runtimes in production. + +## Pull requests + +Please follow existing conventions and include tests for your change when practical. + +For release instructions, see [RELEASING.md](RELEASING.md). diff --git a/README.md b/README.md index 84815c84..82548fa9 100644 --- a/README.md +++ b/README.md @@ -22,57 +22,14 @@ For documentation on the specific packages, see the README files in the respecti The core [PostHog](./src/PostHog/README.md) package targets `netstandard2.1` and `net8.0` for broad compatibility. The [PostHog.AspNetCore](src/PostHog.AspNetCore/README.md) package targets `net8.0`. The [PostHog.AI](src/PostHog.AI/README.md) package targets `netstandard2.1` and `net8.0` for broad compatibility. -## Building +## Contributing -To build the solution, run the following commands in the root of the repository: - -```bash -$ dotnet restore -$ dotnet build -``` +See [CONTRIBUTING.md](CONTRIBUTING.md) for build, sample, and test instructions. ## Docs More detailed docs for using this library can be found at [PostHog Docs for the .NET Client SDK](https://posthog.com/docs/libraries/dotnet). -## Samples - -Sample projects are located in the `samples` directory. - -To run the samples, you'll need to set your PostHog project API key. From the repository root you can run: - -```bash -bin/user-secrets set PostHog:ProjectApiKey YOUR_API_KEY -``` - -The main ASP.NET Core sample app can be run with the following command: - -```bash -$ bin/start -``` - -You can also run it from your favorite IDE or editor. - -## Testing - -To run the tests, run the following command in the root of the repository: - -```bash -$ dotnet test -``` - -### Test Target Frameworks - -The test projects target both `net8.0` and `netcoreapp3.1`. While .NET Core 3.1 reached end-of-life in December 2022, we continue to test against it because: - -- It was the first runtime to fully support .NET Standard 2.1 -- It serves as our minimum test baseline to ensure the `netstandard2.1` library works correctly on older runtimes -- It helps catch compatibility issues that might not surface on newer runtimes - -This testing approach ensures broad compatibility without requiring users to install legacy runtimes in production. - -For release instructions, see [RELEASING.md](RELEASING.md). - ## Installation For ASP.NET Core projects, install the `PostHog.AspNetCore` package: diff --git a/sdk_compliance_adapter/CONTRIBUTING.md b/sdk_compliance_adapter/CONTRIBUTING.md new file mode 100644 index 00000000..3b052e84 --- /dev/null +++ b/sdk_compliance_adapter/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing + +This package contains the PostHog .NET 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 .NET 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-dotnet-adapter . +docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-dotnet-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 92a3c2a5..20642034 100644 --- a/sdk_compliance_adapter/README.md +++ b/sdk_compliance_adapter/README.md @@ -2,45 +2,9 @@ This adapter wraps the posthog-dotnet 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-dotnet/sdk_compliance_adapter directory -docker-compose up --build --abort-on-container-exit -``` - -This will: - -1. Build the .NET 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-dotnet-adapter . -docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-dotnet-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