Add migration guide for 8.0

Author: martinRenou

docs/source/migration_guides.md

@@ -4,6 +4,74 @@ Migrating custom widget libraries
 These are migration guides aimed specifically at developers of third-party
 widgets.
 
+Migrating from 7.0 to 8.0
+-------------------------
+
+For example migrations, see these PRs:
+
+- [ipydatagrid](https://github.com/bloomberg/ipydatagrid/pull/282)
+
+To avoid tying your development cycle to ipywidgets, we recommend starting
+the migration on a branch and keeping that branch open until ipywidgets 8.0
+is released.
+
+We also recommend testing the migration in a completely new notebook, rather
+than one that contains widgets that you instantiated with ipywidgets 7.0.
+
+### Updating setup.py
+
+Start by updating the dependency in your `setup.py` to the latest release.
+
+### Updating package.json
+
+Next, we should update the JavaScript dependencies. You will need to update
+your `@jupyter-widgets/base` dependency and the `@jupyter-widgets/controls` **if**
+you depend on it.
+
+The diff will look like the following in case you want to still support ipywidgets<8:
+
+```diff
+- "@jupyter-widgets/base": "^2 || ^3 || ^4",
++ "@jupyter-widgets/base": "^2 || ^3 || ^4 || ^5",
+```
+
+You can also apply the following diff if you only want to support ipywidgets==8 from now on:
+
+```diff
+- "@jupyter-widgets/base": "^2 || ^3 || ^4",
++ "@jupyter-widgets/base": "^5",
+```
+
+### Updating the client-side code
+
+You should only need to change your client-side JavaScript code if you have mentions to the
+archived Phosphor library.
+
+The maintenance for the Phosphor library (now named Lumino) is done under the JupyterLab governance: https://github.com/jupyterlab/lumino
+
+If you used to import classes like ``JupyterPhosphorPanelWidget`` and ``JupyterPhosphorWidget`` from the ``@jupyter-widgets/base`` library, you will need to update them:
+
+```diff
+- import { JupyterPhosphorPanelWidget, JupyterPhosphorWidget } from '@jupyter-widgets/base';
++ import { JupyterLuminoPanelWidget, JupyterLuminoWidget } from '@jupyter-widgets/base';
+```
+
+The ``DOMWidgetView.pWidget`` property has been renamed ``DOMWidgetView.luminoWidget`` (though an alias for ``pWidget`` has been made for conveniance):
+
+```diff
+- this.pWidget
++ this.luminoWidget
+```
+
+The ``DOMWidgetView.processPhosphorMessage`` method has been renamed ``DOMWidgetView.processLuminoMessage``:
+
+```diff
+- processPhosphorMessage(msg: Message): void {
+-     super.processPhosphorMessage(msg);
++ processLuminoMessage(msg: Message): void {
++     super.processLuminoMessage(msg);
+```
+
 Migrating from 6.0 to 7.0
 -------------------------
 
@@ -14,7 +82,7 @@ For example migrations, see these PRs:
 
 To avoid tying your development cycle to ipywidgets, we recommend starting
 the migration on a branch and keeping that branch open until ipywidgets 7.0
-is released. 
+is released.
 
 We also recommend testing the migration in a completely new notebook, rather
 than one that contains widgets that you instantiated with ipywidgets 6.0.
@@ -30,9 +98,9 @@ cycle through the tags until you see the latest 7.0.0 tag.
 
 Next, we should update the JavaScript dependencies. The most important change
 for widget developers is that the JavaScript package for jupyter-widgets has
-been split between `@jupyter-widgets/base` and `@jupyter-widgets/controls`: 
+been split between `@jupyter-widgets/base` and `@jupyter-widgets/controls`:
  - `@jupyter-widgets/base` contains the base widget classes and the layout
-classes 
+classes
  - `@jupyter-widgets/controls` contains the widget classes for the
 user-facing widgets.
 
@@ -105,7 +173,7 @@ that matches a release on NPM. The most common pattern is to request a
 version compatible with the version currently in your `package.json` by using,
 `~{{ version number }}` for `_model_module_version` and `_view_module_version`. See the [cookiecutter
 template](https://github.com/jupyter-widgets/widget-cookiecutter/blob/master/%7B%7Bcookiecutter.github_project_name%7D%7D/js/lib/example.js#L24)
-for details. 
+for details.
 
 Since you probably want to avoid repeating the module version in every
 widget, a common pattern is to import the version from `package.json` and