docs(*): refresh docs

This refreshes docs, as discussed in #719, and adds a few new sections
to the docs.

Closes #719

README.md

@@ -50,8 +50,11 @@ including installing pre-releases.
 - [Installing Helm](docs/install.md)
 - [Using Helm](docs/using_helm.md)
 - [Developing Charts](docs/charts.md)
+	- [Chart Lifecycle Hooks](docs/chart_hooks.md)
+	- [Chart Tips and Tricks](docs/chart_tips_and_tricks.md)
 	- [Chart Repository Guide](docs/chart_repository.md)
 	- [Syncing your Chart Repository](docs/chart_repository_sync_example.md)
+	- [Signing Charts](docs/provenance.md)
 - [Architecture](docs/architecture.md)
 - [Developers](docs/developers.md)
 - [History](docs/history.md)

docs/architecture.md

@@ -11,7 +11,7 @@ can do the following:
 - Package charts into chart archive (tgz) files
 - Interact with chart repositories where charts are stored
 - Install and uninstall charts into an existing Kubernetes cluster
-- Manage the releases of charts that have been installed with Helm
+- Manage the release cycle of charts that have been installed with Helm
 
 For Helm, there are three important concepts:
 
@@ -22,9 +22,6 @@ For Helm, there are three important concepts:
 3. A _release_ is a running instance of a _chart_, combined with a
    specific _config_.
 
-Following the formula made famous by the [12 Factor App](http://12factor.net/), _chart + config
-= release_.
-
 ## Components
 
 Helm has two major components:
@@ -64,20 +61,4 @@ communicate with Kubernetes. Currently, that library uses REST+JSON.
 The Tiller server stores information in ConfigMaps located inside of
 Kubernetes. It does not need its own database.
 
-### Structure of the Code
-
-The individual programs are located in `cmd/`. Shared libraries are
-stored in `pkg/`. The raw ProtoBuf files are stored in `_proto/hapi`
-(where `hapi` stands for the Helm Application Programming Interface).
-The Go files generated from the `proto` definitions are stored in
-`pkg/proto`.
-
-Docker images are built by cross-compiling Linux binaries and then
-building a Docker image from the files in `rootfs`.
-
-The `scripts/` directory contains a number of utility scripts. Most of these
-are used by the CI/CD pipeline.
-
-Go dependencies are managed with
-[Glide](https://github.com/Masterminds/glide) and stored in the
-`vendor/` directory.
+Configuration files are, when possible, written in YAML.

docs/charts.md

@@ -32,7 +32,8 @@ wordpress/
   templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes
 ```
 
-Helm will silently strip out any other files.
+Helm reserves use of the `charts/` and `templates/` directories, and of
+the listed file names. Other files will be left as they are.
 
 ## The Chart.yaml File
 
@@ -204,23 +205,26 @@ team.
 
 ## Templates and Values
 
-By default, Helm Chart templates are written in the Go template language, with the
-addition of 50 or so [add-on template
-functions](https://github.com/Masterminds/sprig). (In the future, Helm
-may support other template languages, like Python Jinja.)
+Helm Chart templates are written in the
+[Go template language](https://golang.org/pkg/text/template/), with the
+addition of 50 or so add-on template
+functions [from the Sprig library](https://github.com/Masterminds/sprig) and a
+few other [specialized functions](charts_tips_and_tricks.md).
 
 All template files are stored in a chart's `templates/` folder. When
 Helm renders the charts, it will pass every file in that directory
 through the template engine.
 
 Values for the templates are supplied two ways:
+
   - Chart developers may supply a file called `values.yaml` inside of a
     chart. This file can contain default values.
   - Chart users may supply a YAML file that contains values. This can be
     provided on the command line with `helm install`.
 
 When a user supplies custom values, these values will override the
 values in the chart's `values.yaml` file.
+
 ### Template Files
 
 Template files follow the standard conventions for writing Go templates
@@ -269,6 +273,9 @@ It can use the following four template values (usually defined in a
 All of these values are defined by the template author. Helm does not
 require or dictate parameters.
 
+To see many working charts, check out the [Kubernetes Charts
+project](https://github.com/kubernetes/charts)
+
 ### Predefined Values
 
 Values that are supplied via a `values.yaml` file (or via the `--set`
@@ -296,7 +303,8 @@ sensitive_.
 
 **NOTE:** Any unknown Chart.yaml fields will be dropped. They will not
 be accessible inside of the `Chart` object. Thus, Chart.yaml cannot be
-used to pass arbitrarily structured data into the template.
+used to pass arbitrarily structured data into the template. The values
+file can be used for that, though.
 
 ### Values files
 
@@ -342,6 +350,9 @@ Note that only the last field was overridden.
 `values.yaml`. But files specified on the command line can be named
 anything.
 
+**NOTE:** If the `--set` flag is used on `helm install` or `helm upgrade`, those
+values are simply converted to YAML on the client side.
+
 Any of these values are then accessible inside of templates using the
 `.Values` object:
 
@@ -479,157 +490,7 @@ standard references that will help you out.
 
 - [Go templates](https://godoc.org/text/template)
 - [Extra template functions](https://godoc.org/github.com/Masterminds/sprig)
-- [The YAML format]()
-
-## Hooks
-
-Helm provides a _hook_ mechanism to allow chart developers to intervene
-at certain points in a release's life cycle. For example, you can use
-hooks to:
-
-- Load a ConfigMap or Secret during install before any other charts are
-  loaded.
-- Execute a Job to backup up a database before installing a new chart,
-  and then execute a second job after the upgrade in order to restore
-  data.
-- Run a Job before deleting a release to gracefully take a service out
-  of rotation before removing it.
-
-Hooks work like regular templates, but they have special annotations
-that cause Helm to utilize them differently. In this section, we cover
-the basic usage pattern for hooks.
-
-### The Available Hooks
-
-The following hooks are defined:
-
-- pre-install: Executes after templates are rendered, but before any
-  resources are created in Kubernetes.
-- post-install: Executes after all resources are loaded into Kubernetes
-- pre-delete: Executes on a deletion request before any resources are
-  deleted from Kubernetes.
-- post-delete: Executes on a deletion request after all of the release's
-  resources have been deleted.
-- pre-upgrade: Executes on an upgrade request after templates are
-  rendered, but before any resources are loaded into Kubernetes (e.g.
-  before a kuberntes apply operation).
-- post-upgrade: Executes on an upgrade after all resources have been
-  upgraded.
-
-### Hooks and the Release Lifecycle
-
-Hooks allow you, the chart developer, an opportunity to perform
-operations at strategic points in a release lifecycle. For example,
-consider the lifecycle for a `helm install`. By default, the lifecycle
-looks like this:
-
-1. User runs `helm install foo`
-2. Chart is loaded into Tiller
-3. After some verification, Tiller renders the `foo` templates
-4. Tiller loads the resulting resources into Kubernetes
-5. Tiller returns the release name (and other data) to the client
-6. The client exits
-
-Helm defines two hooks for the `install` lifecycle: `pre-install` and
-`post-install`. If the developer of the `foo` chart implements both
-hooks, the lifecycle is altered like this:
-
-1. User runs `helm install foo`
-2. Chart is loaded into Tiller
-3. After some verification, Tiller renders the `foo` templates
-4. Tiller executes the `pre-install` hook (loading hook resources into
-   Kubernetes)
-5. Tiller waits until the hook is "Ready"
-6. Tiller loads the resulting resources into Kubernetes
-7. Tiller executes the `post-install` hook (loading hook resources)
-8. Tiller waits until the hook is "Ready"
-9. Tiller returns the release name (and other data) to the client
-10. The client exits
-
-What does it mean to wait until a hook is ready? This depends on the
-resource declared in the hook. If the resources is a `Job` kind, Tiller
-will wait until the job successfully runs to completion. And if the job
-fails, the release will fail. This is a _blocking operation_, so the
-Helm client will pause while the Job is run.
-
-For all other kinds, as soon as Kubernetes marks the resource as loaded
-(added or updated), the resource is considered "Ready". When many
-resources are declared in a hook, the resources are executed serially,
-but the order of their execution is not guaranteed.
-
-#### Hook resources are unmanaged
-
-The resources that a hook creates are not tracked or managed as part of the
-release. Once Tiller verifies that the hook has reached its ready state, it
-will leave the hook resource alone.
-
-Practically speaking, this means that if you create resources in a hook, you
-cannot rely upon `helm delete` to remove the resources. To destroy such
-resources, you need to write code to perform this operation in a `pre-delete`
-or `post-delete` hook.
-
-### Writing a Hook
-
-Hooks are just Kubernetes manfiest files with special annotations in the
-`metadata` section. Because they are template files, you can use all of
-the normal template features, including reading `.Values`, `.Release`,
-and `.Template`.
-
-For example, this template, stored in `templates/post-install-job.yaml`,
-declares a job to be run on `post-install`:
-
-```yaml
-apiVersion: batch/v1
-kind: Job
-metadata:
-  name: "{{.Release.Name}}"
-  labels:
-    heritage: {{.Release.Service | quote }}
-    release: {{.Release.Name | quote }}
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
-  annotations:
-    # This is what defines this resource as a hook. Without this line, the
-    # job is considered part of the release.
-    "helm.sh/hook": post-install
-spec:
-  template:
-    metadata:
-      name: "{{.Release.Name}}"
-      labels:
-        heritage: {{.Release.Service | quote }}
-        release: {{.Release.Name | quote }}
-        chart: "{{.Chart.Name}}-{{.Chart.Version}}"
-    spec:
-      restartPolicy: Never
-      containers:
-      - name: post-install-job
-        image: "alpine:3.3"
-        command: ["/bin/sleep","{{default "10" .Values.sleepyTime}}"]
-
-```
-
-What makes this template a hook is the annotation:
-
-```
-  annotations:
-    "helm.sh/hook": post-install
-```
-
-One resource can implement multiple hooks:
-
-```
-  annotations:
-    "helm.sh/hook": post-install,post-upgrade
-```
-
-Similarly, there is no limit to the number of different resources that
-may implement a given hook. For example, one could declare both a secret
-as a config map as a pre-install hook. It is important to keep in mind,
-though, that there are no ordering guarantees about hooks.
-
-When subcharts declare hooks, those are also evaluated. There is no way
-for a top-level chart to disable the hooks declared by subcharts. And
-again, there is no guaranteed ordering.
+- [The YAML format](http://yaml.org/spec/)
 
 ## Using Helm to Manage Charts