documentation: include migration guide

The commit introduces a `migration guide` to the framework to help
downstream extensions and applications migrate to newer versions of the
framework.

Signed-off-by: vince-fugnitto <vincent.fugnitto@ericsson.com>
Co-authored-by: Paul Maréchal <paul.marechal@ericsson.com>

Author: vince-fugnitto

README.md

@@ -86,6 +86,7 @@ Read below how to engage with Theia community:
 - Useful Links:
   - [Developing](doc/Developing.md)
   - [Testing](doc/Testing.md)
+  - [Migration Guide](doc/Migration.md)
   - [API Integration Testing](doc/api-testing.md)
   - [Coding Guidelines](https://github.com/eclipse-theia/theia/wiki/Coding-Guidelines)
   - [Code Organization](https://github.com/eclipse-theia/theia/wiki/Code-Organization)

doc/Migration.md

@@ -0,0 +1,47 @@
+# Migration Guide
+
+## Description
+
+The following guide highlights potential migration steps necessary during `theia` upgrades discovered when adopting the framework.
+
+## Guide
+
+### v1.16.0
+
+[Release](https://github.com/eclipse-theia/theia/releases/tag/v1.16.0)
+
+- TBD.
+
+### v1.15.0
+
+[Release](https://github.com/eclipse-theia/theia/releases/tag/v1.15.0)
+
+- `keytar`: 
+  - [`keytar`](https://github.com/atom/node-keytar) was added as a dependency for the secrets API. and may require `libsecret` in your particular distribution to be functional:
+    - Debian/Ubuntu: `sudo apt-get install libsecret-1-dev`
+    - Red Hat-based: `sudo yum install libsecret-devel`
+    - Arch Linux: `sudo pacman -S libsecret`
+  - It is possible that a `yarn resolution` is necessary for `keytar` to work on older distributions (the fix was added in `1.16.0` by downgrading the dependency version):
+    ```json
+    "resolutions": {
+      "**/keytar": "7.6.0",
+    }
+    ```
+  - `keytar` uses [`prebuild-install`](https://github.com/prebuild/prebuild-install) to download prebuilt binaries. If you are experiencing issues where some shared libraries are missing from the system it was originally built upon, you can tell `prebuild-install` to build the native extension locally by setting the environment variable before performing `yarn`:
+    ```sh
+    # either:
+    export npm_config_build_from_source=true
+    yarn
+    # or:
+    npm_config_build_from_source=true yarn
+    ```
+
+- `webpack`:
+  - The version of webpack was upgraded from 4 to 5 and may require additional shims to work properly given an application's particular setup.
+  - The `webpack` dependency may need to be updated if there are errors when performing a `production` build of the application due to a bogus `webpack-sources` dependency. The valid `webpack` version includes `^5.36.2 <5.47.0`. If necessary, you can use a `yarn resolution` to fix the issue:
+    ```json
+    "resolutions": {
+      "**/webpack": "5.46.0",
+    }
+    ```
+