From 8cd15a3404a5aebbf655c02f7d3e69443f581e4c Mon Sep 17 00:00:00 2001
From: Albert Salim <albertlimca@gmail.com>
Date: Sat, 20 Oct 2018 21:26:16 +0800
Subject: [PATCH] doc: Update doc for image templates

Updated docker documentation to use `image_templates`.
Added documentation on publishing to multiple registries
using `image_templates`
Added deprecation notices on `docker.image` and `docker.tag_templates`
---
 www/content/deprecations.md | 50 +++++++++++++++++++++++++++-
 www/content/docker.md       | 66 ++++++++++++++++++++++++-------------
 2 files changed, 93 insertions(+), 23 deletions(-)

diff --git a/www/content/deprecations.md b/www/content/deprecations.md
index aac54bddf..2b28d586e 100644
--- a/www/content/deprecations.md
+++ b/www/content/deprecations.md
@@ -11,7 +11,55 @@ Deprecate code will be removed after ~6 months from the time it was deprecated.
 
 # Active deprecation notices
 
-No active deprecation notices at this time.
+## docker.image
+
+> since 2018-10-20
+
+This property was deprecated in favor of more flexible `image_templates`.
+The idea is to be able to define several images and tags using templates instead of just one image with tag templates.
+This flexibility allows images to be pushed to multiple registries.
+
+Change this:
+
+```yaml
+dockers:
+- image: foo/bar
+  tag_templates:
+    - '{{ .Tag }}'
+```
+
+to this:
+
+```yaml
+dockers:
+- image_templates:
+    - 'foo/bar:{{ .Tag }}'
+```
+
+## docker.tag_templates
+
+> since 2018-10-20
+
+This property was deprecated in favor of more flexible `image_templates`.
+The idea is to be able to define several images and tags using templates instead of just one image with tag templates.
+
+Change this:
+
+```yaml
+dockers:
+- image: foo/bar
+  tag_templates:
+    - '{{ .Tag }}'
+```
+
+to this:
+
+```yaml
+dockers:
+- image_templates:
+    - 'foo/bar:{{ .Tag }}'
+```
+
 
 <!--
 
diff --git a/www/content/docker.md b/www/content/docker.md
index 962adaf80..c77bb0230 100644
--- a/www/content/docker.md
+++ b/www/content/docker.md
@@ -17,9 +17,12 @@ If you have only one `build` setup,
 the configuration is as easy as adding the
 name of your image to your `.goreleaser.yml` file:
 
+The docker image declaration supports templating. Learn more about the [name template engine](/templates).
+
 ```yaml
 dockers:
-  - image: user/repo
+  - image_templates:
+    - user/repo
 ```
 
 You also need to create a `Dockerfile` in your project's root folder:
@@ -53,23 +56,18 @@ dockers:
     goarm: ''
     # Name of the built binary that should be used.
     binary: mybinary
-    # Template of the Docker image name.
-    image: myuser/myimage
-    # Publish to additional registries.
-    additional_registries:
-    - "gcr.io"
-    - "localhost:5000"
+    # Templates of the Docker image names.
+    image_templates:
+    - "myuser/myimage:latest"
+    - "myuser/myimage:{{ .Tag }}"
+    - "myuser/myimage:{{ .Tag }}-{{ .Env.GO_VERSION }}"
+    - "myuser/myimage:v{{ .Major }}"
+    - "gcr.io/myuser/myimage:latest"
     # Skips the docker push. Could be useful if you also do draft releases.
     # Defaults to false.
     skip_push: false
     # Path to the Dockerfile (from the project root).
     dockerfile: Dockerfile 
-    # Template of the docker tag. Defaults to `{{ .Version }}`.
-    tag_templates:
-    - "{{ .Tag }}"
-    - "{{ .Tag }}-{{ .Env.GO_VERSION }}"
-    - "v{{ .Major }}"
-    - latest
     # Template of the docker build flags.
     build_flag_templates:
     - "--label=org.label-schema.schema-version=1.0"
@@ -99,7 +97,8 @@ project: foo
 dockers:
   -
     binary: mybinary
-    image: myuser/{{.ProjectName}}
+    image_templates:
+    - "myuser/{{.ProjectName}}"
 ```
 
 This will build and public the following images:
@@ -112,19 +111,18 @@ This will build and public the following images:
 
 Some users might want to when version to push docker tags `:v1`, `:v1.6`,
 `:v1.6.4` and `:latest` when `v1.6.4` (for example) is built. That can be
-accomplished by using multiple `tag_templates`:
+accomplished by using multiple `image_templates`:
 
 ```yaml
 # .goreleaser.yml
 dockers:
   -
     binary: mybinary
-    image: myuser/myimage
-    tag_templates:
-    - "{{ .Tag }}"
-    - "v{{ .Major }}"
-    - "v{{ .Major }}.{{ .Minor }}"
-    - latest
+    image_templates:
+    - "myuser/myimage:{{ .Tag }}"
+    - "myuser/myimage:v{{ .Major }}"
+    - "myuser/myimage:v{{ .Major }}.{{ .Minor }}"
+    - "myuser/myimage:latest"
 ```
 
 This will build and publish the following images:
@@ -139,6 +137,29 @@ with multiple tags.
 
 > Learn more about the [name template engine](/templates).
 
+## Publishing to multiple docker registries
+
+Some users might want to push images to multiple docker registries. That can be
+accomplished by using multiple `image_templates`:
+
+```yaml
+# .goreleaser.yml
+dockers:
+  -
+    binary: mybinary
+    image_templates:
+    - "docker.io/myuser/myimage:{{ .Tag }}"
+    - "docker.io/myuser/myimage:latest"
+    - "gcr.io/myuser/myimage:{{ .Tag }}"
+    - "gcr.io/myuser/myimage:latest"
+```
+
+This will build and publish the following images to `docker.io` and `gcr.io`:
+
+- `myuser/myimage:v1.6.4`
+- `myuser/myimage:latest`
+
+
 ## Applying docker build flags
 
 Build flags can be applied using `build_flag_templates`. The flags must be
@@ -149,7 +170,8 @@ valid docker build flags.
 dockers:
   -
     binary: mybinary
-    image: myuser/myimage
+    image_templates:
+        - "myuser/myimage"
     build_flag_templates:
     - "--label=org.label-schema.schema-version=1.0"
     - "--label=org.label-schema.version={{.Version}}"