Initialize data version control for managing test images

.dvc/.gitignore

@@ -0,0 +1,3 @@
+/config.local
+/tmp
+/cache

.dvc/config

@@ -0,0 +1,4 @@
+[core]
+    remote = upstream
+['remote "upstream"']
+    url = https://dagshub.com/GenericMappingTools/pygmt.dvc

.dvcignore

@@ -0,0 +1,3 @@
+# Add patterns of files dvc should ignore, which could improve
+# the performance. Learn more at
+# https://dvc.org/doc/user-guide/dvcignore

.github/workflows/ci_tests.yaml

@@ -108,6 +108,13 @@ jobs:
           touch ~/.gmt/server/gmt_data_server.txt ~/.gmt/server/gmt_hash_server.txt
           ls -lhR ~/.gmt
 
+      # Install data version control (dvc) and pull data from dvc remote
+      - name: Install dvc and pull data from dvc remote
+        run: |
+          pip install dvc
+          dvc pull
+          ls -lhR pygmt/
+
       # Install the package that we want to test
       - name: Install the package
         run: |

CONTRIBUTING.md

@@ -423,7 +423,74 @@ If it's correct, copy it (and only it) to `pygmt/tests/baseline`.
 When you run `make test` the next time, your test should be executed and
 passing.
 
-Don't forget to commit the baseline image as well.
+Don't forget to commit the baseline image as well!
+The images should be pushed up into a remote repository using `dvc` (instead of
+`git`) as will be explained in the next section.
+
+#### Using data version control ([dvc](https://dvc.org)) to manage test images
+
+As the baseline images are quite large blob files that can change often (e.g.
+with new GMT versions), it is not ideal to store them in `git` (which is meant
+for tracking plain text files). Instead, we will use [`dvc`](https://dvc.org)
+which is like `git` but for data. What `dvc` does is to store the hash (md5sum)
+of a file. For example, given an image file like `test_logo.png`, `dvc` will
+generate a `test_logo.png.dvc` plain text file containing the hash of the
+image. This `test_logo.png.dvc` file can be stored as usual on GitHub, while
+the `test_logo.png` file can be stored separately on our `dvc` remote at
+https://dagshub.com/GenericMappingTools/pygmt.
+
+To **pull** or sync files from the `dvc` remote to your local repository, use
+the commands below. Note how `dvc` commands are very similar to `git`.
+
+    dvc status  # should report any files 'not_in_cache'
+    dvc pull  # pull down files from DVC remote cache (fetch + checkout)
+
+Once the sync/download is complete, you should notice two things. There will be
+images stored in the `pygmt/tests/baseline` folder (e.g. `test_logo.png`) and
+these images are technically reflinks/symlinks/copies of the files under the
+`.dvc/cache` folder. You can now run the image comparison test suite as per
+usual.
+
+    pytest pygmt/tests/test_logo.py  # run only one test
+    make test  # run the entire test suite
+
+To **push** or sync changes from your local repository up to the `dvc` remote
+at DAGsHub, you will first need to set up authentication using the commands
+below. This only needs to be done once, i.e. the first time you contribute a
+test image to the PyGMT project.
+
+    dvc remote modify upstream --local auth basic
+    dvc remote modify upstream --local user "$DAGSHUB_USER"
+    dvc remote modify upstream --local password "$DAGSHUB_PASS"
+
+The configuration will be stored inside your `.dvc/config.local` file. Note
+that the $DAGSHUB_PASS token can be generated at
+https://dagshub.com/user/settings/tokens after creating a DAGsHub account
+(can be linked to your GitHub account). Once you have an account set up, please
+ask one of the PyGMT maintainers to add you as a collaborator at
+https://dagshub.com/GenericMappingTools/pygmt/settings/collaboration before
+proceeding with the next steps.
+
+The entire workflow for generating or modifying baseline test images can be
+summarized as follows:
+
+    # Sync with git and dvc remote
+    git pull
+    dvc pull
+
+    # Generate new baseline images
+    pytest --mpl-generate-path=baseline pygmt/tests/test_logo.py
+    mv baseline/*.png pygmt/tests/baseline/
+
+    # Generate hash for baseline image and stage the *.dvc file in git
+    dvc add pygmt/tests/baseline/test_logo.png
+    git rm -r --cached 'pygmt/tests/baseline/test_logo.png'  # optional
+    git add pygmt/tests/baseline/test_logo.png.dvc
+
+    # Commit changes and push to both the dvc and git remote
+    git commit -m "Add test_logo.png into DVC"
+    dvc push --remote upstream
+    git push
 
 ### Documentation
 

environment.yml

@@ -17,6 +17,7 @@ dependencies:
     - codecov
     - coverage[toml]
     - docformatter
+    # - dvc
     - flake8
     - ipython
     - isort>=5

pygmt/tests/baseline/.gitignore

@@ -0,0 +1 @@
+/test_*.png

pygmt/tests/baseline/test_logo.png.dvc

@@ -0,0 +1,4 @@
+outs:
+- md5: 905d5b9f0f8d8b809899dfe9e87d0e91
+  size: 33347
+  path: test_logo.png

pygmt/tests/baseline/test_logo_on_a_map.png.dvc

@@ -0,0 +1,4 @@
+outs:
+- md5: 25854f87e4e6f4c30be71bc08a3d430c
+  size: 114522
+  path: test_logo_on_a_map.png

pygmt/tests/test_logo.py

@@ -1,34 +1,26 @@
 """
 Tests for fig.logo.
 """
+import pytest
 from pygmt import Figure
-from pygmt.helpers.testing import check_figures_equal
 
 
-@check_figures_equal()
+@pytest.mark.mpl_image_compare
 def test_logo():
     """
     Plot a GMT logo of a 2 inch width as a stand-alone plot.
     """
-    fig_ref, fig_test = Figure(), Figure()
-    # Use single-character arguments for the reference image
-    fig_ref.logo(D="x0/0+w2i")
-    fig_test.logo(position="x0/0+w2i")
-    return fig_ref, fig_test
+    fig = Figure()
+    fig.logo(position="x0/0+w2i")
+    return fig
 
 
-@check_figures_equal()
+@pytest.mark.mpl_image_compare
 def test_logo_on_a_map():
     """
     Plot a GMT logo in the upper right corner of a map.
     """
-    fig_ref, fig_test = Figure(), Figure()
-    # Use single-character arguments for the reference image
-    fig_ref.coast(R="-90/-70/0/20", J="M6i", G="chocolate", B="")
-    fig_ref.logo(D="jTR+o0.1i/0.1i+w3i", F="")
-
-    fig_test.coast(
-        region=[-90, -70, 0, 20], projection="M6i", land="chocolate", frame=True
-    )
-    fig_test.logo(position="jTR+o0.1i/0.1i+w3i", box=True)
-    return fig_ref, fig_test
+    fig = Figure()
+    fig.coast(region=[-90, -70, 0, 20], projection="M6i", land="chocolate", frame=True)
+    fig.logo(position="jTR+o0.1i/0.1i+w3i", box=True)
+    return fig