Development¶

Setting up environment¶

We use pixi to manage development environments. See the pixi installation guide for setup instructions.

From the repository root folder, run:

# Install the default environment
pixi install

# Install the development environment (includes test dependencies)
pixi install -e dev

# Install the documentation environment
pixi install -e docs

Testing¶

We use pytest for unit and integration testing. If you installed the development environment, you may run the test suite by invoking commands like:

# Run all tests
pixi run -e dev pytest

# Run all tests with a verbose mode, and stop at the first failure
pixi run -e dev pytest -x -v

# Run all tests and also print their output
pixi run -e dev pytest -s

The test files are in the tests folder of the repository.

Tests are also run through GitHub Actions, with Python 3.11 and 3.12. Within GitHub Actions we run tests for both the pixi-installed and pip-installed versions of the code, which may have different versions of some dependencies.

Documentation¶

The documentation is built with mkdocs. To build the documentation locally, setup the docs environment and then run one of these commands:

pixi run -e docs mkdocs serve --config-file mkdocs.yml  # serves the docs at http://127.0.0.1:8000
pixi run -e docs mkdocs build --config-file mkdocs.yml  # creates a build in the `site` folder

A dedicated GitHub action takes care of building the documentation and pushing it to https://fractal-analytics-platform.github.io/fractal-tasks-core, when commits are pushed to the main branch.

Release to PyPI¶

Preliminary check-list¶

The main branch is checked out.
All tests are passing, for the main branch.
CHANGELOG.md is up to date.
If appropriate (e.g. if you added some new task arguments, or if you modified some of their descriptions), update the manifest via:
```
pixi run -e dev fractal-manifest create --package fractal_tasks_core
```
(note that the CI will fail if you forgot to update the manifest, but it is good to be aware of it)

Actual release¶

From within the main branch, create a new git tag:

# For a release version
git tag 1.2.3

# For a prerelease version
git tag 1.2.3a1

Push the tag to the remote:
```
git push origin <tag>
```
Approve the new version deployment at Publish package to PyPI (or have it approved); the corresponding GitHub action will take care of building and publishing the package with the appropriate credentials.

Static type checker¶

We do not enforce strict mypy compliance, but we do run it as part of a specific GitHub Action. You can run mypy locally for instance as:

pixi run -e dev mypy --package fractal_tasks_core --ignore-missing-imports --warn-redundant-casts --warn-unused-ignores --warn-unreachable --pretty