Backport PR #10654: Add some upgrade notes to JupyterLab 3.1 (#10659)

Co-authored-by: Frédéric Collonval <fcollonval@gmail.com>

docs/source/extension/extension_dev.rst

@@ -681,6 +681,8 @@ path on the user's machine or a provided tarball. Any valid
 We encourage extension authors to add the `jupyterlab-extension GitHub topic
 <https://github.com/search?utf8=%E2%9C%93&q=topic%3Ajupyterlab-extension&type=Repositories>`__ to any GitHub extension repository.
 
+.. _testing_with_jest:
+
 Testing your extension
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -703,14 +705,22 @@ To transpile jupyterlab packages, you need to install the following package:
    jlpm add --dev jest @types/jest ts-jest @babel/core@^7 @babel/preset-env@^7
 
 Then in `jest.config.js`, you will specify to use babel for js files and ignore
-all node modules except the jupyterlab ones:
+all node modules except the ES6 modules:
 
 ::
 
+   const esModules = [
+     '@jupyterlab/',
+     'lib0',
+     'y\\-protocols',
+     'y\\-websocket',
+     'yjs'
+   ].join('|');
+
    module.exports = {
      preset: 'ts-jest/presets/js-with-babel',
      moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
-     transformIgnorePatterns: ['/node_modules/(?!(@jupyterlab/.*)/)'],
+     transformIgnorePatterns: [`/node_modules/(?!${esModules}).+`],
      globals: {
        'ts-jest': {
          tsConfig: 'tsconfig.json'

docs/source/extension/extension_migration.rst

@@ -3,6 +3,48 @@
 Extension Migration Guide
 ================================================
 
+JupyterLab 3.0 to 3.1
+---------------------
+
+Following semver rules, API are compatible.
+
+New main and context menus customization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+JupyterLab 3.1 introduces a new way to hook commands into :ref:`mainmenu` and :ref:`context_menu`.
+It allows the final user to customize those menus through settings as it is already possible for
+the shortcuts.
+
+
+Jest configuration update
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are using jest to test your extension, some new ES6 packages dependencies are added to JupyterLab.
+They need to be ignore when transforming the code with Jest. You will need to update the 
+``transformIgnorePatterns`` to match:
+
+.. code::
+
+   const esModules = [
+     '@jupyterlab/',
+     'lib0',
+     'y\\-protocols',
+     'y\\-websocket',
+     'yjs'
+   ].join('|');
+
+   // ...
+
+   transformIgnorePatterns: [`/node_modules/(?!${esModules}).+`]
+
+For more information, have a look at :ref:`testing_with_jest`.
+
+.. note::
+
+   Here is an example of pull request to update to JupyterLab 3.1 in ``@jupyterlab/git`` extension:  
+   https://github.com/jupyterlab/jupyterlab-git/pull/979/files
+
+
 .. _extension_migration_2_3:
 
 JupyterLab 2.x to 3.x

docs/source/extension/extension_points.rst

@@ -211,6 +211,7 @@ Your command ``label`` function can then check the ``args`` it is provided for `
 and return a different label in that case.
 This can be useful to make a single command flexible enough to work in multiple contexts.
 
+.. _context_menu:
 
 Context Menu
 ------------