Add more info about when build cache is invalidated/used - Issue #3636

Plus some edits as suggested by @jamtur01

Closes #3636

Signed-off-by: Doug Davis <dug@us.ibm.com>

docs/sources/articles/dockerfile_best-practices.md

@@ -75,6 +75,43 @@ Here’s an example from the [`buildpack-deps` image](https://github.com/docker-
       mercurial \
       subversion
 
+### Build Cache
+
+During the process of building an image Docker will step through the
+instructions in your `Dockerfile` executing each in the order specified.
+As each instruction is examined Docker will look for an existing image in its
+cache that it can reuse, rather than creating a new (duplicate) image.
+If you do not want to use the cache at all you can use the ` --no-cache=true`
+option on the `docker build` command.
+
+However, if you do let Docker use its cache then it is very important to
+understand when it will, and will not, find a matching image. The basic rules
+that Docker will follow are outlined below:
+
+* Starting with a base image that is already in the cache, the next
+instruction is compared against all child images derived from that base
+image to see if one of them was built using the exact same instruction. If
+not, the cache is invalidated.
+
+* In most cases simply comparing the instruction in the `Dockerfile` with one
+of the child images is sufficient.  However, certain instructions require
+a little more examination and explanation.
+
+* In the case of the `ADD` and `COPY` instructions, the contents of the file(s)
+being put into the image are examined. Specifically, a checksum is done
+of the file(s) and then that checksum is used during the cache lookup.
+If anything has changed in the file(s), including its metadata,
+then the cache is invalidated.
+
+* Aside from the `ADD` and `COPY` commands cache checking will not look at the
+files in the container to determine a cache match. For example, when processing
+a `RUN apt-get -y update` command the files updated in the container
+will not be examined to determine if a cache hit exists.  In that case just
+the command string itself will be used to find a match.
+
+Once the cache is invalidated, all subsequent `Dockerfile` commands will
+generate new images and the cache will not be used.
+
 ## The `Dockerfile` instructions
 
 This section contains specific recommendations for the correct usage of the
@@ -336,4 +373,5 @@ These Official Repos have exemplary `Dockerfile`s:
 * [Dockerfile Reference](https://docs.docker.com/reference/builder/#onbuild)
 * [More about Base Images](https://docs.docker.com/articles/baseimages/)
 * [More about Automated Builds](https://docs.docker.com/docker-hub/builds/)
-* [Guidelines for Creating Official Repositories](https://docs.docker.com/docker-hub/official_repos/)
+* [Guidelines for Creating Official 
+Repositories](https://docs.docker.com/docker-hub/official_repos/)

docs/sources/reference/builder.md

@@ -13,8 +13,8 @@ successively.
 
 This page discusses the specifics of all the instructions you can use in your
 `Dockerfile`. To further help you write a clear, readable, maintainable
-`Dockerfile`, we've also written a [`Dockerfile` Best Practices guide](/articles/dockerfile_best-practices).
+`Dockerfile`, we've also written a [`Dockerfile` Best Practices
-
+guide](/articles/dockerfile_best-practices).
 
 ## Usage
 
@@ -60,7 +60,9 @@ to be created - so `RUN cd /tmp` will not have any effect on the next
 instructions.
 
 Whenever possible, Docker will re-use the intermediate images,
-accelerating `docker build` significantly (indicated by `Using cache`):
+accelerating `docker build` significantly (indicated by `Using cache` -
+see the [`Dockerfile` Best Practices
+guide](/articles/dockerfile_best-practices/#build-cache) for more information):
 
     $ sudo docker build -t SvenDowideit/ambassador .
     Uploading context 10.24 kB
@@ -192,10 +194,13 @@ commands using a base image that does not contain `/bin/sh`.
 > you must use double-quotes (") around words not single-quotes (').
 
 The cache for `RUN` instructions isn't invalidated automatically during
-the next build. The cache for an instruction like `RUN apt-get
+the next build. The cache for an instruction like 
-dist-upgrade -y` will be reused during the next build.  The cache for
+`RUN apt-get dist-upgrade -y` will be reused during the next build.  The 
-`RUN` instructions can be invalidated by using the `--no-cache` flag,
+cache for `RUN` instructions can be invalidated by using the `--no-cache` 
-for example `docker build --no-cache`.
+flag, for example `docker build --no-cache`.
+
+See the [`Dockerfile` Best Practices
+guide](/articles/dockerfile_best-practices/#build-cache) for more information.
 
 The cache for `RUN` instructions can be invalidated by `ADD` instructions. See
 [below](#add) for details.
@@ -325,6 +330,9 @@ have permissions of 600.
 > The first encountered `ADD` instruction will invalidate the cache for all
 > following instructions from the Dockerfile if the contents of `<src>` have
 > changed. This includes invalidating the cache for `RUN` instructions.
+> See the [`Dockerfile` Best Practices
+guide](/articles/dockerfile_best-practices/#build-cache) for more information.
+
 
 The copy obeys the following rules: