Contributing to Jupyter Notebook#

Thanks for contributing to Jupyter Notebook!

Make sure to followProject Jupyter’s Code of Conductfor a friendly and welcoming collaborative environment.

Setting up a development environment#

Note: You will need NodeJS to build the extension package.

Thejlpm command is JupyterLab’s pinned version ofyarn that is installed with JupyterLab. You may useyarn ornpm in lieu ofjlpm below.

Note: we recommend usingmamba to speed up the creation of the environment.

# create a new environmentmambacreate-nnotebook-cconda-forgepythonnodejs-y# activate the environmentmambaactivatenotebook# Install package in development modepipinstall-e".[dev,docs,test]"# Install dependencies and build packagesjlpmjlpmbuild# Link the notebook extension and @jupyter-notebook schemasjlpmdevelop# Enable the server extensionjupyterserverextensionenablenotebook

notebook follows a monorepo structure. To build all the packages at once:

jlpmbuild

There is also awatch script to watch for changes and rebuild the app automatically:

jlpmwatch

To make sure thenotebook server extension is installed:

$jupyterserverextensionlistConfigdir:/home/username/.jupyterConfigdir:/home/username/miniforge3/envs/notebook/etc/jupyterjupyterlabenabled-Validatingjupyterlab...jupyterlab3.0.0OKnotebookenabled-Validatingnotebook...notebook7.0.0a0OKConfigdir:/usr/local/etc/jupyter

Then start Jupyter Notebook with:

jupyternotebook

Local changes in Notebook dependencies#

The development installation described above fetches JavaScript dependencies fromnpm.according to the versions in thepackage.json file.However, it is sometimes useful to be able to test changes in Notebook, with dependencies (e.g.@jupyterlab packages) that have not yetbeen published.

yalc can help you use local JavaScript packages when building Notebook, acting as a local package repository.

  • Install yalc globally in your environment:npminstall-gyalc

  • Publish your dependency package:
    yalcpublish, from the package root directory.
    For instance, if you are developing on@jupyterlab/ui-components, this command must be executed frompath_to_jupyterlab/packages/ui-components.

  • Depend on this local repository in Notebook:

    • from the Notebook root directory:
      yalcaddyour_package : this will create adependencies entry in the mainpackage.json file.
      With the previous example, it would beyalcadd@jupyterlab/ui-components.

    • Notebook is a monorepo, so we want this dependency to be ‘linked’ as a resolution (for all sub-packages) insteadof a dependency.
      The easiest way is to manually move the new entry inpackage.json fromdependencies toresolutions.

    • Build Notebook with the local dependency:
      jlpminstall&&jlpmbuild

Changes in the dependency must then be built and pushed usingjlpmbuild&&yalcpush (from the package root directory),and fetched from Notebook usingyarninstall.

Warning: you need to make sure that the dependencies of Notebook and the local package match correctly,otherwise there will be errors with webpack during build.
In the previous example, both@jupyterlab/ui-components and Notebook depend on@jupyterlab/coreutils. Westrongly advise you to depend on the same version.

Running Tests#

To run the tests:

jlpmrunbuild:testjlpmruntest

There are also end to end tests to cover higher level user interactions, located in theui-tests folder. To run these tests:

cdui-tests#install required packages for jlpmjlpm#install playwrightjlpmplaywrightinstall# start a new Jupyter server in a terminaljlpmstart# in a new terminal, run the testsjlpmtest

Thetest script calls the Playwright test runner. You can pass additional arguments toplaywright by appending parameters to the command. For example to run the test in headed mode,jlpmtest--headed.

Check out thePlaywright Command Line Reference for more information about the available command line options.

Running the end to end tests in headful mode will trigger something like the following:

playwright-headed-demo

Tasks caching#

The repository is configured to use the Lerna caching system (vianx) for some of the development scripts.

This helps speed up rebuilds when runningjlpmrunbuild multiple times to avoid rebuilding packages that have not changed on disk.

You can generate a graph to have a better idea of the dependencies between all the packages using the following command:

npxnxgraph

Running the command will open a browser tab by default with a graph that looks like the following:

a screenshot showing the nx task graph

To learn more about Lerna caching:

  • https://lerna.js.org/docs/features/cache-tasks

  • https://nx.dev/features/cache-task-results

Updating reference snapshots#

Often a PR might make changes to the user interface, which can cause the visual regression tests to fail.

If you want to update the reference snapshots while working on a PR you can post the following sentence as a GitHub comment:

botpleaseupdateplaywrightsnapshots

This will trigger a GitHub Action that will run the UI tests automatically and push new commits to the branch if the reference snapshots have changed.

Code Styling#

All non-python source code is formatted usingprettier and python source code is formatted usingblack.When code is modified and committed, all staged files will beautomatically formatted using pre-commit git hooks (with help frompre-commit. The benefit ofusing code formatters likeprettier andblack is that it removes the topic ofcode style from the conversation when reviewing pull requests, therebyspeeding up the review process.

As long as your code is valid,the pre-commit hook should take care of how it should look.pre-commit and its associated hooks will automatically be installed whenyou runpipinstall-e".[dev,test]"

To installpre-commit manually, run the following:

pipinstallpre-commitpre-commitinstall

You can invoke the pre-commit hook by hand at any time with:

pre-commitrun

which should run any autoformatting on your codeand tell you about any errors it couldn’t fix automatically.You may also installblack integrationinto your text editor to format code automatically.

If you have already committed files before setting up the pre-commithook withpre-commitinstall, you can fix everything up usingpre-commitrun--all-files. You need to make the fixing commityourself after that.

You may also use the prettier npm script (e.g.npmrunprettier oryarnprettier orjlpmprettier) to format the entire code base.We recommend installing a prettier extension for your code editor andconfiguring it to format your code with a keyboard shortcut, orautomatically on save.

Some of the hooks only run on CI by default, but you can invoke them byrunning with the--hook-stagemanual argument.

Documentation#

First make sure you have set up a development environment as described above.

Then run the following command to build the docs:

hatchrundocs:build

In a separate terminal window, run the following command to serve the documentation:

hatchrundocs:serve

Now open a web browser and navigate tohttp://localhost:8000 to access the documentation.

Contributing from the browser#

Alternatively you can also contribute to Jupyter Notebook without setting up a local environment, directly from a web browser:

  • GitHub CodeSpaces is directly integrated into GitHub. This repository uses thepixi package manager to set up the development environment. To contribute after the Codespace is started:

    • Runpixishell in a terminal to activate the development environment

    • Use the commands above for building the extension and running the tests, for example:jlpmbuild

    • To start the application:pixirunstart. A popup should appear with a button to open the Jupyter Notebook in a new browser tab. If the popup does not appear, you can navigate to the “Forwarded ports” panel to find the URL to the application.

  • GitHub’sbuilt-in editor is suitable for contributing small fixes.

  • A more advancedgithub.dev editor can be accessed by pressing the dot (.) key while in the Jupyter Notebook GitHub repository