From 4e50f4b7244b34faefda4e0a19c07616f96885f0 Mon Sep 17 00:00:00 2001 From: LucaMarconato <2664412+LucaMarconato@users.noreply.github.com> Date: Fri, 20 Dec 2024 19:57:16 +0100 Subject: [PATCH 1/3] Update contributing.md --- docs/contributing.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/contributing.md b/docs/contributing.md index 77e97aae..983c2543 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -78,6 +78,14 @@ out to the developers of the dependency before the package is released to a wide [scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests +### 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](https://github.com/scverse/spatialdata-plot/actions/workflows/test.yaml), 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. + ## Publishing a release ### Updating the version number From 04673dfd800a362d9d175bbf614fbcf12d713e7e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 20 Dec 2024 18:58:14 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/contributing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing.md b/docs/contributing.md index 983c2543..178d4ce9 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -81,6 +81,7 @@ out to the developers of the dependency before the package is released to a wide ### 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](https://github.com/scverse/spatialdata-plot/actions/workflows/test.yaml), 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. From 46b0172cb56a83290e186945ac0537ee597b9d83 Mon Sep 17 00:00:00 2001 From: LucaMarconato <2664412+LucaMarconato@users.noreply.github.com> Date: Mon, 23 Dec 2024 14:55:24 +0100 Subject: [PATCH 3/3] Add PyCharm Dockerfile instructions to contributing guide --- docs/contributing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing.md b/docs/contributing.md index 178d4ce9..35e59ac8 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -86,6 +86,7 @@ Many tests will produce plots and check that they are correct by comparing 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 availabel in the repository. If you encountering problems with `act` or `docker`, please [get in touch with the developers via Zulip](https://scverse.zulipchat.com/#narrow/channel/443514-spatialdata-dev) and we will help troubleshoot the issue. See also additional details [here](https://github.com/scverse/spatialdata-plot/pull/397). ## Publishing a release