diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md
new file mode 100644
index 0000000..ca4f57e
--- /dev/null
+++ b/docs/3.0-migration-guide.md
@@ -0,0 +1,210 @@
+Migrating from Mbed TLS 2.x to Mbed TLS 3.0
+===========================================
+
+This guide details the steps required to migrate from Mbed TLS version 2.x to
+Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks
+compatibility with previous versions, so users (and alt implementors) might
+need to change their own code in order to make it work with Mbed TLS 3.0.
+
+Here's the list of breaking changes; each entry should help you answer these
+two questions: (1) am I affected? (2) if yes, what's my migration path?
+
+Some function parameters were made const
+----------------------------------------
+
+Various functions in the PK and ASN.1 modules had a `const` qualifier added to
+some of their parameters.
+
+This normally doesn't affect your code, unless you use pointers to reference
+those functions. In this case, you'll need to update the type of your pointers
+in order to match the new signature.
+
+Deprecated functions were removed from hashing modules
+------------------------------------------------------
+
+Modules: MD2, MD4, MD5, SHA1, SHA256, SHA512, MD.
+
+- The functions `mbedtls_xxx_starts()`, `mbedtls_xxx_update()`,
+  `mbedtls_xxx_finish()` and `mbedtls_xxx()` were removed. Please use the
+function with the same name with `_ret` appended and check the return value.
+- The function `mbedtls_md_init_ctx()` was removed; please use
+  `mbedtls_md_setup()` instead.
+- The functions `mbedtls_xxx_process()` were removed. You normally don't need
+  to call that from application code. However it you do (or it you want to
+provide your own version of that function), please use
+`mbedtls_internal_xxx_process()` instead, and check the return value.
+
+Deprecated error codes for hardware failures were removed
+---------------------------------------------------------
+
+- The macros `MBEDTLS_ERR_xxx_FEATURE_UNSUPPORTED` from various crypto modules
+  were removed; `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used
+instead.
+- The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules
+  were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead.
+
+Deprecated names for PSA constants and types were removed
+---------------------------------------------------------
+
+Some constants and types that were present in beta version of the PSA Crypto
+API were removed from in version 1.0 of specification. Please switch to the new
+names provided by the 1.0 specification instead.
+
+Internal / alt-focused headers were moved to a private location
+----------------------------------------------------------------
+
+This shouldn't affect users who took care not to include headers that
+were documented as internal, despite being in the public include directory.
+
+If you're providing alt implementations of ECP or RSA, you'll need to add our
+`library` directory to your include path when building your alt
+implementations, and note that `ecp_internal.h` and `rsa_internal.h` have been
+renamed to `ecp_alt.h` and `rsa_alt_helpers.h` respectively.
+
+If you're a library user and used to rely on having access to a structure or
+function that's now in a private header, please reach out on the mailing list
+and explain your need; we'll consider adding a new API in a future version.
+
+Remove the option to allow SHA-1 by default in certificates
+-----------------------------------------------------------
+
+This does not affect users who use the default `config.h`, as this option was
+already off by default.
+
+If you used to enable `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` in your
+`config.h`, first please take a moment to consider whether you really still
+want to accept certificates signed with SHA-1 as those are considered insecure
+and no CA has issued them for a while. If you really need to allow SHA-1 in
+certificates, please set up a custom profile as explained in the ChangeLog.
+
+Remove the certs module from the library
+----------------------------------------
+
+This should not affect production use of the library, as the certificates and
+keys included there were never suitable for production use.
+
+However it might affect you if you relied on them for testing purposes. In
+that case, please embed your own test certificates in your test code; now that
+`certs.c` is out of the library there is no longer any stability guaranteed
+and it may change in incompatible ways at any time.
+
+Remove the HAVEGE module
+------------------------
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects users who called the HAVEGE modules directly (not
+recommended), or users who used it though the entropy module but had it as the
+only source of entropy. If you're in that case, please declare OS or hardware
+RNG interfaces with `mbedtls_entropy_add_source()` and/or use an entropy seed
+file created securely during device provisioning. See
+<https://tls.mbed.org/kb/how-to/add-entropy-sources-to-entropy-pool> for more
+information.
+
+Remove support for parsing SSLv2 ClientHello
+--------------------------------------------
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects TLS servers that have clients who send a SSLv2 ClientHello.
+These days clients are very unlikely to do that. If you have a client that
+does, please try contacting them and encouraging them to upgrade their
+software.
+
+Remove support for SSL 3.0
+--------------------------
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects TLS users who explicitly enabled `MBEDTLS_SSL_PROTO_SSL3`
+and relied on that version in order to communicate with peers that are not up
+to date. If one of your peers in in that case, please try contacting them and
+encouraging them to upgrade their software.
+
+Remove support for compatibility with old Mbed TLS's truncated HMAC
+-------------------------------------------------------------------
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects TLS users enabled `MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT` and
+used the Truncated HMAC extension to communicate with peers using old version
+of Mbed TLS. Please consider using a CCM-8 ciphersuite instead of the
+Truncated HMAC extension, or convicing your peer to upgrade their version of
+Mbed TLS.
+
+Remove support for TLS record-level compression
+-----------------------------------------------
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This only affects TLS users who enabled `MBEDTLS_ZLIB_SUPPORT`. This will not
+cause any failures however if you used to enable TLS record-level compression
+you may find that your bandwidth usage increases without compression. There's
+no general solution to this problem; application protocols might have their
+own compression mechanisms and are in a better position than the TLS stack to
+avoid variants of the CRIME and BREACH attacks.
+
+Remove support for TLS RC4-based ciphersuites
+---------------------------------------------
+
+This does not affect people who used the default `config.h` and the default
+list of ciphersuites, as RC4-based ciehrsuites were already not negociated in
+that case.
+
+Please switch to any of the modern, recommended ciphersuites (based on
+AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support
+any, encourage them to upgrade their software.
+
+Remove support for TLS single-DES ciphersuites
+----------------------------------------------
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+Please switch to any of the modern, recommended ciphersuites (based on
+AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support
+any, encourage them to upgrade their software.
+
+Remove support for TLS record-level hardware acceleration
+---------------------------------------------------------
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+This feature had been broken for a while so we doubt anyone still used it.
+However if you did, please reach out on the mailing list and let us know about
+your use case.
+
+Remove wrapper for libpkcs11-helper
+-----------------------------------
+
+This doesn't affect people using the default configuration as it was already
+disabled by default.
+
+If you used to rely on this module in order to store your private keys
+securely, please have a look at the key management facilities provided by the
+PSA crypto API. If you have a use case that's not covered yet by this API,
+please reach out on the mailing list.
+
+Remove config option `MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME`
+----------------------------------------------------------
+
+This doesn't affect people using the default configuration.
+
+This option has been inactive for a long time. Please use the `lifetime`
+parameter of `mbedtls_ssl_ticket_setup()` instead.
+
+Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0
+-------------------------------------------------------------------
+
+This only affects people who've been using Mbed TLS since before version 2.0
+and still relied on `compat-1.3.h` in their code.
+
+Please use the new names directly in your code; `scripts/rename.pl` (from any
+of the 2.x releases - no longer included in 3.0) might help you do that.
+