Contributing to Zut

Prepare

Prepare Python environment:

python3 -m venv .venv       # Windows: python -m venv .venv
source .venv/bin/activate   # Windows: .\.venv\Scripts\activate
pip install -r requirements.txt

Start test databases and servers (as Docker containers):

docker compose up -d

Test

Run unit tests:

python -m test

Run unit tests with another Python version:

docker compose --profile specific run --build --rm test-3.7

Publish

IMPORTANT: Review the following prerequisites before publishing a stable version:

Search for TODO and FIXME
Search for ROADMAP: they should be followed by expected timeline
Search for type: ignore: they should be followed by the reason

Ensure build dependencies are installed:

python3 -m venv .venv.build
source .venv.build/bin/activate
pip install -r build-requirements.txt

Create package:

pip wheel --no-deps -w dist .

Verify package:

version=$(python -c 'from zut import __version__; print(__version__)')
twine check "dist/zut-$version-py3-none-any.whl"

Publish package:

# (optional: network and token configuration)
# export HTTPS_PROXY=http://proxy:3128
# export NO_PROXY=127.0.0.1,localhost,.lan
# export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
# pass insert python-keyring/https:/upload.pypi.org/legacy/__token__

twine upload "dist/zut-$version-py3-none-any.whl"

Create documentation:

rm -rf docs/api docs/build

version=$(python -c 'from zut import __version__; print(__version__)')
target="docs/build/zut/v$version"

sphinx-build docs "$target"

(cd docs/build/zut; zip -r "../../../dist/zut-docs-$version.zip" "v$version"; docs-versions-menu --default-branch main --no-downloads-file)

Serve documentation:

python -m http.server -b 127.0.0.1 -d docs/build 8001

Publish documentation:

ssh_server=
scp "dist/zut-docs-$version.zip" $ssh_server:"zut-docs-$version.zip"
ssh "$ssh_server" ./update-docs.sh "zut-docs-$version.zip"