Merge pull request #2339 from technosophos/docs/2234-hook-weight-clarification

docs(chart_hooks): clarify hook execution order

docs/charts_hooks.md

@@ -79,8 +79,13 @@ 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,
+resources are declared in a hook, the resources are executed serially. If they
-but the order of their execution is not guaranteed.
+have hook weights (see below), they are executed in weighted order. Otherwise,
+ordering is not guaranteed. (In Helm 2.3.0 and after, they are sorted
+alphabetically. That behavior, though, is not considered binding and could change
+in the future.) It is considered good practice to add a hook weight, and set it
+to `0` if weight is not important.
+
 
 ### Hook resources are unmanaged
 
@@ -157,12 +162,15 @@ 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.
 
-It is also possible to define a weight for a hook which will help build a deterministic executing order. Weights are defined using the following annotation:
+It is also possible to define a weight for a hook which will help build a
+deterministic executing order. Weights are defined using the following annotation:
 
 ```
   annotations:
     "helm.sh/hook-weight": "5"
 ```
 
-Hook weights can be positive or negative numbers but must be represented as strings. When Tiller starts the execution cycle of hooks of a particular Kind it will sort those hooks in ascending order. 
+Hook weights can be positive or negative numbers but must be represented as
+strings. When Tiller starts the execution cycle of hooks of a particular Kind it
+will sort those hooks in ascending order.