From 88a1e7b572e0924928229c9e694ee8da963c4b7e Mon Sep 17 00:00:00 2001
From: Greg Parsons <gregorskii@gmail.com>
Date: Mon, 23 Jan 2017 15:19:56 -0800
Subject: [PATCH] adds readme section for changes

---
 website/source/docs/builders/docker.html.md | 52 +++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/website/source/docs/builders/docker.html.md b/website/source/docs/builders/docker.html.md
index 81e6f32bd..f802823d0 100644
--- a/website/source/docs/builders/docker.html.md
+++ b/website/source/docs/builders/docker.html.md
@@ -56,6 +56,58 @@ more easily tagged, pushed, etc.
 }
 ```
 
+## Basic Example: Changes to Metadata
+
+Below is an example using the changes argument of the builder. This feature allows the source images metadata to be changed when committed back into the Docker environment. It is derived from the `docker commit --change` command line [option to Docker](https://docs.docker.com/engine/reference/commandline/commit/).
+
+Example uses of all of the options, assuming one is building an NGINX image from ubuntu as an simple example:
+
+```
+{
+	"type": "docker",
+	"image": "ubuntu",
+	"commit": true,
+	"changes": [
+		"USER www-data",
+		"WORKDIR /var/www",
+		"ENV HOSTNAME www.example.com",
+		"VOLUME /test1 /test2",
+		"EXPOSE 80 443",
+		"CMD [\"nginx\", \"-g\", \"daemon off;\"]",
+		"MAINTAINER Captain Kirk",
+		"ENTRYPOINT /var/www/start.sh"
+	]
+}
+```
+
+Allowed metadata fields that can be changed are:
+
+- CMD
+	- String, supports both array (escaped) and string form
+	- EX: `”CMD [\"nginx\", \"-g\", \"daemon off;\"]"`
+	- EX: `"CMD nginx -g daemon off;”`
+- ENTRYPOINT
+	- String 
+	- EX: `“ENTRYPOINT /var/www/start.sh”`
+- ENV
+	- String, note there is no equal sign: 
+	- EX: `“ENV HOSTNAME www.example.com”` not `“ENV HOSTNAME=www.example.com”`
+- EXPOSE
+	- String, space separated ports 
+	- EX: `“EXPOSE 80 443”`
+- MAINTAINER
+	- String 
+	- EX: `“MAINTAINER NAME”`
+- USER
+	- String 
+	- EX: `“USER USERNAME”`
+- VOLUME
+	- String 
+	- EX: `“VOLUME FROM TO“`
+- WORKDIR
+	- String
+	- EX: `“WORKDIR PATH”`
+
 ## Configuration Reference
 
 Configuration options are organized below into two categories: required and