Add migration guide
Signed-off-by: Hanno Becker <hanno.becker@arm.com>
diff --git a/docs/3.0-migration-guide.d/session-cache-api.md b/docs/3.0-migration-guide.d/session-cache-api.md
new file mode 100644
index 0000000..b28ce19
--- /dev/null
+++ b/docs/3.0-migration-guide.d/session-cache-api.md
@@ -0,0 +1,28 @@
+Session Cache API Change
+-----------------------------------------------------------------
+
+This affects users who use `mbedtls_ssl_conf_session_cache()`
+to configure a custom session cache implementation different
+from the one Mbed TLS implements in `library/ssl_cache.c`.
+
+Those users will need to modify the API of their session cache
+implementation to that of a key-value store with keys being
+session IDs and values being instances of `mbedtls_ssl_session`:
+
+```
+typedef int mbedtls_ssl_cache_get_t( void *data,
+ unsigned char const *session_id,
+ size_t session_id_len,
+ mbedtls_ssl_session *session );
+typedef int mbedtls_ssl_cache_set_t( void *data,
+ unsigned char const *session_id,
+ size_t session_id_len,
+ const mbedtls_ssl_session *session );
+```
+
+Since the structure of `mbedtls_ssl_session` is no longer public from 3.0
+onwards, portable session cache implementations must not access fields of
+`mbedtls_ssl_session`. See the corresponding migration guide. Users that
+find themselves unable to migrate their session cache functionality without
+accessing fields of `mbedtls_ssl_session` should describe their usecase
+on the Mbed TLS mailing list.