Skip to content

docs: add dedicated contributing guides #521

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marandaneto merged 2 commits into from
Apr 17, 2026
+107 −85
Merged

docs: add dedicated contributing guides #521

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f998856
docs: add contributing guides
marandaneto Apr 17, 2026
a03d111
Update CONTRIBUTING.md
marandaneto Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Contributing

Thanks for your interest in improving the PostHog Python 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).

## Testing locally

We recommend using [uv](https://docs.astral.sh/uv/).

1. Create a virtual environment:
- `uv venv env`
- or `python3 -m venv env`
2. Activate it:
- `source env/bin/activate`
3. Install the package in editable mode with development and test dependencies:
- `uv sync --extra dev --extra test`
- or `pip install -e ".[dev,test]"`
4. Install pre-commit hooks:
- `pre-commit install`
5. Run the test suite:
- `make test`
6. Run a specific test if needed:
- `pytest -k test_no_api_key`

## Recommended `uv` workflow

```bash
uv python install 3.12
uv python pin 3.12
uv venv
source .venv/bin/activate
uv sync --extra dev --extra test
pre-commit install
make test
```

## Running locally

Assuming you have a [local version of PostHog](https://posthog.com/docs/developing-locally) running, you can run `python3 example.py` to see the library in action.

## Testing changes locally with the PostHog app

Run `make prep_local` to create a sibling folder named `posthog-python-local`. You can then import it into the PostHog app by changing `pyproject.toml` like this:

```toml
dependencies = [
...
"posthoganalytics" #NOTE: no version number
...
]
...
[tools.uv.sources]
posthoganalytics = { path = "../posthog-python-local" }
```

This lets you test SDK changes fully locally inside the PostHog app stack. It mainly takes care of the `posthog -> posthoganalytics` module renaming. Re-run `make prep_local` each time you make a change, and then run `uv sync --active` in the PostHog app project.
50 changes: 2 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,52 +20,6 @@ Please see the [Python integration docs](https://posthog.com/docs/integrations/p
| 7.0.0 - 7.0.1 | 3.10, 3.11, 3.12, 3.13 | Dropped Python 3.9 support |
| 4.0.1 - 6.x | 3.9, 3.10, 3.11, 3.12, 3.13 | Python 3.9+ required |

## Development
## Contributing

This repo requires all commits to be signed. To configure commit signing, see the [PostHog handbook](https://posthog.com/handbook/engineering/security#commit-signing).

### Testing Locally

We recommend using [uv](https://docs.astral.sh/uv/). It's super fast.

1. Run `uv venv env` (creates virtual environment called "env")
- or `python3 -m venv env`
2. Run `source env/bin/activate` (activates the virtual environment)
3. Run `uv sync --extra dev --extra test` (installs the package in develop mode, along with test dependencies)
- or `pip install -e ".[dev,test]"`
4. you have to run `pre-commit install` to have auto linting pre commit
5. Run `make test`
6. To run a specific test do `pytest -k test_no_api_key`

## PostHog recommends `uv` so...

```bash
uv python install 3.12
uv python pin 3.12
uv venv
source env/bin/activate
uv sync --extra dev --extra test
pre-commit install
make test
```

### Running Locally

Assuming you have a [local version of PostHog](https://posthog.com/docs/developing-locally) running, you can run `python3 example.py` to see the library in action.

### Testing changes locally with the PostHog app

You can run `make prep_local`, and it'll create a new folder alongside the SDK repo one called `posthog-python-local`, which you can then import into the posthog project by changing pyproject.toml to look like this:

```toml
dependencies = [
...
"posthoganalytics" #NOTE: no version number
...
]
...
[tools.uv.sources]
posthoganalytics = { path = "../posthog-python-local" }
```

This'll let you build and test SDK changes fully locally, incorporating them into your local posthog app stack. It mainly takes care of the `posthog -> posthoganalytics` module renaming. You'll need to re-run `make prep_local` each time you make a change, and re-run `uv sync --active` in the posthog app project.
See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, test, and development workflow instructions.
44 changes: 44 additions & 0 deletions sdk_compliance_adapter/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Contributing

This package contains the PostHog Python 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 Python 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-python-adapter .
docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-python-adapter
Comment on lines +24 to +32
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Missing working directory note for "Manually with Docker"

The docker build command uses -f sdk_compliance_adapter/Dockerfile with a repo-relative path, so it must be run from the repository root, not from sdk_compliance_adapter/ as the Docker Compose section instructs. A brief comment (or a prose note matching the one above) would prevent confusion.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: sdk_compliance_adapter/CONTRIBUTING.md
Line: 24-32

Comment:
**Missing working directory note for "Manually with Docker"**

The `docker build` command uses `-f sdk_compliance_adapter/Dockerfile` with a repo-relative path, so it must be run from the **repository root**, not from `sdk_compliance_adapter/` as the Docker Compose section instructs. A brief comment (or a prose note matching the one above) would prevent confusion.

How can I resolve this? If you propose a fix, please make it concise.


# 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
```
39 changes: 2 additions & 37 deletions sdk_compliance_adapter/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,44 +9,9 @@ This is a simple Flask app that:
2. Exposes a REST API for the test harness to control
3. Tracks internal SDK state for test assertions

## 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-python/sdk_compliance_adapter directory
docker-compose up --build --abort-on-container-exit
```

This will:
1. Build the Python 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-python-adapter .
docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-python-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.

## Adapter Implementation

Expand Down
Loading