6.1. Contributing

6.1.1. How to contribute

If you’re willing to help, there are several ways to do it:

  • Use PyMoDAQ and report bug or issues using github issue tracker

  • Talk about PyMoDAQ to your colleagues

  • Cite PyMoDAQ in your papers

  • Add your instruments in plugins (see Instrument Plugins)

  • Work on new features, on solving bugs or issues

For the last point, here are some pointers:

You should fork and clone the up-to-date GitHub repo: https://github.com/PyMoDAQ/PyMoDAQ using git command line or GitHub Desktop (the latter is recommended for newcomers, just make sure to uncheck “Copy the … branch only”). Then create a dedicated branch name from the change you want to work on (using git).

Finally it is advised to create a dedicated virtual environment for this and install PyMoDAQ’s package as a developer. For example, using mamba as an environment manager:

  • mamba create -n dev_env

  • mamba activate dev_env

  • cd to the location of the folder where you downloaded or cloned the repository.

  • install the package as a developer with test tools using the command either by using the provided script python install-packages.py -d.

    • it calls pip install -e on each pymodaq package (pymodaq_utils, pymodaq_data, pymodaq_gui and pymodaq) in the package folder.

    • the -e option tells pip to install the package in editable mode, meaning that any change done to the source will be reported to the installed package.

    • the -d option activates [dev] in the package names transmitted to pip install (e.g. pymodaq_utils[dev]). It indicate to install the package alongside its optional dependancies, declared as dev in the pyproject.toml file.

Note

The install-packages.py script also provides a -u/--up-to {pymodaq_utils,pymodaq_data,pymodaq_gui,pymodaq} optional argument.

When provided, only the necessary packages “up to” the specified ones are installed; e.g. -u pymodaq_data will install pymodaq_utils and pymodaq_data but skip pymodaq_gui and PyMoDAQ packages.

When not provided, it will install all the packages (equivalent to -u pymodaq)

Then any change on the code will be seen by python interpreter so that you can see and test your modifications. Think about writing tests that will make sure your code is sound and that modification elsewhere doesn’t change the expected behavior.

It also requires the installation of a QT backend and some system packages on Linux, like explained in the installation tips page of the documentation.

When ready, you can create a pull request from your code into the proper branch, as discussed in the next section.

6.1.2. Branch structure and release cycle

There are several branches of the PyMoDAQ repository, directly linked to the release cycle of PyMoDAQ, which we define here. PyMoDAQ versioning follows usual practice, as described in this link:

https://upload.wikimedia.org/wikipedia/commons/8/82/Semver.jpg

Starting from November 2025, the following structure was agreed upon by the contributors. At any given time, there is a stable version of PyMoDAQ - at the time of writing it is 5.1.0 - which is not to be modified except for bugfixes, and a development version (he next minor version), onto which new features may be added.

The release cycle is illustrated in this figure:

../_images/release_cycle_pymodaq.svg

This cycle makes use of several types of branches:

Code flow branches:

  • the stable branch, eg: ‘5.1.x’ This is the branch representing the stable version of PyMoDAQ. No change should be made on this branch except bugfixes and hotfixes (see below). This is the branch from which the official releases are created, for instance version 5.1.0, 5.1.1, 5.1.2, etc. Only packages with modifications will be part of a bugfix release. For example, if the current version is 5.1.0, all packaged are at version 5.1.0. Then, pymodaq_data and pymodaq_utils are modified and a new bugfix version is released, then pymodaq_utils and pymodaq_data 5.1.1 will be released and pymodaq_gui and pymodaq will stay at 5.1.0.

  • the development branch: ‘dev Note that the branch name will always be dev. This is the development branch. It is ahead of the main branch, in the sense that it contains more recent commits than the main branch. It is thus the future state of the code. This is where the last developments of the code of PyMoDAQ are pushed. When the developers are happy with the state of this branch, typically when they finished to develop a new functionality and they tested it, this will lead to a new release of all four packages (5.1.x -> 5.2.0 in our example). In practice, the branch will stay dev but a 5.2.x branch will be created based on the last state of dev

Temporary branches:

  • Feature, eg: ‘feature/new_colors’: Any additional feature should be done on a feature branch. They are created based on the current development branch. When the feature is complete, a Pull Request must be open to integrate the changes into the development branch.

  • Bugfix, eg: ‘bugfix/remove_annoying_message’: These branches are meant to correct small issues. It can be created based on either the stable or development branch, depending on where the bug is located. Regardless, any bugfix must then be applied to all branches, if applicable (see note below).

  • Hotfix, eg: ‘hotfix/fix_huge_bug’: This is similar to a bugfix, but for more important bugs. More precisely, hotfixes are important enough that when applied, they will trigger an immediate new release (e.g. 5.1.1 -> 5.1.2) that incorporate the fix. At the contrary bugfixes can wait for a future release.

Note

Applying fixes across several branches

Let’s consider the case where a bug is found on the stable branch. We create a new branch to fix it, open a pull request into the stable branch, and wait for it to be accepted. However, it is likely that the buggy code is also part of the development version, requiring another pull request on that branch! Thus, but when a bug is found, one should always remember to check if it is present on several branches.

6.1.3. Where to contribute

There are easy places where to contribute and some more obscure places… After a few years of code rewriting/enhancing, several places are available for easily adding functionalities. These places are implementing one form or another of the Factory Pattern. For other places, you’ll have to read the API documentation :-)

6.1.3.1. Factory Patterns (to be completed)

6.1.3.1.1. Data Exporting

New Exporting data format from the H5Browser is made easy see pymodaq/utils/h5modules/exporters

6.1.3.1.2. Math functions in ROI

6.1.3.1.3. Scanning modes

6.1.4. Contributors

Here is a list of the main contributors:

6.1.4.1. Main modules

6.1.4.1.1. Functionalities

  • Sébastien Weber, Research Engineer at CEMES/CNRS

  • David Bresteau, Research Engineer at Attolab facility, CEA Saclay

  • Nicolas Tappy, Engineer at Attolight (https://attolight.com/)

6.1.4.1.2. Cleaning

  • Sébastien Weber, Research Engineer at CEMES/CNRS

  • David Trémouilles, Researcher at LAAS/CNRS

6.1.4.2. Plugins

  • Sébastien Weber, Research Engineer at CEMES/CNRS

  • Sophie Meuret, Researcher at CEMES/CNRS

  • David Bresteau, Research Engineer at Attolab facility, CEA Saclay

  • and many others…

6.1.4.3. Extensions

  • Sébastien Weber, Research Engineer at CEMES/CNRS

  • Romain Geneaux, Researcher at CEA Saclay contributed to the PyMoDAQ-Femto extension

6.1.4.4. Documentation

  • Sébastien Weber, Research Engineer at CEMES/CNRS

  • Matthieu Cabos helped with this documentation

  • David Bresteau wrote the documentation of the PID extension and the tutorial: Story of an instrument plugin development

6.1.4.5. Testing

  • Sébastien Weber, Research Engineer at CEMES/CNRS

  • Pierre Jannot wrote tests with a total of 5000 lines of code tested during his internship at CEMES in 2021

Note

If you’re not in the list and contributed somehow, sorry for that and let us know at sebastien.weber@cemes.fr