Doccument records overwriting in the manual.
@@ -23,7 +23,7 @@ If you have to merge with fields in commons, you will use two new concepts:
- default annotation,
- overwriting,
-## Default annotation.
+## Default annotation
To be able to merge records with commons fields, at least one side field has to
be annotated as default. It means, if you have two records:
@@ -64,3 +64,36 @@ So, this value can be changed afterward. Saying it in a more abstract way,
default indicate a smaller priority to a field in case of merging. Saying that,
If both side would have been annotated `default`, the merge is not possible
neither.
+
+## Overwriting
+
+The overwriting is the concept specifying the behaviour of a merge when you
+overwrite a field on which depend an otherone. This feature is described in
+["#573 [RFC] Merge types and terms syntax proposal"](https://github.com/tweag/nickel/pull/573)
+in more details.
+
+Here, we will simply explain what appen in the following case:
+We have a record with some fields annotated `default` and others depending on
+these ones. An exemple could be:
+
+```text
+let security = {
+ firewall.open_proto.http | default = true,
+ firewall.open_proto.https | default = true,
+ firewall.open_proto.ftp | default = true,
+ firewall.open_ports = []
+ @ (if firewall.open_proto.ftp then [21] else [])
+ @ (if firewall.open_proto.http then [80] else [])
+ @ (if firewall.open_proto.https then [443] else []),
+} in // security => {firewall.open_ports = [21, 80, 443]
+security & {firewall.open_proto.ftp = false} // => {firewall.open_ports = [80, 443]
+```
+
+We then see that depending fields are updated when you overwrite the fields they
+depend on.
+
+## A word about contracts
+
+To simplify, when merging two records, all contracts of both left and right one
+are applied to the resulting one.
+TODO: detail and write exemples.
