Contributing

We welcome contributions of all kinds — bug reports, feature requests, documentation improvements, and pull requests!

Branch strategy

Branch	Purpose
master	Stable, always-deployable code, tested on real hardware.
release/candidate-py12	Integration branch for new features and bugfixes.

We follow the GitHub Flow. We recommend GitHub Desktop for branch management.

Contributing a new feature

0. Fork the repository on GitHub.

1. Check out release/candidate-py12 and verify it works in demo mode and on your actual mesoSPIM.

2. Create a local branch from release/candidate-py12:

   git checkout -b dev-my-feature
   

3. Make your changes, write tests (see below), and commit.

4. Open a pull request back to release/candidate-py12. We review and merge it.

5. Once merged and stable, your branch can be deleted.

Stable releases from release/candidate-py12 are periodically merged into master after testing on several physical setups.

Reporting bugs

Please file a GitHub issue with:

• mesoSPIM-control version (or git commit hash)

• Python version and OS

• Relevant section of the log file from mesoSPIM/log/

• Steps to reproduce

Testing

Hardware-in-the-loop testing is hard to automate, so we rely on a two-step approach:

1. Demo mode — run the software with demo_config.py (no physical hardware).

2. Real hardware — test on an actual mesoSPIM setup.

Unit tests live in mesoSPIM/test/. Run them with:

pytest mesoSPIM/test/

Writing tests before implementing a feature (test-driven development) is encouraged but not required.

Sharing ideas

Have a feature idea or want to discuss the project? Head to the image.sc forum or open a GitHub discussion.

Github contains multiple tools that allow you to switch seamlessly between code versions, track changes, and collaborate efficiently. Initially it can be confusing, but it’s OK!

Branches

The master branch contains stable, always deployable code, well tested on actual hardware. We follow the Github worflow with the release/candidate-py12 being the branch where we test new features. We recommend using Github Desktop application for easy branch management.

Contributing new features

We welcome contributions of new features, bugfixes, and improvements from the community! It is recommended to use the release/candidate-py12 branch as a starting point for development.

Your workflow may look as follows:

0. Fork the repository.

1. Check out the release/candidate-py12 branch and see if it works in demo mode and on your actual mesoSPIM setup.

2. Create a local branch from release/candidate-py12 (e.g. dev-my-feature), and start experimenting with the code.

3. Once you are satisfied with your new feature, create a pull request back to the release/candidate-py12 branch, we will review and merge it.

4. After your commits were merged into release/candidate-py12, the code is stable, and you are done with my-feature branch, you can delete it. This will keep things tidy.

Stable releases from release/candidate-py12 will be merged into master once every few months after testing on several physical setups with multiple users. Often users are the ones who report bugs and issues, because they use the software in diverse real-world scenarios.

Reporting bugs and issues

If you find a bug or unexpected behavior, please report an issue! We will try to fix it or find another solution.

Testing, testing

Because mesoSPIM is a complex hardware-software-user system and often individually customized, it is quite difficult to run good tests that cover such diverse systems. So, be careful! Test the code fist in hardware-simulation mode (using demo_config.py file), then on real hardware, ideally with some sample.

Share you ideas and feature requests

If you have an idea or feature request that can significantly improve mesosPIM user experience - share it in Forum. We can implement it!

Enjoy!

Any contribution is welcome, and tinkering with mesoSPIM is fun. So, enjoy it!