Add details about the merge strategies to the Kpt book (#2145)

* Add details about the merge strategies to the Kpt book

* Addressed comments

* Addressed more comments

* Addressed comments

* Moved content to reference docs

Author: mortent

site/reference/cli/pkg/update/README.md

@@ -94,3 +94,129 @@ $ kpt pkg update my-package-dir/@master --strategy fast-forward
 ```
 
 <!--mdtogo-->
+
+### Details
+
+#### Resource-merge strategy
+
+The resource-merge strategy performs a structural comparison of each resource using the
+OpenAPI schema. So rather than performing a text-based merge, kpt leverages the
+common structure of KRM resources.
+
+##### Resource identity
+In order to perform a per-resource merge, kpt needs to be able to match a resource in
+the local package with the same resource in the upstream version of the package. It does
+this matching based on the identity of a resource, which is the combination of group,
+kind, name and namespace. So in our wordpress example, the identity of the`Deployment`
+resource is:
+```
+group: apps
+kind: Deployment
+name: wordpress
+namespace: ""
+```
+Changing the name and/or namespace of a resource is a pretty common way to customize
+a package. In order to make sure this doesn't create problems during merge, kpt will
+automatically adding the `# kpt-merge: <namespace>/<name>` comment on the `metadata`
+field of every resource when getting or updating a package. An example is the `Deployment`
+resource from the wordpress package:
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata: # kpt-merge: /wordpress
+  name: wordpress
+  labels:
+    app: wordpress
+...
+```
+
+##### Merge rules
+kpt performs a 3-way merge for every resource. This means it will use the resource
+in the local package, the updated resource from upstream, as well as the resource
+at the version where the local and upstream package diverged (i.e.
+common ancestor). When discussing the merge rules in detail, we will be referring to
+the three different sources as local, upstream and origin.
+
+In the discussion, we will be referring to non-associative and associative lists. A
+non-associative list either has elements that are scalars or another list, or it has elements
+that are mappings but without an associative key. An example of this in the kubernetes
+API is the `command` property on containers:
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod
+spec:
+  containers:
+    - name: hello
+      image: busybox
+      command: ['sh', '-c', 'echo "Hello, World!"]
+```
+
+An associative list has elements that are mappings and
+one or more of the fields in the mappings are designated as associative keys. An associative key
+(also sometimes referred to as a merge key) is used to identify the "same" elements in two
+different lists for the purpose of merging them. An example from the kubernetes API
+is the list of containers in a pod which uses the `name` property as the merge key:
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod
+spec:
+  containers:
+    - name: web
+      image: nginx
+    - name: sidecar
+      image: log-collector
+```
+
+kpt will primarily look for information about
+any associative keys from the OpenAPI schema, but some fields are also automatically recognized as
+associative keys:
+* `mountPath`
+* `devicePath`
+* `ip`
+* `type`
+* `topologyKey`
+* `name`
+* `containerPort`
+
+The 3-way merge algorithm operates both on the level of each resource and on
+each individual field with a resource. 
+
+On the resource level, the rules are:
+
+* A resource present in origin and deleted from upstream will be deleted from local.
+* A resource missing from origin and added in upstream will be added to local.
+* A resource only in local will be kept without changes.
+* A resource in both upstream and local will be merged into local.
+
+On the field level, the rules differ based on the type of field.
+
+For scalars and non-associative lists:
+* If the field is present in either upstream or local and the value is `null`, remove the field from local.
+* If the field is unchanged between upstream and local, leave the local value unchanged.
+* If the field has been changed in both upstream and local, update local with the value from upstream.
+
+For mappings:
+* If the field is present in either upstream or local and the value is `null`, remove the field from local.
+* If the field is present only in local, leave the local value unchanged.
+* If the field is not present in local, add the delta between origin and upstream as the value in local.
+* If the field is present in both upstream and local, recursively merge the values between local, upstream and origin.
+
+For associative lists:
+* If the field is present in either upstream or local and the value is `null`, remove the field from local.
+* If the field is present only in local, leave the local value unchanged.
+* If the field is not present in local, add the delta between origin and upstream as the value in local.
+* If the field is present in both upstream and local, recursively merge the values between local, upstream and origin.
+
+#### Fast-forward strategy
+
+The fast-forward strategy updates a local package with the changes from upstream, but will
+fail if the local package has been modified since it was fetched.
+
+#### Force-delete-replace strategy
+
+The force-delete-replace strategy updates a local package with changes from upstream, but will
+wipe out any modifications to the local package.