Document HelmRelease desired state transitions

This documents what is considered a desired state transition, and
the resulting upgrade and status condition semantics.

docs/spec/v2alpha1/helmreleases.md

@@ -7,10 +7,10 @@ action trigger configuration, individual action configuration, and statusing.
 
 ## Helm release placement
 
-The namespace/name in which to deploy the helm release defaults to the namespace/name of the
+The namespace/name in which to deploy the Helm release defaults to the namespace/name of the
 `HelmRelease`. These can be overridden respectively via `spec.targetNamespace` and
 `spec.releaseName`. If `spec.targetNamespace` is set, `spec.releaseName` defaults to
-`<spec.targetNamespace>-<HelmRelease name>`.
+`<spec.targetNamespace>-<metadata.name>`.
 
 ## Helm chart template
 
@@ -29,7 +29,7 @@ Supported source types:
 * [Bucket](https://github.com/fluxcd/source-controller/blob/master/docs/spec/v1alpha1/buckets.md)
 
 The `HelmChart` is created in the same namespace as the `sourceRef`,
-with a name of `<HelmRelease namespace>-<HelmRelease name>`.
+with a name matching the `HelmRelease` `<metadata.namespace>-<metadata.name>`.
 
 The `chart.spec.chart` can either contain:
 
@@ -60,8 +60,8 @@ spec:
   - kind: Secret
     name: prod-tls-values
     valuesKey: crt
-	targetPath: tls.crt
-	optional: true
+    targetPath: tls.crt
+    optional: true
 ```
 
 The definition of the listed keys for items in `spec.valuesFrom` is as follows:
@@ -90,25 +90,33 @@ The definition of the listed keys for items in `spec.valuesFrom` is as follows:
 
 ## Reconciliation
 
-If a helm release with the matching namespace/name is not found it will be installed, otherwise
-it will be upgraded.
+If no Helm release with the matching namespace/name is found it will be installed. It will
+be upgraded any time new state is found which consists of:
 
-The timeout for any individual Kubernetes operation (like Jobs for hooks) during the performance
-of helm actions can be configured via `spec.timeout` and can be overridden per action
-via `spec.<action>.timeout`.
+* `spec` (and thus `metadata.generation`)
+* Latest `HelmChart` revision available
+* Latest Helm release revision, in case it was not made by the helm-controller and thus may not
+  match the desired state.
+* [`ConfigMap` and `Secret` values overrides](#values-overrides). Changes to these do not trigger an
+  immediate reconciliation, but will be handled upon the next reconciliation. This is to avoid
+  a large number of upgrades occuring when multiple resources are updated.
 
 The `spec.interval` tells the reconciler at which interval to reconcile the release. The
 interval time units are `s`, `m` and `h` e.g. `interval: 5m`, the minimum value should be 60 seconds.
 
-The reconcilation can be suspended by setting `spec.susped` to `true`.
-
 The reconciler can be told to reconcile the `HelmRelease` outside of the specified interval
 by annotating the object with a `fluxcd.io/reconcileAt` annotation. For example:
 
 ```bash
 kubectl annotate --overwrite helmrelease/podinfo fluxcd.io/reconcileAt="$(date +%s)"
 ```
 
+Reconcilation can be suspended by setting `spec.susped` to `true`.
+
+The timeout for any individual Kubernetes operation (like Jobs for hooks) during the performance
+of Helm actions can be configured via `spec.timeout` and can be overridden per action
+via `spec.<action>.timeout`.
+
 ### Disabling resource waiting
 
 For install, upgrade, and rollback actions resource waiting is enabled by default,
@@ -276,7 +284,7 @@ to true if at least one retry is configured.
 
 When the controller completes a reconciliation, it reports the result in the status sub-resource.
 
-The following `status.condtions` types are supported:
+The following `status.condtions` types are supported. Here, "state" is as detailed in [reconciliation](#reconciliation):
 
 ```go
 const (