Add migration guide for 8.0

[martinRenou]

No description provided.

[github-actions]

👈 Launch a binder notebook on branch martinRenou/ipywidgets/add_migration_guide

[vidartf]

I've made a phosphor/lumino message processing compatibility implementation in a package like this. Any input on the implementation itself? Any suggestions for where to best put it in the migration guide?

class MyWidget extends DOMWidgetView {

  _processLuminoMessage(msg: Message, _super: (msg: Message) => void): void {
    _super.call(this, msg);
    switch (msg.type) {
    case 'after-attach':
      // Auto-sizing should be updated when attached to DOM:
      this.onChange();
      break;
    }
  }

  processPhosphorMessage(msg: Message): void {
    this._processLuminoMessage(msg, (DOMWidgetView as any).processPhosphorMessage);
  }

  processLuminoMessage(msg: Message): void {
    this._processLuminoMessage(msg, (DOMWidgetView as any).processLuminoMessage);
  }
}

[vidartf]

We should make sure we include some notes about what we recommend in terms of depending on phosphor / lumino . This is probably important in terms of which version of /base can be used? It is also important in terms of allowing JupyterLab to drop the resolution key in the future.

[martinRenou]

cc. @mariobuikhuizen @maartenbreddels

We discussed Phosphor/Lumino (and ipywidgets 7/8) compatibility with @ibdafna yesterday. Some open questions raised:

• feat: backward compatibility with 7.x #3358 was introducing some aliases that allows to stay compatible with ipywidgets 8 for free, but it is missing some aliases, like JupyterLuminoPanelWidget. Should we fix that?
• What @vidartf is suggesting in Add migration guide for 8.0 #3405 (review) sounds good to me, but it requires people to update their code, so what would be the point of adding aliases (as suggested above) anyway? So my question is should we get rid of the aliases and just document how to update user code (what @vidartf is suggesting + document the different aliases to add)?
  I cannot think of a way to fix the processPhosphorMessage/processLuminoMessage incompatibility without changing user code.

Sorry I didn't join the widgets meeting for some time, I'll join the next one.

[jasongrout]

Here is another example of a migration to 8.0, which was only complicated by the fact that it tried to use display_model in an unconventional way: jupyter-widgets/jupyterlab-sidecar#86

[jasongrout]

ipyleaflet also seems very easy to upgrade: jupyter-widgets/ipyleaflet#968

Edit: Oh, it also needs the processPhosphorMessage shim: see jupyter-widgets/ipyleaflet#969

[jasongrout-db]

We may need to put the message compatibility shim in the base widget package itself so that widget packages will inherit it and be able to work under both 7 and 8. Then the widget packages will be able to work under both an ipywidgets 7 manager (which calls processPhosphorMessage) and an ipywidgets 8 manager (which calls processLuminoMessage).

[martinRenou]

@vidartf @jasongrout This should be good for another review, thanks for your comments!