Simple retry policy documentation

docs/src/migration_guide.md

@@ -114,3 +114,25 @@ When `localDc` is not provided connections to all nodes will be allowed.
 **WARNING**:
 This is a change in behavior. In the DataStax driver, when `localDc` would not be provided,
 `localDataCenter` from client options would be used.
+
+## Retry policies
+
+### Supported retry policies
+
+- `FallthroughRetryPolicy`
+
+### Not supported retry policy
+
+- (legacy) `RetryPolicy`
+- `IdempotenceAwareRetryPolicy`
+- custom retry policies
+
+#### legacy RetryPolicy
+
+The `RetryPolicy` as present in the DataStax driver is no longer supported.
+It was replaced with a [new implementation](./retry_policies.md). There are no plans for
+re-creating its functionality. You do not have to update a code to migrate to new policy.
+
+#### IdempotenceAwareRetryPolicy
+
+This policy was deprecated in the DataStax driver, and for this reason was removed from this driver.

docs/src/retry_policies.md

@@ -0,0 +1,19 @@
+# Retry policies
+
+Currently the driver supports only built-in policies. This includes the following policies:
+
+<!-- TODO: This is a very brief documentation, but this is what the rust driver provides...
+https://github.com/scylladb/scylla-rust-driver/tree/main/docs/source/retry-policy.
+There appears to be an issue to address this fact:
+https://github.com/scylladb/scylla-rust-driver/issues/1285
+We should update this documentation, when the rust driver updates it's docs.
+ -->
+
+- Default retry policy (used if no other policy is specified):
+
+    It retries when there is a high chance that it might help.
+    This policy is based on the one in [DataStax Java Driver](https://docs.datastax.com/en/developer/java-driver/4.11/manual/core/retries/index.html). The behavior is the same.
+
+- Falthrough retry policy:
+
+    Never retries, returns errors straight to the user. Useful for debugging