From ff3289abe96ecfc623f534a743e132c7d2de66fb Mon Sep 17 00:00:00 2001
From: Dane Springmeyer <dane@mapbox.com>
Date: Thu, 30 Apr 2015 08:11:53 -0700
Subject: [PATCH] add details about how tests+submodules work - refs #2789
 [skip ci]

---
 Makefile                   |  5 ++++-
 docs/contributing.markdown | 21 +++++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 70ec91400..c4d76c2e3 100755
--- a/Makefile
+++ b/Makefile
@@ -58,7 +58,10 @@ rebuild:
 uninstall:
 	@$(PYTHON) scons/scons.py -j$(JOBS) --config=cache --implicit-cache --max-drift=1 uninstall
 
-test:
+test/data:
+	git submodule update --init
+
+test: ./test/data
 	@./test/run
 
 check: test
diff --git a/docs/contributing.markdown b/docs/contributing.markdown
index 74c6c2ebf..bfe0a0ec5 100644
--- a/docs/contributing.markdown
+++ b/docs/contributing.markdown
@@ -1,5 +1,26 @@
 # Contributing
 
+## Testing
+
+Developers adding new features or fixing bugs should always write tests alongside.
+
+Mapnik has both C++ unit tests in `./test/unit` and visual tests in `./test/visual`.
+
+Test data for the unit and visual tests is pulled in from standalone repos via git submodules.
+
+After building Mapnik (see INSTALL.md), the submodules can be loaded and the tests can be run like:
+
+    make test
+
+Developers with commit access can update test data like:
+
+    cd test/data
+    git remote set-url origin git@github.com:mapnik/test-data
+    git commit -a -m "update test data"
+    git push origin HEAD:master
+    cd ../../
+    git commit test/data -m "update test-data submodule"
+
 ## Community
 
 Mapnik is a creative community focused on making beautiful maps with beautiful software.