Lab 3 migration

[jeffyjefflabs]

Docs:

• Upstream ticket: JupyterLab 3.0 jupyter/docker-stacks#1207
• Migration guide

Some terminology, to avoid confusion:

• Jupyter back-end options:
  • notebook server, which supports "serverextensions" (no space) that I'll refer to as old-server extensions
  • jupyter_server, which supports "server extensions" (space) that I'll refer to as new-server extensions
• Jupyter front-end options:
  • notebook - the traditional UI, often called "classic" -- but since I'm about to mention two other "classic" projects, I'll call it "Notebook UI" for clarity
  • lab - the next-gen UI
  • jupyterlab-classic - the look and feel of the Notebook UI but built with Lab components
• Compatibility layers:
  • nbclassic - provides the Notebook UI as a new-server extension and also translates old-server extensions into new-server extensions. (To be clear, this isn't just something that looks like the Notebook UI, it is literally the same code, running through the compatibility layer.)

In Lab 2, Lab was an old-server extension, so launching jupyter notebook and jupyter lab were essentially equivalent, giving you a notebook server with both front-ends running as old-server extensions.

In Lab 3, Lab is now a new-server extension, so if you launch jupyter lab you get the new jupyter_server backend, with the Lab UI running as a new-server extension, and the Notebook UI running via nbclassic. Any old-server extensions you had configured for the notebook back-end will get translated into new-server extensions -- however this process is not perfect and may not work for all old-server extensions (e.g. the nbextensions configurator). You may also see console warnings encouraging you to update old-server extensions to the new-server extension API. Also note that the new back-end uses a different configuration file.

In Lab 3, Lab is also still able to run as an old-server extension, so if you launch jupyter notebook you get the old notebook back-end with both front ends, just like in Lab 2. So everything works just like it did before, for now.

In Lab 3, you can also add the jupyterlab-classic extension, which looks similar to the Notebook UI but is built from the ground up using Lab components.

Now, several things are "deprecated" -- maybe not in a formal sense with dates and timelines, but there may come a time when something breaks and the maintainers decide it's no longer worth fixing. These are the capabilities that should be considered deprecated:

1. Lab being able to run as an old-server extension (i.e. at some point it won't run on the notebook back-end)
2. Lab automatically providing nbclassic as a dependency (i.e. at some point we may need to explicitly add it)
3. nbclassic being able to provide the Notebook UI as a new-server extension
4. notebook itself, although since this is back-end and front-end in one package, this is more likely to just not be maintained rather than to outright break

The implication of (1) and (3) together is that eventually the Lab UI and the Notebook UI may be mutually exclusive, and the implication of (4) is that we should prepare users for the eventual demise of the Notebook UI (which is where jupyterlab-classic and Lab's simple mode come in).

Similar to the strategy of the upstream jupyter/docker-stacks image, the migration path probably looks like this:

1. Add support for jupyter lab entrypoint but still default to jupyter notebook, with the goal of providing the same user experience on top of either back-end (I've started this in the lab3 branch)
2. Change default entrypoint to jupyter lab, using nbclassic for backward compatibility and jupyterlab-classic to help transition users
3. Remove jupyter notebook entrypoint

We don't necessarily have to do this on the same timeline as the upstream image, but we might have to override their defaults. The only thing I see forcing our hand on any of the steps is if some of the deprecated capabilities actually stop working.

[romainx]

Hello @jeffyjefflabs,

Very good description, if you don't mind I will quote it in the upstream ticket 😄.
Interesting to read this description because the way each component interacts with other is not clear at first glance.
For information we have already merged a kind of dual setup that implements the procedure described in the Migration guide (PR jupyter/docker-stacks#1206 and issue jupyter/docker-stacks#1205). So, the last images can run either JupyterLab 2.x and JupyterLab 3.x even if, as you have seen, the upgrade is not over.

I will definitely keep an eye 👀 here since I could get a lot of information.
And I would be happy to help / contribute if needed.
Best

[jeffyjefflabs]

Thanks! Yeah, feel free to quote. We have both Lab and Notebook users, so we had a brief moment of panic after reading the Lab 3 release notes thinking we couldn't run both simultaneously -- fortunately there's been a lot of effort into compatibility in both directions.