From 5876439ea7c7ba8daa0353dd77fd0b3ce0621082 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20N=C3=BCst?= <daniel.nuest@uni-muenster.de>
Date: Sat, 7 Sep 2019 16:35:45 +0200
Subject: [PATCH] add documentation how to compare Dockerfiles created between
 current and oder version of r2d

---
 .gitignore                               |  2 +
 docs/source/contributing/contributing.md |  2 +-
 docs/source/contributing/tasks.md        | 55 ++++++++++++++++++++++++
 3 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index bbd850df..31b06b9a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,3 +33,5 @@ test_file_text.txt
 
 
 \.vscode/
+
+tests/dockerfile_diff.sh
diff --git a/docs/source/contributing/contributing.md b/docs/source/contributing/contributing.md
index ca9413d6..2f61d13c 100644
--- a/docs/source/contributing/contributing.md
+++ b/docs/source/contributing/contributing.md
@@ -202,7 +202,7 @@ Then you are good to go!
 If you only changed the documentation, you can also build the documentation locally using `sphinx` .
 
 ```bash
-#pip install -r docs/doc-requirements.txt
+pip install -r docs/doc-requirements.txt
 
 cd docs/
 make html
diff --git a/docs/source/contributing/tasks.md b/docs/source/contributing/tasks.md
index b216f58d..06acd9e1 100644
--- a/docs/source/contributing/tasks.md
+++ b/docs/source/contributing/tasks.md
@@ -202,3 +202,58 @@ same syntax to update the Pipfile and viceversa.
 
 At the moment this has to be done manually so please make sure to update both
 files accordingly.
+
+# Uncommon tasks
+
+## Compare generated Dockerfiles between repo2docker versions
+
+For larger refactorings it can be useful to check that the generated Dockerfiles match
+between an older version of r2d and the current version. The following shell script 
+automates this test.
+
+```bash
+#! /bin/bash -e
+
+current_version=$(jupyter-repo2docker --version | sed s@+@-@)
+echo "Comparing $(pwd) (local $current_version vs. $R2D_COMPARE_TO)"
+basename="dockerfilediff"
+
+diff_r2d_dockerfiles_with_version () {
+    docker run --rm -t -v "$(pwd)":"$(pwd)" --user 1000 jupyter/repo2docker:"$1" jupyter-repo2docker --no-build --debug "$(pwd)" &> "$basename"."$1"
+    jupyter-repo2docker --no-build --debug "$(pwd)" &> "$basename"."$current_version"
+    
+    # remove first line logging the path
+    sed -i '/^\[Repo2Docker\]/d' "$basename"."$1"
+    sed -i '/^\[Repo2Docker\]/d' "$basename"."$current_version"
+
+    diff --strip-trailing-cr "$basename"."$1" "$basename"."$current_version" | colordiff
+    rm "$basename"."$current_version" "$basename"."$1"
+}
+
+startdir="$(pwd)"
+cd "$1"
+
+#diff_r2d_dockerfiles 0.10.0-22.g4f428c3.dirty
+diff_r2d_dockerfiles_with_version "$R2D_COMPARE_TO"
+
+cd "$startdir"
+```
+
+Put the code above in a file `tests/dockerfile_diff.sh` and make it executable: `chmod +x dockerfile_diff.sh`.
+
+Configure the repo2docker version you want to compare with your local version in the environment variable `R2D_COMPARE_TO`.
+The scripts takes one input: the directory where repo2docker should be executed.
+
+```bash
+cd tests/
+R2D_COMPARE_TO=0.10.0 ./dockerfile_diff.sh venv/py35/
+```
+
+Run it for all directories where there is a `verify` file:
+
+```bash
+cd tests/
+R2D_COMPARE_TO=0.10.0 CMD=$(pwd)/dockerfile_diff.sh find . -name 'verify' -execdir bash -c '$CMD $(pwd)' \;
+```
+
+To keep the created Dockefilers for further inspection, comment out the deletion line in the script.