[Fix #2144] Create a docker image to mimic the TravisCI environment (#2145)

1 files changed, 66 insertions, 0 deletions

diff --git a/doc/hacking_on_cider.md b/doc/hacking_on_cider.md
index 11c4e80f..c778a536 100644
--- a/doc/hacking_on_cider.md
+++ b/doc/hacking_on_cider.md
@@ -77,6 +77,72 @@ You can also check for the presence of byte-compilation warnings in batch mode:
 $ make test-bytecomp
 ```
 
+#### Running the tests in Travis CI
+
+If you prefer to see the full Travis test suite run successfully, the easiest
+way to achieve that is to create your own personal account on
+https://travis-ci.org. View your profile details on the Travis site, and toggle
+the switch to enable builds on your fork of the cider project.
+
+Subsequent pushes to your fork will generate a Travis build you can monitor for
+success or failure.
+
+#### Simulating the Travis tests locally in Docker
+
+If you prefer not to wait for Travis all the time, or if you need to debug
+something that fails in Travis but does not fail for you on your own machine,
+then you can also run the Travis tests manually in Docker.
+
+You will need to run some scripts to build and launch the Docker image.
+
+To build:
+```
+$ docker/build.sh
+```
+
+The build script uses a base image provided by the engineers at Travis. Note: the
+Travis docker image is currently more than 8GB, so be prepared with a good
+internet connection and time to spare.
+
+The resulting docker image is tagged simply `cider-travis`. You can run this
+image by hand, but there is a convenience script available:
+```
+$ docker/run.sh
+```
+
+This script launches a docker container and bind-mounts your cider project
+directory as `/home/travis/cider` such that you can instantly see any code
+changes reflected inside the docker environment.
+
+For instance, you can run tests on emacs 25.3
+```
+(emacs-25.3-travis) ~/cider$ make test
+```
+
+and then switch to emacs 26 and test again
+
+```
+(emacs-25.3-travis) ~/cider$ evm use emacs-26-pretest-travis
+(emacs-26-pretest-travis) ~/cider$ cask install
+(emacs-26-pretest-travis) ~/cider$ make test
+```
+
+You can test byte compilation too
+```
+(emacs-26-pretest-travis) ~/cider$ make test-bytecomp
+```
+
+When you are done working in docker, just `exit` the bash prompt, and the docker
+container will also exit. Note that `docker/run.sh` runs the container with
+`--rm`, meaning any changes to the docker container are discarded when the
+container exits.
+
+So for example, by default, the docker image pre-installs only the most recent
+releases of emacs 25, emacs 26, and a recent snapshot of the emacs git
+repository. The `evm` tool is available should you need to install some other
+specific build. However additional versions of emacs will be discarded when
+you exit the docker container.
+
 ## Hacking on cider-nrepl
 
 ### Obtaining the code