Add migration guide and changelog
Signed-off-by: Bence Szépkúti <bence.szepkuti@arm.com>
diff --git a/ChangeLog.d/split-config.txt b/ChangeLog.d/split-config.txt
new file mode 100644
index 0000000..bb807be
--- /dev/null
+++ b/ChangeLog.d/split-config.txt
@@ -0,0 +1,12 @@
+Changes
+ * config.h has been split into build_info.h and mbedtls_config.h
+ build_info.h is intended to be included from C code directly, while
+ mbedtls_config.h is intended to be edited by end users whishing to
+ change the build configuration, and should generally only be included from
+ build_info.h.
+ * The handling of MBEDTLS_CONFIG_FILE has been moved into build_info.h.
+ * Mandatory version symbols MBEDTLS_CONFIG_VERSION and
+ MBEDTLS_USER_CONFIG_VERSION were introduced for MBEDTLS_CONFIG_FILE and
+ MBEDTLS_USER_CONFIG_FILE respectively. They have to be defined with a
+ value of one in their respective config file for the config to be
+ considered valid.
diff --git a/docs/3.0-migration-guide.d/split_config.md b/docs/3.0-migration-guide.d/split_config.md
new file mode 100644
index 0000000..b8f516a
--- /dev/null
+++ b/docs/3.0-migration-guide.d/split_config.md
@@ -0,0 +1,16 @@
+Introduce a level of indirection and versioning in the config files
+-------------------------------------------------------------------
+
+`config.h` was split into `build_info.h` and `mbedtls_config.h`.
+`build_info.h` is intended to be included from C code directly, while
+`mbedtls_config.h` is intended to be edited by end users whishing to
+change the build configuration, and should generally only be included from
+`build_info.h`. This is because all the preprocessor logic has been moved
+into `build_info.h`, including the handling of the `MBEDTLS_CONFIG_FILE`
+macro.
+
+Mandatory version symbols were introduced for `MBEDTLS_CONFIG_FILE` and
+`MBEDTLS_USER_CONFIG_FILE`, `MBEDTLS_CONFIG_VERSION` and
+`MBEDTLS_USER_CONFIG_VERSION` respectively. Both config files should include
+a definiton of their respective version symbol, with a value of `1` to be
+considered valid.
