Start specifiying our plans for stability in repo2docker versions
MODIFY
docs/source/design.md
docs/source/design.md
@@ -31,6 +31,27 @@ This provides a few advantages:
multiple repositories, enabling better use of the Docker build cache. This
also provides massive performance advantages.
+## Reproducibility and version stability
+
+Many ingredients go into making an image from a repository:
+
+1. version of the base docker image
+1. version of `repo2docker` itself
+1. versions of the libraries installed by the repository
+
+`repo2docker` controls the first two, the user controls the third one. The current
+policy for the version of the base image is that we will keep pace with Ubuntu
+releases until we reach the next release with Long Term Support (LTS). We
+currently use Artful Aardvark (17.10) and the next LTS version will be
+Bionic Beaver (18.04).
+
+The version of `repo2docker` used to build an image can influence which packages
+are installed by default and which features are supported during the build
+process. We will periodically update those packages to keep step with releases
+of jupyter notebook, jupyterlab, etc. For packages that are installed by
+default but where you want to control the version we recommend you specify them
+explicitly in your dependencies.
+
## Unix principles "do one thing well"
`repo2docker` should do one thing, and do it well. This one thing is:

Start specifiying our plans for stability in repo2docker versions