From 84c7139e4d814555ea173354f43a36015f688fe7 Mon Sep 17 00:00:00 2001
From: Stephen Tallowitz <stephen.tallowitz@petzi.ch>
Date: Wed, 24 Apr 2019 21:02:32 +0200
Subject: [PATCH] Update readme to explain versioning

---
 README.md | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 6004c0e..92faab7 100644
--- a/README.md
+++ b/README.md
@@ -4,21 +4,40 @@ This is a Docker image containing pre-commit.
 
 ## Goal
 
-This image provides a base to create derived images containing specific pre-commit tools. It is based on Ubuntu, which should increase the chance that a derived image can simply use the package manager to install a required package.
+This image provides a base to create derived images containing specific pre-commit tools. Currently, it is based on Ubuntu. This should increase the chance that a derived image can simply use the package manager to install a required package.
 
 Example derived image Dockerfile:
 
 ```
-FROM petzi/pre-commit:1.15.2-ubuntu.18.10
+FROM petzi/pre-commit:1.15.2
 RUN apt-get install -y --no-install-recommends \
     yamllint
 ```
 
 ## Versioning
 
+### Git
+
 The project uses semantic versioning.
 
 1. The main version number denotes the pre-commit version used.
-1. The pre-release part denotes the base docker image used. Codenames of the distributions are not used, as version numbers of the distributions are better suited to produce semver-like precedence. 
+1. The pre-release part refers to a revision used inside this repository.
+
+A git tag will typically look like this.
+
+```
+1.15.2-6
+```
+
+### Docker image tag
+
+This repository uses docker hub autobuild and derives many image tags from one build. A build from `1.15.2-6` will thus create the following tags:
+
+1. `1.15.2`
+1. `1.15.2-6`
+1. `1.15.2-ubuntu`
+1. `1.15.2-ubuntu-6`
+1. `1.15.2-ubuntu.18.10`
+1. `1.15.2-ubuntu.18.10-6`
 
-`1.15.2-ubuntu.18.10` is pre-commit version 1.15.2 built from Ubuntu 18.10 base image.
+Choosing the right version to base your derived image on depends on your need for stability. If you reliably need to depend on the correct version of Ubuntu, use a tag such as `1.15.2-ubuntu.18.10`. If you reliably need to depend on a certain revision from within this repository, but the operating system is irrelevant, us a tag such as `1.15.2-6`.