Developer Guide

Setting Up the Development Environment

This project uses UV as its package manager for managing dependencies and ensuring consistent and reproducible environments. To install UV:

curl -LsSf https://astral.sh/uv/install.sh | sh

PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

See UV’s documentation for details.

Once UV is installed, synchronize your environment with the dependencies specified in the pyproject.toml file, including development dependencies:

uv sync

Testing and Code Quality

Two tools are used to check the code:

  • pytest — unit-tests (located in the tests directory)

  • ruff — linting and formatting checks

Run them against your current environment with:

uv run pytest          # run unit-tests
uv run ruff check      # check for linting issues
uv run ruff format     # auto-format code

Adding --fix to ruff check will automatically correct fixable issues. Both should be clean before a pull request is opened.

To measure how much of the code is covered by the unit-tests, run the tests with coverage enabled and then report on the result:

uv run pytest --cov
uv run coverage report

For a more detailed representation, generate an HTML report:

uv run coverage html

You’ll find the HTML report in the folder htmlcov, where you can open index.html in a web browser to view detailed coverage statistics.

Note

mypy is available in the typing dependency group and can be run with uv run mypy, but the code base is not yet free of type errors, so it is not part of the checks above.

Pull Requests

All development work should be based on the develop branch. To contribute:

  1. Create a new branch from develop:

    git checkout develop
git checkout -b your-branch-name

  2. Make your changes, keeping each pull request focused on a single topic (feature, bugfix, refactor, etc.).

  3. Before opening a pull request, ensure that all tests pass and the code is properly formatted (see Testing and Code Quality)

  4. Open your pull request against the develop branch. The main branch only receives merges from develop as part of the release process.

Building the Documentation

We use Sphinx to build our documentation and API reference. To build the documentation, run the following command:

uv run sphinx-build docs/source docs/build

After running this command, you can view the generated documentation in your web browser by opening docs/build/index.html.

Building the Package

To build ibl-alignment-gui as a distributable Python package, execute the following command:

uv build

This command will create a distributable package of ibl-alignment-gui, in the form of a source distribution (sdist) and a wheel (bdist_wheel). The generated package files will be located in the dist directory.

Versioning Scheme

ibl-alignment-gui uses Semantic Versioning. Its version string (currently 0.1.0a1) is a combination of three fields, separated by dots:

MAJOR . MINOR . PATCH

  • The MAJOR field is only incremented for breaking changes, i.e., changes that are not backward compatible with previous changes.

  • The MINOR field will be incremented upon adding new, backward compatible features.

  • The PATCH field will be incremented with each new, backward compatible bugfix release that does not implement a new feature.

  • Optionally appended letters can be used to indicate an alpha release (a), a beta release (b) or a release candidate (rc).

On the developer side, these fields are controlled by both

  1. adjusting the variable version field in pyproject.toml, and

  2. adding the corresponding version string to a commit as a git tag, for instance:

    git tag 1.2.3
git push origin --tags