We welcome your contributions! Please see the provided steps below and never hesitate to contact us.
If you are a new user, we recommend checking out the detailed Github Docs.
We use issues to track bug reports, feature requests, and user questions. Please use the suggested template when creating a new issue to receive the most relevant feedback.
Changes to pycro-manager
need to be proposed in a pull request (PR) to the main
branch. Please follow the GitHub documentation on Contributing to projects for instructions on how to fork the repository, make changes, and create a pull request to contribute to the repo.
Please reference open issues that can be addressed by your PR. Please include a description of the bug fix or new feature implemented in the PR.
pycro-manager
can be installed in editable mode to allow you to test the changes you have made. We recommend using an environment management tool such as Conda.
Create a new conda environment with
conda create -n pycro-manager
conda activate pycro-manager
Navigate to the repo directory and install the package in editable mode, along with all of the developer tools
pip install -e ".[dev]"
Each commit you make must have a GitHub-registered email
as the author
. You can read more here.
To set it, use
git config --global user.email your-address@example.com
Make sure your fork stays up-to-date with the latest changes in the main repo by syncing your fork.
We use the pytest framework to test the code. During development, you can run the tests locally using
# in the project root directory
pytest -v
You may also execute the tests in an IDE such as PyCharm or VSCode. You may chose to run individual tests or all tests in a module or package using the IDE tools.
The suite of tests runs automatically using GitHub Actions for every PR. All tests must pass before a PR is merged. Please contribute new tests as you fix bugs and develop new features.
Execution of the pycro-manager
tests depends on Micro-manager and several Java libraries (AcqEngJ, NDTiffStorage, NDViewer).
During setup, pytest
will download the latest nightly build of Micro-manager
and install it in ~/Micro-Manager-nightly
; this step will be skipped if that folder exists. Currently installation of the latest Micro-manager
nightly build through pytest
is only supported on Windows platforms. For other platforms, please manually install a working version of Micro-manager
in ~/Micro-Manager-nightly
.
During setup, pytest
will also look for pre-compiled .jar
files in the ../../{java_lib_name}/target
directory (e.g. ../../{AcqEngJ}/target
) and replace the ones that are packaged with the Micro-manager
nightly build if they are older version. This is helpful when co-developing these libraries. The user does need to pre-compile the Java libraries first. When the tests run in GitHub Actions they always use with the .jar
files that are packaged with Micro-manager
.
Tests of the pycro-manager
NDViewer and napari
viewer only execute locally and are skipped by GitHub Actions. When making changes that may affect these viewer, please make sure to always run the tests locally.
- Add/edit files in the
docs/source
directory - Build a local copy by navigating to the
docs
and typingmake clean && make html
. Make sure there are no compilation errors - View the locally built version by opening the
docs/build/html/index.html
file Most web browsers will allow you to preview HTML pages. Try enteringfile:///absolute/path/to/pycro-manager/docs/build/html/index.html
in your address bar.
If you have questions, comments, suggestions for improvement, or any other inquiries regarding the project, feel free to open an issue.
Issues and pull-requests are written in Markdown. You can find a comprehensive guide here.