Skip to content

docs: Document system dependencies and clarify tool usage #3038

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

Open
rgant wants to merge 2 commits into
base: master
Choose a base branch
from
+28 −2
Open

docs: Document system dependencies and clarify tool usage #3038

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9553c7a
docs: Document system dependencies and clarify tool usage
rgant Feb 4, 2026
b2a981f
docs: Link to upstream install guides for system dependencies
rgant Feb 6, 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
30 changes: 28 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,30 @@ As a first step you will need to fork this repository and clone your fork locall
In order to be able to continuously sync your fork with the origin repository's master branch, you will need to set up an upstream master.
To do so follow this [official github guide](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork).

### System Dependencies

The test suite requires some system libraries that Django itself treats as optional.
This project depends on `mysqlclient`, which needs MySQL/MariaDB C client libraries to build.
Install them for your platform following the
[mysqlclient install guide](https://github.com/PyMySQL/mysqlclient#install).
For Debian/Ubuntu, the [django-docker-box packages list](https://github.com/django/django-docker-box/blob/main/packages.txt)
is also a useful reference.

**GDAL and GEOS** are needed to pass all tests (2 GIS-related tests require them).
See the Django documentation on
[installing geospatial libraries](https://docs.djangoproject.com/en/stable/ref/contrib/gis/install/geolibs/).
If you're not working on GIS-related stubs, you can skip GDAL/GEOS —
the 2 failing tests won't affect other contributions.

> **macOS Note:** Homebrew installs GDAL/GEOS to `/opt/homebrew` (Apple Silicon) or `/usr/local` (Intel),
> which are not in the default library search path. The GIS tests may fail unless you create symlinks:
>
> ```bash
> sudo mkdir -p /usr/local/lib
> sudo ln -s /opt/homebrew/opt/gdal/lib/libgdal.dylib /usr/local/lib/libgdal.dylib
> sudo ln -s /opt/homebrew/opt/geos/lib/libgeos_c.dylib /usr/local/lib/libgeos_c.dylib
> ```

### Dependency Setup

We use [uv](https://github.com/astral-sh/uv) to manage our dev dependencies.
Expand All @@ -45,7 +69,9 @@ uv sync
source .venv/bin/activate
```

Finally, install the pre-commit hooks:
Finally, install the pre-commit hooks. Pre-commit must be installed separately
(see [installation options](https://pre-commit.com/#install)), or you can use `uvx pre-commit` to
run it without installation:

```bash
pre-commit install
Expand All @@ -66,7 +92,7 @@ You can also run pre-commit per file or for a specific path, simply replace "--a
To execute the unit tests, simply run:

```bash
pytest -n auto
uv run pytest -n auto
```

If you get some unexpected results or want to be sure that tests run is not affected by previous one, remove `mypy` cache:
Expand Down
Loading