Skip to content

Development

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

To contribute code, please fork the repository and submit a pull request.

Set up the development environment

Clone repository

You can clone the fractal-server repository via 

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

Install uv

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). Note that to run commands from within this environment you should prepend them with uv run (as in uv run --frozen fractalctl set-db).

Update database schema

Whenever the models in app/models are modified, you should update them via a migration. To check whether this is needed, run 

uv run --frozen alembic check

If needed, the simplest procedure is to use alembic --autogenerate to create an incremental migration script, as in 

$ export POSTGRES_DB="autogenerate-fractal-revision"
$ dropdb --if-exist "$POSTGRES_DB"
$ createdb "$POSTGRES_DB"
$ uv run --frozen fractalctl set-db --skip-init-data
$ uv run --frozen alembic revision --autogenerate -m "Some migration message"

Release

  1. Checkout to branch main.
  2. Check that the current HEAD of the main branch passes all the tests (note: make sure that you are using the uv-installed local package).
  3. Update the CHANGELOG.md file (e.g. remove (unreleased) from the upcoming version).
  4. If you have modified the models, then you must also create a new migration script (note: in principle the CI will fail if you forget this step).
  5. 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.
  6. If the previous step looks OK, remove --dry and re-run to actually bump the version, commit and push the changes.
  7. Approve (or have approved) the new version at Publish package to PyPI.
  8. After the release: If the release was a stable one (e.g. X.Y.Z, not X.Y.Za1 or X.Y.Zrc2), move fractal_server/data_migrations/X_Y_Z.py to fractal_server/data_migrations/old.

Run tests

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

To test the SLURM backend, we use a custom version of a Docker local SLURM cluster. The pytest plugin pytest-docker is then used to spin up the Docker containers for the duration of the tests.

Important: this requires docker being installed on the development system, and the current user being in the docker group. A simple check for this requirement is to run a command like docker ps, and verify that it does not raise any permission-related error. Note that also docker compose must be available..

If you installed the development dependencies, you may run the test suite by invoking 

uv run --frozen pytest
from the main directory of the fractal-server repository. It is sometimes useful to specify additional arguments, e.g. 
uv run --frozen pytest -s -v --log-cli-level info --full-trace

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

Documentation

The documentations is built with mkdocs and the Material theme. Docstrings should be formatted as in the Google Python Style Guide.

To build the documentation

  1. Setup a python environment and install the requirements from docs/doc-requirements.txt.
  2. Run 
    uv run --frozen mkdocs serve --config-file mkdocs.yml
    and browse the documentation at http://127.0.0.1:8000.