Skip to content

Commit fe12309

Browse files
marandanetogreptile-apps[bot]
marandaneto
and
greptile-apps[bot]
authored
docs: add dedicated contributing guides (#521)
* docs: add contributing guides * Update CONTRIBUTING.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
1 parent 12c38e7 commit fe12309

4 files changed

Lines changed: 107 additions & 85 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Contributing
2+
3+
Thanks for your interest in improving the PostHog Python SDK.
4+
5+
## Commit signing
6+
7+
This repo requires all commits to be signed. To configure commit signing, see the [PostHog handbook](https://posthog.com/handbook/engineering/security#commit-signing).
8+
9+
## Testing locally
10+
11+
We recommend using [uv](https://docs.astral.sh/uv/).
12+
13+
1. Create a virtual environment:
14+
- `uv venv env`
15+
- or `python3 -m venv env`
16+
2. Activate it:
17+
- `source env/bin/activate`
18+
3. Install the package in editable mode with development and test dependencies:
19+
- `uv sync --extra dev --extra test`
20+
- or `pip install -e ".[dev,test]"`
21+
4. Install pre-commit hooks:
22+
- `pre-commit install`
23+
5. Run the test suite:
24+
- `make test`
25+
6. Run a specific test if needed:
26+
- `pytest -k test_no_api_key`
27+
28+
## Recommended `uv` workflow
29+
30+
```bash
31+
uv python install 3.12
32+
uv python pin 3.12
33+
uv venv
34+
source .venv/bin/activate
35+
uv sync --extra dev --extra test
36+
pre-commit install
37+
make test
38+
```
39+
40+
## Running locally
41+
42+
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.
43+
44+
## Testing changes locally with the PostHog app
45+
46+
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:
47+
48+
```toml
49+
dependencies = [
50+
...
51+
"posthoganalytics" #NOTE: no version number
52+
...
53+
]
54+
...
55+
[tools.uv.sources]
56+
posthoganalytics = { path = "../posthog-python-local" }
57+
```
58+
59+
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.

‎README.md‎

Lines changed: 2 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -20,52 +20,6 @@ Please see the [Python integration docs](https://posthog.com/docs/integrations/p
2020
| 7.0.0 - 7.0.1 | 3.10, 3.11, 3.12, 3.13 | Dropped Python 3.9 support |
2121
| 4.0.1 - 6.x | 3.9, 3.10, 3.11, 3.12, 3.13 | Python 3.9+ required |
2222

23-
## Development
23+
## Contributing
2424

25-
This repo requires all commits to be signed. To configure commit signing, see the [PostHog handbook](https://posthog.com/handbook/engineering/security#commit-signing).
26-
27-
### Testing Locally
28-
29-
We recommend using [uv](https://docs.astral.sh/uv/). It's super fast.
30-
31-
1. Run `uv venv env` (creates virtual environment called "env")
32-
- or `python3 -m venv env`
33-
2. Run `source env/bin/activate` (activates the virtual environment)
34-
3. Run `uv sync --extra dev --extra test` (installs the package in develop mode, along with test dependencies)
35-
- or `pip install -e ".[dev,test]"`
36-
4. you have to run `pre-commit install` to have auto linting pre commit
37-
5. Run `make test`
38-
6. To run a specific test do `pytest -k test_no_api_key`
39-
40-
## PostHog recommends `uv` so...
41-
42-
```bash
43-
uv python install 3.12
44-
uv python pin 3.12
45-
uv venv
46-
source env/bin/activate
47-
uv sync --extra dev --extra test
48-
pre-commit install
49-
make test
50-
```
51-
52-
### Running Locally
53-
54-
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.
55-
56-
### Testing changes locally with the PostHog app
57-
58-
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:
59-
60-
```toml
61-
dependencies = [
62-
...
63-
"posthoganalytics" #NOTE: no version number
64-
...
65-
]
66-
...
67-
[tools.uv.sources]
68-
posthoganalytics = { path = "../posthog-python-local" }
69-
```
70-
71-
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.
25+
See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, test, and development workflow instructions.

‎sdk_compliance_adapter/CONTRIBUTING.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Contributing
2+
3+
This package contains the PostHog Python SDK compliance adapter used with the PostHog SDK Test Harness.
4+
5+
## Running tests
6+
7+
Tests run automatically in CI via GitHub Actions.
8+
9+
### Locally with Docker Compose
10+
11+
Run the full compliance suite from the `sdk_compliance_adapter` directory:
12+
13+
```bash
14+
docker-compose up --build --abort-on-container-exit
15+
```
16+
17+
This will:
18+
19+
1. Build the Python SDK adapter
20+
2. Pull the test harness image
21+
3. Run all compliance tests
22+
4. Show the results
23+
24+
### Manually with Docker
25+
26+
```bash
27+
# Create network
28+
docker network create test-network
29+
30+
# Build and run adapter
31+
docker build -f sdk_compliance_adapter/Dockerfile -t posthog-python-adapter .
32+
docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-python-adapter
33+
34+
# Run test harness
35+
docker run --rm \
36+
--name test-harness \
37+
--network test-network \
38+
ghcr.io/posthog/sdk-test-harness:latest \
39+
run --adapter-url http://sdk-adapter:8080 --mock-url http://test-harness:8081
40+
41+
# Cleanup
42+
docker stop sdk-adapter && docker rm sdk-adapter
43+
docker network rm test-network
44+
```

‎sdk_compliance_adapter/README.md‎

Lines changed: 2 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -9,44 +9,9 @@ This is a simple Flask app that:
99
2. Exposes a REST API for the test harness to control
1010
3. Tracks internal SDK state for test assertions
1111

12-
## Running Tests
12+
## Contributing
1313

14-
Tests run automatically in CI via GitHub Actions. See the test harness repo for details.
15-
16-
### Locally with Docker Compose
17-
18-
```bash
19-
# From the posthog-python/sdk_compliance_adapter directory
20-
docker-compose up --build --abort-on-container-exit
21-
```
22-
23-
This will:
24-
1. Build the Python SDK adapter
25-
2. Pull the test harness image
26-
3. Run all compliance tests
27-
4. Show results
28-
29-
### Manually with Docker
30-
31-
```bash
32-
# Create network
33-
docker network create test-network
34-
35-
# Build and run adapter
36-
docker build -f sdk_compliance_adapter/Dockerfile -t posthog-python-adapter .
37-
docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-python-adapter
38-
39-
# Run test harness
40-
docker run --rm \
41-
--name test-harness \
42-
--network test-network \
43-
ghcr.io/posthog/sdk-test-harness:latest \
44-
run --adapter-url http://sdk-adapter:8080 --mock-url http://test-harness:8081
45-
46-
# Cleanup
47-
docker stop sdk-adapter && docker rm sdk-adapter
48-
docker network rm test-network
49-
```
14+
See [CONTRIBUTING.md](CONTRIBUTING.md) for local build and compliance test instructions.
5015

5116
## Adapter Implementation
5217

0 commit comments

Comments
 (0)