Add versioning to images

.travis.yml

@@ -5,11 +5,12 @@ language: python
 
 env:
   global:
+    - IMAGE_NAME=praekeltfoundation/django-bootstrap
     - REGISTRY_USER=praekeltorgdeploy
     - secure: "UK7h5cBSPlsL1bPJx+S7ArYKHIUjEWfsITw8M/ObTLaIQHMq2uV3J/D7K5GFkqJFX9sUGmFZBkCu1J9JwpieO1Ew79B2/g4i0aDDmhIuE+IOo5tQ6jinAmP1NEVrCvk1LUTdXwk46VbUCGNxYpv44ge1zwhRrtNpMxaIqXsSYLOXjA7p7A/IghDRYDsRIjz6TfXNKcw+qWxzUTSUjLqgcZqezvI3c9VRRgD94vKh9KpLryVtSPxGjUQTKD6cfu6Yvbz6TzVGp6QCEM9ysRdRJx0ecsP39XBj8VVnqI34ux+4sqiwdqM7SQTlaKFJK+o6dMAX5ZEkA9jQw2kWDX0Pg60zHX+vbH1vycPVaQ6ln9J68pNZx6AMFbJpDkTacrmStH9uIuH6+pN4j4gNsT4TkwtFJDcRuGI0gShqBgQVVHhGuCECfj6RZQ7K35NsQVHXQy47AkwGODu3xUwAuiMOeQVR2rEYCBnJfx+qLY5hIsPzR4MhidLPSZa5T520uhp+35pVAk95DYYEL+6N2C3wIOmtEl6gZNC1P0IgCDuTOU/u5+TCaS5C7M3aWk26SL+n3JnFeCAgLr+OYntHwW9PIen70OG1bokGdxQZ00DvF9veyQz+6IGVEG1Cm5MZv6Cp9bqgpGYMRhKBEAJyKrT+slt6ah10+eIJbT7p4HIgKBM="
   matrix:
-    - VARIANT=py2 PYTHON_VERSION=2.7 TAG_LATEST=1
-    - VARIANT=py3 PYTHON_VERSION=3.6 TAG_LATEST=
+    - VARIANT=py2 PYTHON_VERSION=2.7 TAG_DEFAULT=1
+    - VARIANT=py3 PYTHON_VERSION=3.6 TAG_DEFAULT=
 
 # Update Docker Engine and Compose
 before_install:
@@ -19,7 +20,7 @@ before_install:
 install: []
 
 before_script:
-  - image="praekeltfoundation/django-bootstrap:$VARIANT"
+  - image="$IMAGE_NAME:$VARIANT"
   # Fetch existing image to use as cache
   - docker pull "$image"
 script:
@@ -34,7 +35,15 @@ before_deploy:
   - pip install docker-ci-deploy==0.3.0
   - docker login -u "$REGISTRY_USER" -p "$REGISTRY_PASS"
 deploy:
-  provider: script
-  script: dcd --version "$VARIANT" ${TAG_LATEST:+--version-latest} -- "$image"
-  on:
-    branch: develop
+  # On develop branch, tag with (e.g.) develop-py3, debd419-develop-py3...
+  # Then tag default variant with develop, develop-py2, debd419-develop, debd419-develop-py2
+  - provider: script
+    script: dcd --tag develop-"$VARIANT" ${TAG_DEFAULT:+develop} --version "$(git rev-parse --short HEAD)" --version-latest "$image"
+    on:
+      branch: develop
+  # On tags, tag with (e.g.) py3, 1.0.1-py3, 1.0-py3, 1-py3...
+  # Then tag default variant with latest, py2, 1.0.1, 1.0.1-py2, 1.0, 1.0-py2, 1, 1-py2
+  - provider: script
+    script: dcd --tag "$VARIANT" ${TAG_DEFAULT:+''} --version "$TRAVIS_TAG" --version-latest --version-semver "$image"
+    on:
+      tags: true

CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+## 1.0.0 - Unreleased
+* Initial versioned release.

README.md

@@ -1,6 +1,7 @@
 # docker-django-bootstrap
 
 [![Docker Pulls](https://img.shields.io/docker/pulls/praekeltfoundation/django-bootstrap.svg?style=flat-square)](https://hub.docker.com/r/praekeltfoundation/django-bootstrap/)
+[![GitHub tag](https://img.shields.io/github/tag/praekeltfoundation/docker-django-bootstrap.svg?style=flat-square)](https://github.com/praekeltfoundation/docker-django-bootstrap/tags)
 [![Travis branch](https://img.shields.io/travis/praekeltfoundation/docker-django-bootstrap/develop.svg?style=flat-square)](https://travis-ci.org/praekeltfoundation/docker-django-bootstrap)
 [![Requires.io](https://img.shields.io/requires/github/praekeltfoundation/docker-django-bootstrap.svg?style=flat-square)](https://requires.io/github/praekeltfoundation/docker-django-bootstrap/requirements/?branch=develop)
 
@@ -48,7 +49,7 @@ You'll probably want to make your Django settings file *Docker-friendly* so that
 #### Step 2: Write a Dockerfile
 In the root of the repo for your Django project, add a Dockerfile for the project. For example, this file could contain:
 ```dockerfile
-FROM praekeltfoundation/django-bootstrap
+FROM praekeltfoundation/django-bootstrap:1-py2
 
 COPY . /app
 RUN pip install -e .
@@ -104,6 +105,24 @@ CMD ["django-admin", "runserver"]
 
 If the entrypoint script sees a command for `gunicorn` then it will run all bootstrapping processes (database migration, starting Nginx, etc.). Otherwise, the script will execute the command directly. A special case is Celery, which is described next.
 
+## Tags
+The following tags are available:
+* `<version>-py2`, `py2`: These tags are built with Python 2.7.
+* `<version>-py3`, `py3`: These tags are built with Python 3.6.
+* `<version>`, `latest`: These tags track the Python 2.7 images.
+
+### Versioning
+This Docker image uses semantic versioning, following the [tagging guidelines](https://github.com/docker-library/official-images#tags-and-aliases) in the Docker "Official Images" repository. This means that releases are tagged with the full version as well as each major version. So, for example, the `1.0.0` release is tagged with `1.0.0`, `1.0`, and `1`. When a newer `1.0.x` version is released, that will replace the `1.0` and `1` tags, and so on.
+
+Note that, unlike how Docker images are usually versioned, this version is for the Docker image itself, not the software that the image contains. This means that for a given full version tag (e.g. `1.0.0`), that tag _will not ever change_ to point to a new Docker image.
+
+Sometimes there are changes to the image that could break compatibility with existing images based on this one. If you want to ensure compatibility use a specific version or major version when building on this image. For example:
+```dockerfile
+FROM praekeltfoundation/django-bootstrap:1-py3
+```
+
+Note that only the latest versions are actively maintained. So if, for example, we were to move to version `2.0.0`, the `1.x.x` releases are unlikely to receive updates or fixes. The versioning exists primarily to avoid breakage when a Docker tag is updated to point to a new image.
+
 ## Celery
 It's common for Django applications to have [Celery](http://docs.celeryproject.org/en/latest/django/first-steps-with-django.html) workers performing tasks alongside the actual website. Using this image, there are 2 different ways to run Celery: