contributing.md

Contributing guide

Please refer to the contribution guide from the spatialdata repository.

Testing the correctness of the plots

Many tests will produce plots and check that they are correct by comparing them with a previously saved and serialized version of the same plots. The ground truth images are located in tests/_images. Different OS/versions may produce similar but not identical plots (for instance the ticks/padding could vary). To take into account for this please consider the following:

• you should not use locally generated plots as ground truth images, but you should commit images that have been generated by a GitHub Action. The recommended workflow is to go to the "actions" page for the repo, download the artifacts, and upload them as ground truth (after having reviewed them).
• the ground truth images need to be updated when a new test is passing, or when a test starts producing a slightly different (but consistent) plot.
• please never replace the ground truth images without having manually reviewed them.
• if you run the tests locally in macOS or Windows they will likely fail because the ground truth images are generated using Ubuntu. To overcome this you can use act, which will generate a Docker reproducing the environment used in the GitHub Action. After the Docker container is generated you can use it within IDEs to run tests and debug code.
• in the case of PyCharm, it is easier to create a container from a Dockerfile instead of using act. Please in such case use the Dockerfile made available in the repository. In this thread you can find extra details, and the process is shown in this Loom recording.
• If you encountering problems with act or docker, please get in touch with the developers via Zulip and we will help troubleshoot the issue.