Development

Requirements

While not strictly required we assume that you installed

just and
uv

in the description below.

Install

You can use the instructions below, if you want to work on the code of the ICOtronic package, i.e. add additional features or fix bugs.

Clone the repository to a directory of your choice. You can either use the command line tool git:
```
git clone https://github.com/MyTooliT/ICOtronic.git
```
or one of the many available graphical user interfaces for Git to do that.
Install ICOtronic with uv
1. Change your working directory to the (root) directory of the cloned repository
2. Install ICOtronic:
```
just setup
```
  Notes:
  - The command above will install the package in a virtual environment.
  - You need to prefix commands, such as icon with the command uv run (e.g. uv run icon) to execute it in this virtual environment.
  - Using uv run will only work in the root folder of the repository (that contains pyproject.toml).
Install other required tools (for tests)
- hdf5: For the command line tool h5dump (Linux/macOS). You can install hdf5 via Homebrew:
```
brew install hdf5
```

Style

Please use the guidelines from PEP 8. For code formatting we currently use Black, which should format code according to PEP 8 by default.

To format the whole code base you can use the following command in the root of the repository:

uv black .

For development we recommend that you use a tool or plugin that reformats your code with Black every time you save. This way we can ensure that we use a consistent style for the whole code base.

Tests

The following text describes some of the measures we should take to keep the software stable:

Please only push your changes to the main branch, if you think there are no new bugs or regressions. The main branch should always contain a working version of the software.
Please always run the automatic test (just run) for every supported OS (Linux, macOS, Windows) before you push to the main branch.

Code Checks

Flake8

We check the code with Flake8. Please use the following command in the root of the repository to make sure you did not add any code that introduces warnings:

uv run flake8

mypy

To check the type hint in the code base we use the static code checker mypy. Please use the following command in the root of the repository to check the code base for type problems:

uv run mypy icotronic

Pylint

We currently use Pylint to check the code:

uv run pylint .

Automatic Tests

Usage

Please run the following command in the root of the repository:

uv run pytest -v

and make sure that it reports no test failures.

Manual Tests

The text below specifies the manual test that should be executed before we release a new version of the ICOtronic package. Please note that the tests assume that you more or less use the default configuration values.

Check the Performance of the Library

Open your favorite terminal application and change your working directory to the root of the repository
Remove HDF5 files from the repository:
```
rm *.hdf5
```
Note: You can ignore errors about “no matches for wildcard” on Linux and macOS. This message just tells you that there is no file with the extension hdf5 in the current directory.
Check that no HDF5 files exist in the repository. The following command should not produce any output:
```
ls *.hdf5
```
Give your test STH the name “Test-STH”
Run the following command
```
uv run icon measure -t 300 -n Test-STH
```
- The command should not print any error messages.
- The data loss must be below 1 %.
Check that the repo now contains a HDF5 (*.hdf5) file
```
ls *.hdf5
```
Open the file in HDFView
Check that the timestamp of the last value in the acceleration table has approximately the value 30 000 000 (all values above 29 900 000 should be fine).

Combined Checks & Tests

While you need to execute some test for the ICOtronic package manually, other tests and checks can be automated. To run all automated checks and tests use the following just command:

just

Release

Check that the CI jobs for the main branch finished successfully
Check that the most recent “Read the Docs” build of the documentation ran successfully
Check that the checks and tests run without any problems on Linux, macOS and Windows. To do that execute them command:
```
just
```
in the root of the repository
Execute the manual tests in Windows and check that everything works as expected.
Update the release notes:
1. Open the release notes for the latest version
2. Replace links with a permanent version:
  
  For example instead of
  - ../../something.txt use
  - https://github.com/MyTooliT/ICOtronic/blob/REVISION/something.txt,
  where REVISION is the latest version of the main branch (e.g. 8568893f for version 1.0.5)
3. Commit your changes
Change the version number and commit your changes (please replace <VERSION> with the version number e.g. 1.0.5):
```
just release <VERSION>
```
Note: GitHub Actions will publish a package based on the tagged commit and upload it to PyPi.
Create a new release here
1. Insert the version number (e.g. 1.0.5) into the tag field
2. For the release title use “Version ”, where <VERSION> specifies the version number (e.g. “Version 1.0.5”)
3. Paste the release notes for the lastest release into the main text field
4. Click on “Publish Release”
Note: Alternatively you can also use the gh command:
```
gh release create
```
to create the release notes.
Close the milestone for the latest release number