Developer Guide

Versioning Scheme

IBLRIG v8 uses Semantic Versioning. Its version string (currently “8.24.7”) 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. Releases of IBLRIG v8, for instance, are generally incompatible with IBLRIG v7.
The MINOR field will be incremented upon adding new, backwards compatible features.
The PATCH field will be incremented with each new, backwards compatible bugfix release that does not implement a new feature.

On the developer side, these 3 fields are manually controlled by, both

adjusting the variable __version__ in iblrig/__init__.py, and
adding the corresponding version string to a commit as a git tag, for instance:
git tag 8.8.4
git push origin --tags

The version string displayed by IBLRIG may include additional fields, such as in “8.24.7.post3+dirty”. Here,

post3 indicates the third unversioned commit after the latest versioned release, and
dirty indicates the presence of uncommited changes in your local repository of IBLRIG.

Both of these fields are automatically inferred (by means of git describe) and do not require manual interaction from the developer.

Package Management and Development Workflows with PDM

We use PDM to manage dependencies of IBLRIG. PDM can also be used to run various commands with relevance to the development process without having to activate a virtual environment first. Please refer to PDM’s documentation for help with installing PDM.

Installing Developer Dependencies

To install additional dependencies needed for working on IBLRIG’s code-base, run:

pdm sync -d

Running Unit Tests

To run unit tests locally, run:

pdm run pytest

This will also generate a HTML based coverage report which can be found in the htmlcov directory.

Linting & Formatting

We use Ruff for linting and formatting our code-base in close accordance with the Black code style.

To lint your code, run:

pdm run ruff check

Appending the flag --fix to the above command will automatically fix issues that are deemed safe to handle.

To reformat your code according to the Black code style run:

pdm run ruff format

Appending the flag --check to the above command will check your code for formatting issues without applying any changes. Refer to Ruff Formater’s documentation for further details.

pre-commit

IBLRIG v8 supports pre-commit hooks. Install pre-commit according to the official guide to enable automated code-checks on commits.

Release Checklist

update CHANGELOG.md including changes from the last tag
Pull request to iblrigv8dev
Check CI and eventually wet lab test
Pull request to iblrigv8
Merge PR
git tag the release in accordance to the version number below (after merge!)

Building the documentation

To build the documentation, run:

pdm run sphinx-autobuild ./docs/source ./docs/build

You can also export the documentation to a PDF file:

pdm run make -C docs/ simplepdf

Find the exported PDF file in docs/build/simplepdf.

Contribute to the documentation

To write the documentation:

Write the documentation in the iblrig/docs/source folder
If you are writing in a new file, add it to the index.rst so it appears in the table of content
Push all your changes to the iblrigv8dev branch; if this branch does not exist, create it first

To release the documentation onto the website:

Wait for the next release, or
Manually trigger the GitHub action by clicking “Run Workflow” (select iblrigv8dev) here