Add section to readme about stable memory compatibility (#1150)

This PR adds more help in case external developers run into stable
memory incompatibilities on upgrade.

README.md

@@ -32,6 +32,7 @@ For more information, see [What is Internet Identity?](https://internetcomputer.
 * [Build Features and Flavors](#build-features-and-flavors)
   * [Features](#features)
   * [Flavors](#flavors)
+* [Stable Memory Compatibility](#stable-memory-compatibility)
 * [Getting Help](#getting-help)
 * [Links](#links)
 
@@ -123,6 +124,14 @@ We offer some pre-built Wasm modules that contain flavors, i.e. sets of features
 | Test | This flavor is used by Internet Identity's test suite. It fully supports authentication but uses a known CAPTCHA value for test automation. Includes the following features: <br><ul><li><code>II_FETCH_ROOT_KEY</code></li><li><code>II_DUMMY_CAPTCHA</code></li></ul>| [💾](https://github.com/dfinity/internet-identity/releases/latest/download/internet_identity_test.wasm) |
 | Development | This flavor contains a version of Internet Identity that effectively performs no checks. It can be useful for external developers who want to integrate Internet Identity in their project and care about the general Internet Identity authentication flow, without wanting to deal with authentication and, in particular, WebAuthentication. Includes the following features: <br><ul><li><code>II_FETCH_ROOT_KEY</code></li><li><code>II_DUMMY_CAPTCHA</code></li><li><code>II_DUMMY_AUTH</code></li><li><code>II_INSECURE_REQUESTS</code></li></ul><br>See the [`using-dev-build`](demos/using-dev-build/README.md) project for an example on how to use this flavor.| [💾](https://github.com/dfinity/internet-identity/releases/latest/download/internet_identity_dev.wasm) |
 
+## Stable Memory Compatibility
+
+Internet Identity requires data in stable memory to have a specific layout in order to be upgradeable. The layout has been changed multiple times in the past. This is why II stable memory is versioned and each version of II is only compatible to some stable memory versions.
+
+If on upgrade II traps with the message `stable memory layout version ... is no longer supported` then the stable memory layout has changed and is no longer compatible.
+
+The easiest way to address this is to reinstall the canister (thus wiping stable memory). A canister can be reinstalled by executing `dfx deploy <canister> --mode reinstall`.
+
 ## Getting Help
 
 We're here to help! Here are some ways you can reach out for help if you get stuck:

src/internet_identity/src/storage.rs

@@ -212,7 +212,12 @@ impl<M: Memory> Storage<M> {
             ));
         }
         if &header.version < SUPPORTED_LAYOUT_VERSIONS.start() {
-            trap(&format!("stable memory layout version {} is no longer supported:\nEither reinstall (wiping stable memory) or migrate using a previous II version", header.version));
+            trap(&format!(
+                "stable memory layout version {} is no longer supported:\n\
+            Either reinstall (wiping stable memory) or migrate using a previous II version\n\
+            See https://github.com/dfinity/internet-identity#stable-memory-compatibility for more information.",
+                header.version
+            ));
         }
         if !SUPPORTED_LAYOUT_VERSIONS.contains(&header.version) {
             trap(&format!("unsupported header version: {}", header.version));