Merge pull request #3076 from joanrieu/template-docs

docs(templates): fix misleading/broken examples

docs/chart_template_guide/builtin_objects.md

@@ -27,7 +27,7 @@ In the previous section, we use `{{.Release.Name}}` to insert the name of a rele
   - `Capabilities.TillerVersion` provides a way to look up the Tiller version. It has the following values: `SemVer`, `GitCommit`, and `GitTreeState`.
 - `Template`: Contains information about the current template that is being executed
   - `Name`: A namespaced filepath to the current template (e.g. `mychart/templates/mytemplate.yaml`)
-  - `BasePath`: The namespaced path to the templates directory of the current chart (e.g. `mychart/templates`). This can be used to [include template files](https://github.com/kubernetes/helm/blob/master/docs/charts_tips_and_tricks.md#automatically-roll-deployments-when-configmaps-or-secrets-change)
+  - `BasePath`: The namespaced path to the templates directory of the current chart (e.g. `mychart/templates`).
 
 The values are available to any top-level template. As we will see later, this does not necessarily mean that they will be available _everywhere_.
 

docs/charts_tips_and_tricks.md

@@ -18,11 +18,11 @@ We also added two special template functions: `include` and `required`. The `inc
 function allows you to bring in another template, and then pass the results to other
 template functions.
 
-For example, this template snippet includes a template called `mytpl.tpl`, then
+For example, this template snippet includes a template called `mytpl`, then
 lowercases the result, then wraps that in double quotes.
 
 ```yaml
-value: {{include "mytpl.tpl" . | lower | quote}}
+value: {{include "mytpl" . | lower | quote}}
 ```
 
 The `required` function allows you to declare a particular
@@ -134,9 +134,8 @@ be updated with a subsequent `helm upgrade`, but if the
 deployment spec itself didn't change the application keeps running
 with the old configuration resulting in an inconsistent deployment.
 
-The `sha256sum` function can be used together with the `include`
+The `sha256sum` function can be used to ensure a deployment's
-function to ensure a deployments template section is updated if another
+annotation section is updated if another file changes: 
-spec changes: 
 
 ```yaml
 kind: Deployment
@@ -144,10 +143,13 @@ spec:
   template:
     metadata:
       annotations:
-        checksum/config: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
+        checksum/config: {{ .Files.Get "path/to/config" | sha256sum }}
 [...]
 ```
 
+See also the `helm upgrade --recreate-pods` flag for a slightly
+different way of addressing this issue.
+
 ## Tell Tiller Not To Delete a Resource
 
 Sometimes there are resources that should not be deleted when Helm runs a