add documentation how to compare Dockerfiles created between current and oder version of r2d

Author: nuest

.gitignore

@@ -33,3 +33,5 @@ test_file_text.txt
 
 
 \.vscode/
+
+tests/dockerfile_diff.sh

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

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.