diff --git a/README.md b/README.md
index 18840d4..32e4311 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@ Libvalkey is the official C client for the [Valkey](https://valkey.io) database.
 - Using the library
   - [Standalone mode](docs/standalone.md)
   - [Cluster mode](docs/cluster.md)
+  - [Migration guide](docs/migration-guide.md)
 
 ## Features
 
diff --git a/docs/migration-guide.md b/docs/migration-guide.md
new file mode 100644
index 0000000..37ccb2d
--- /dev/null
+++ b/docs/migration-guide.md
@@ -0,0 +1,41 @@
+# Migration guide
+
+Libvalkey can replace both libraries `hiredis` and `hiredis-cluster`.
+This guide highlights which APIs that have changed and what you need to do when migrating to libvalkey.
+
+The general actions needed are:
+
+* Replace the prefix `redis` with `valkey` in API usages.
+* Update include paths depending on your previous installation.
+  All `libvalkey` headers are now found under `include/valkey/`.
+
+## Migrating from `hiredis` v1.2.0
+
+No version specific action needed.
+
+## Migrating from `hiredis-cluster` 0.14.0
+
+### Renamed API functions
+
+* `ctx_get_by_node` is renamed to `valkeyClusterGetValkeyContext`.
+* `actx_get_by_node` is renamed to `valkeyClusterGetValkeyAsyncContext`.
+
+### Removed API functions
+
+* `redisClusterSetMaxRedirect` removed and replaced with `valkeyClusterSetOptionMaxRetry`.
+* `redisClusterSetOptionConnectBlock` removed since it was deprecated.
+* `redisClusterSetOptionConnectNonBlock` removed since it was deprecated.
+* `parse_cluster_nodes` removed from API, for internal use only.
+* `parse_cluster_slots` removed from API, for internal use only.
+
+### Removed support for splitting multi-key commands per slot
+
+Since old days (from `hiredis-vip`) there has been support for sending some commands with multiple keys that covers multiple slots.
+The client would split the command into multiple commands and send to each node handling each slot.
+This was unnecessary complex and broke any expectations of atomicity.
+Commands affected are `DEL`, `EXISTS`, `MGET` and `MSET`.
+
+_Proposed action:_
+
+Partition the keys by slot using `valkeyClusterGetSlotByKey` before sending affected commands.
+Construct new commands when needed and send them using multiple calls to `valkeyClusterCommand` or equivalent.