Contributing

We welcome contributions that meet the goals and standards of this project. Contributions may include bug fixes, feature development, corrections or additional context for the documentation, submission of Issues on GitHub, etc.

For development and testing, you can run your own instance of Postgres (either locally or using a DBaaS), or you can use the provided Docker Compose yaml file to provision a containerized PostgreSQL instance locally.

Getting up-and-running

Clone the Repository

git clone https://github.com/OmenApps/django-generate-series.git
cd django-generate-series

Install uv

If you don’t already have uv installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install dependencies

uv sync --extra dev --prerelease=allow

Using your own postgres instance

To develop using your own Postgres instance, you may set the following environmental variables on your machine:

  • DB_NAME (defaults to “postgres”)

  • DB_USER (defaults to “docker”)

  • DB_PASSWORD (defaults to “docker”)

  • DB_HOST (defaults to “localhost”)

  • DB_PORT (defaults to “9932”)

The process of setting environmental variables varies between different operating systems. Generally, on macOS and Linux, you can use the following convention in the console:

export KEY=value

Using the provided docker compose postgres instance

This guide assumes you already have Docker and Docker Compose installed.

Start the PostgreSQL service:

docker compose up -d

These are the database connection details:

DB = postgres
USER = docker
PASSWORD = docker
HOST = localhost
PORT = 9932

To view logs of the database container:

docker compose logs postgres

Once running, you should be able to connect using the test app, psql, or other Postgres management tools if desired.

To completely remove the container and associated data:

docker compose down --rmi all --remove-orphans -v

Once you have a Running Postgres Instance you can:

Install pre-commits:

These ensure code is formatted correctly upon commit. See the pre-commit docs for more information.

uv run pre-commit install

Run the tests:

uv run pytest

Run the full test matrix via nox:

uv run nox --session=tests

Run code coverage report:

uv run nox --session=coverage

Run linting:

uv run nox --session=pre-commit

Check the django test project:

uv run python manage.py check

To run the example project in the python REPL:

uv run python manage.py shell_plus

Build the docs

uv run nox --session=docs-build