Documentation regarding conflicts is added.
@@ -130,3 +130,17 @@ c = d.getParent(); // preferred way to fetch the pa
this is that Oak internally uses various classes from the `nio` package that implement
`InterruptibleChannel`, which are [asynchronously closed](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/channels/InterruptibleChannel.html)
when receiving an `InterruptedException` while blocked on IO. See [OAK-2609](https://issues.apache.org/jira/browse/OAK-2609).
+
+### Avoid or minimize conflicts
+To reduce the possiblity of having errors like `OakState0001: Unresolved conflicts in ...`:
+
+1. Make sure you always release the session by calling session.logout(). If possible, avoid long-running sessions. If they are required (e.g. for observation) make sure
+to always call session.refresh(false) before applying changes or session.refresh(true) before saving the changes.
+
+2. Enable the DEBUG level for `org.apache.jackrabbit.oak.plugins.commit.MergingNodeStateDiff` and `org.apache.jackrabbit.oak.plugins.commit.ConflictValidator` loggers if you want
+to have more information on the circumstances of a conflict that happened in a point of time.
+
+3. Write your own conflict handler and add it when configuring your Oak or WhiteBoard instances. Only if you know what you are doing (i.e. you know how to resolve
+the conflict in each one of the possible situations). By default, the [AnnotatingConflictHandler](https://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/commit/AnnotatingConflictHandler.html) instance will discard your changes
+and your commit will fail. If persisting changes fails with a conflict and you cannot lose them, refactor your code such that you can retry after having called session.refresh(false).
+Check the source code of [JcrLastModifiedConflictHandler](https://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/commit/JcrLastModifiedConflictHandler.html) for an example of a conflict handler.
\ No newline at end of file
