Contribute to Fractal Client development¶

The development of Fractal Client takes place on the fractal-client Github repository. To ask questions or to inform us of a bug or unexpected behavior, please feel free to open an issue.

Set up the development environment¶

Clone repository¶

First, you should clone the repository

git clone https://github.com/fractal-analytics-platform/fractal-client.git
cd fractal-client

Install package¶

We use uv to manage the development environment and the dependencies - see https://docs.astral.sh/uv/getting-started/installation/ for methods to install it. Running

$ uv venv
$ uv sync --frozen [--group dev] [--group docs]

will create a new virtual environment in ./.venv and install the main dependencies (and optionally the dev/docs groups).

Build and release¶

Preliminary check-list:

The main branch is checked out.
You reviewed dependencies, and the lock file is up to date with pyproject.toml.
The current HEAD of the main branch passes all the tests (uv run pytest).
You updated the CHANGELOG.md file.
You updated docs/versions.md with the constraints for the new version.

Actual release instructions:

Use one of the following

uv run --frozen bumpver update --tag-num --tag-commit --commit --dry
uv run --frozen bumpver update --patch --tag-commit --commit --dry
uv run --frozen bumpver update --minor --tag-commit --commit --dry
uv run --frozen bumpver update --set-version X.Y.Z --tag-commit --commit --dry

to test updating the version bump.

If the previous step looks good, remove --dry and re-run to actually bump the version. This will trigger a dedicated GitHub action to build the new package and publish it to PyPI.

Run tests¶

Unit and integration testing of Fractal Server uses the pytest testing framework.

Before running the test suite, a Fractal Server instance and a PostgreSQL database must be available. For convenience, both services can be started via Docker Compose using the configuration provided at tests/fractal-server/docker-compose.yml:

docker compose -f tests/fractal-server/docker-compose.yml up

The Fractal Server service can be customized via environment variables:

FRACTAL_SERVER_BRANCH: Git branch of the Fractal Server repository to use (defaults to main).

For example:

export FRACTAL_SERVER_BRANCH=123-bug-fix
docker compose -f tests/fractal-server/docker-compose.yml up

Then, you may run the test suite by invoking

uv run pytest

from the main directory of the fractal-client repository. It is sometimes useful to specify additional arguments, e.g.

uv run pytest -s -vvv --log-cli-level info --full-trace

Tests are also run as part of GitHub Actions Continuous Integration for the fractal-client repository.

Documentation¶

The documentations is built with zensical. You can preview it locally through

uv run python3 docs/scripts/generate_cli_ref.py
uv run zensical serve