Skip to content

Contributing

Dependencies

Create test environment

Get source code

$ git clone https://github.com/ely-as/django-gesha # (1)!
$ cd django-gesha
  1. If you have forked django-gesha, use the URL of your fork here instead.

Create Python environment

Create a virtual environment, for example, in a directory named venv:

$ python -m venv venv

Activate the virtual environment:

$ source venv/bin/activate

$ source venv/bin/activate.fish

$ source venv/bin/activate.csh

C:\> venv\Scripts\activate.bat

PS C:\> venv\Scripts\Activate.ps1

Upgrade pip:

$ pip install --upgrade pip

Install editable django-gesha to Python environment:

$ pip install -e ."[doc,test]"

Create Node.js environment

$ npm install

Develop

Python

Apply formatting

Run the format tox environment to apply formatting using black and isort rules: 

$ tox -e format

Type-hinting

Include the following import at the top of Python modules to enable the latest typing features for all Python versions supported by django-gesha:

1
from __future__ import annotations
Typing features enabled by future import

The following features are available by default in Python 3.10, but the future import is required to enable them in previous Python versions.

PEP Title Python
563 Postponed Evaluation of Annotations 3.8, 3.9
585 Type Hinting Generics In Standard Collections 3.8
604 Allow writing union types as X | Y 3.8, 3.9
Declaring custom types

When declaring custom types use the TYPE_CHECKING constant to prevent execution during runtime:

Example using TYPE_CHECKING constant
1
2
3
4
import typing

if typing.TYPE_CHECKING:
    CoordinateType = dict[str, float]

Otherwise, declarations like this may cause runtime errors in Python 3.9 or lower.

TypeScript

Build assets

$ gulp

To watch source files and continuously build when changes occur: 

$ gulp watch

Test

Python

Lint and type-check

$ tox -e lint-type

Run tests

$ tox -e test

To run tests for all supported Django versions for a specific Python version:

$ tox -m py3.8 # (1)!
  1. See the labels section in tox.ini for available Python labels.

Run test project

$ cd test_project
$ uvicorn fake.asgi:application --reload
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

TypeScript

Lint

$ npm run lint

Run tests

$ npm test
Generating test.html fixture for TypeScript tests

The fixture js_tests/test.html is generated from the test Django project located in test_project. If the test project has been modified the fixture can be regenerated using the following command:

$ python test_project/manage.py printtestpage --pretty -o js_tests/test.html

C:\> python test_project\manage.py printtestpage --pretty -o js_tests\test.html

Documentation

Preview changes to documentation by running the builtin development server:

$ mkdocs serve

Pull request

Make a pull request.

  1. django-gesha supports Python 3.8 or higher, but type-checking requires or Python 3.10 or higher. ↩