Contributing to django-postgresql-dag¶

We would love your input! We want to make contributing to the project as easy and transparent as possible. We welcome…

Reporting a bug
Discussing the current state of the code
Submitting a fix
Proposing new features
Becoming a maintainer

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

Getting the Code¶

git clone https://github.com/OmenApps/django-postgresql-dag.git
cd django-postgresql-dag

Or fork the repository on GitHub first, then clone your fork.

Prerequisites¶

Python 3.11+
uv - for dependency management
Docker - for running PostgreSQL (or a local PostgreSQL 16+ instance)

Installing Dependencies¶

uv sync --group dev

To include optional NetworkX/pandas transformation support:

uv sync --group dev --extra transforms

Running PostgreSQL¶

The easiest way to get PostgreSQL running is with Docker Compose:

docker compose up -d

This starts PostgreSQL 16 on host port 5433 (mapped from container port 5432) with default credentials postgres/postgres. The test settings default to port 5433, so no environment variables are needed when using Docker Compose.

For a custom PostgreSQL setup, configure the connection with environment variables:

Variable	Default
`PG_HOST`	`localhost`
`PG_PORT`	`5433`
`PG_USER`	`postgres`
`PG_PASSWORD`	`postgres`
`PG_DATABASE`	`postgres`

Running Tests¶

# Run tests with pytest
uv run pytest tests/ -vv

# Or with the Django test runner
uv run python manage.py test

To run the full test matrix across Python and Django versions using nox:

# All default nox sessions (pre-commit, pip-audit, tests)
uv run nox

# A specific Django/Python combination
uv run nox -s "tests(django='5.2', python='3.13')"

Linting & Formatting¶

uv run ruff check src/              # lint
uv run ruff check --fix src/        # lint and auto-fix
uv run ruff format src/             # format
uv run pre-commit run --all-files   # run all pre-commit hooks

Building Documentation¶

# Build docs with live reload (opens browser)
uv run nox -s docs

# Build docs without serving
uv run nox -s docs-build

Nox Sessions¶

Running nox with no arguments executes the default sessions:

pre-commit - runs all pre-commit hooks
pip-audit - scans dependencies for known vulnerabilities
tests - runs the test suite across the Python/Django version matrix

Additional sessions:

docs - builds and serves docs with live reload
docs-build - builds docs to docs/_build/
coverage - combines and reports test coverage

Code Changes Happen Through Pull Requests¶

Pull requests are the best way to propose changes to the codebase. We actively welcome your pull requests:

Fork the repo and create your branch from main.
If you’ve added code that should be tested, add tests.
If you’ve changed APIs, update the documentation.
Ensure the test suite passes.
Make sure your code lints.
Issue that pull request!

Coding Style & Commit Messages¶

Follow Django coding conventions with a line length of 120
Use ruff for linting and formatting
Git commit messages: present tense imperative, first line 72 characters or less (e.g., “Add feature” not “Added feature”)
Reference relevant issues and pull requests as needed after the first line

Report Bugs¶

We use GitHub issues to track public bugs. Report a bug by opening a new issue; it’s that easy!

Great Bug Reports tend to have:

A quick summary and/or background
Steps to reproduce
- They are specific!
- Give sample code if you can that can be used to easily reproduce the issue. Ideally, strip out everything that does not pertain to the problem or which is not required to allow the sample to run.
What you expected would happen
What actually happens
Notes (possibly including why you think this might be happening, or stuff you tried that didn’t work)

We love thorough bug reports.

Be Kind¶

This project is volunteer run. Please be kind in your discourse.

License¶

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.