Backwards Compatibility, Versions and Breaking Changes#

New versions of JupyterLab may break backwards compatibility with extensions and other Jupytercustomizations. Breaking changes are kept to a minimum where possible. JupyterLab developmentand release cycles followsemantic versioning, so when breakingchanges are necessary, they are communicated via the version numbering scheme. In short, thismeans that, for a JupyterLab version X.Y.Z:

• Major version (X) number changes indicate breaking changes (NOT backwards compatible)

• Minor Version (Y) number changes indicate a backwards compatible addition of new features

• Patch version (Z) number changes indicate backwards compatible bug fixes

Contributions to JupyterLab extensions and other customizations should plan for possiblebreaking changes. Consider documenting your maintenance plans to users in these projects.You may also wish to consider pinning the major version of JupyterLab when developingextensions (in your package metadata).

We maintain a major version of JupyterLab forone year after its successor’s first release.Seeversion lifecycle for details.JupyterLab v4 was released on May 15, 2023, so JupyterLab v3 will be maintaineduntil May 15, 2024. JupyterLab v1 and v2 are no longer maintained.All JupyterLab v2 and v3 users are strongly advised to upgrade as soon as possible.

Issue Management#

Opening an issue lets community members participate in the designdiscussion, makes others aware of work being done, and sets the stagefor a fruitful community interaction. When you open a new bug orenhancement request, please provide all the requested informationin the issue templateso that a responder will be able to triage your bug without delay.

A pull request should referencethe issue it is addressing. Once the pull request is merged, the issuerelated to it will also be closed. If there is additional discussionaround implementation the issue may be re-opened. Once 30 days havepassed with no additional discussion, thelockbot will lock the issue. If additionaldiscussion is desired, or if the pull request doesn’t fully address thelocked issue, please open a new issue referencing the locked issue.

New issues are subject to triage. A developer with triage permissions(atriager) will do the following:

1. Read the issue

2. Search the existing issues and mark it as a duplicate if necessary

3. If additional information is required, add a comment requesting it

4. If the issue is ready to be worked on, assign it to a milestone

5. Apply appropriate labels to the issue (see examples below)

A developer may start to work on an issue as soon as it is filed. Pleasework with a triager if they have any questions about your issue so thatyour changes can be merged in without delay.

Definition of Ready#

One of the main goals of triage is to get issues into a state where theyareready for someone to work on. Once a triager is satisfied that anissue meets the definition below, they will remove thestatus:NeedsTriagelabel from it. We will not merge a pull request for an issue that stillneeds triage.

Triagers should also ensure that the issue has appropriate labels thatdescribe it, such as labels with thepkg: prefix for issues thataffect one or more packages.

All requested information, where applicable, is provided. From thetemplates in JupyterLab’s issues:

For abug:

• Description, preferably including screen shots

• Steps to reproduce

• Expected behavior

• Context, such as OS, browser, JupyterLab version, and output or log excerpts

For afeature request:

• Description of the problem

• Description of the proposed solution

• Additional context

The issue should represent real, relevant, feasible work. In short, if aknowledgeable person were to be assigned this issue, they would be able tocomplete it with a reasonable amount of effort and assistance, and itfurthers the goals of the Jupyter project.

• Issues should be unique; triage is the best time to identify duplicates.

• Bugs represent valid expectations for use of Jupyter products and services.

• Expectations for security, performance, accessibility, and localization matchgenerally-accepted norms in the community that uses Jupyter products.

• The issue represents work that one developer can commit to owning, even ifthey collaborate with other developers for feedback. Excessively large issuesshould be split into multiple issues, each triaged individually, or intoteam-compass issues to discussmore substantive changes.

Labels Used by Triagers#

All new bugs and enhancement requests have thestatus:NeedsTriage label.

On a regular basis, Jupyter contributors (triage reviewers or triagers)review JupyterLab issues taggedwithstatus:NeedsTriage, starting with the oldest, and determinewhether they meet the definition of ready.

Once triaged, if the issue is ready, the reviewer removes thestatus:NeedsTriage label; no additional label is required. If thereis not enough information in the issue as filed, the triage reviewer appliesthestatus:NeedsInfo label and leavesstatus:NeedsTriage in place.If an issue has remained instatus:NeedsInfo for more than 14 dayswithout any follow-up communication, the reviewer should applystatus:Blocked. A blocked issue should be closed after another 14 dayspass without a reply that unblocks it.

Our expectation is that every new issue should be examined within a week ofits creation.

Triagers should label easier/lower complexity issues asgoodfirstissue tofacilitate beginner contributions. A good first issue should have:

• A clear, easily understood description with screen shots and expectations that do not require much familiarity with the project

• Links, either in the description or in comments, to documentation and source code files that are relevant to the issue

• Recommended points of contact, either by GitHub username or on other forums (Discourse, etc) where a contributor can get help

Unless an issue is time-sensitive, such as if it is a release blockerfor an imminent release, experienced Jupyter contributors should avoidpicking up recent issues with thegoodfirstissue label.

Tagging Issues with Labels#

Users without the commit rights to the JupyterLab repository can tagissues with labels using the@meeseeksdev bot. For example: To applythe labelfoo andbarbaz to an issue, comment@meeseeksdevtagfoo"barbaz" on the issue.

Installing Node.js and jlpm#

Building JupyterLab from its GitHub source code requires Node.js. Thedevelopment version requires Node.js version 20+, as defined in theengines specification indev_mode/package.json.

If you useconda, you can get it with:

condainstall-cconda-forgenodejs=20

If you useHomebrew on macOS:

brewinstallnode

You can also use the installer from theNode.jswebsite.

To check which version of Node.js is installed:

node-v

Using automation to set up a local development environment#

While there is a lot to learn by following the steps above, they can be automated to save time.The main advantages of using automation are: reduced time to get the environment up-and-running, reduced time tore-build the environment, better standardisation (“baseline”, reproducible environments).This section shows how to do that using VS Code dev containers, Docker and Vagrant.

gitclonehttps://github.com/<your-github-username>/jupyterlab.git

gitclonehttps://github.com/<your-github-username>/jupyterlab.gitcdjupyterlabbashdocker/start.sh

bashdocker/start.shdev4567# Start JupyterLab dev container at port 4567bashdocker/start.shstop# Stop the running containerbashdocker/start.shclean# Remove the docker imagebashdocker/start.shbuild# Rebuild the docker image# Log into the container's shell with the JupyterLab environment activated.# It's useful to run the tests or install dependencies.bashdocker/start.shshell

bashdocker/start.shshell# In the container shelljlpmadd...exit# Back to host shellbashdocker/start.shbuild

Frequent issues#

• A few of the scripts will run “python”. If your target python iscalled something else (such as “python3”) then parts of the buildwill fail. You may wish to build in a conda environment, or make analias.

• Thejlpm command is a JupyterLab-provided, locked version of theyarn package manager. If you haveyarn installed already, you can use theyarn command whendeveloping, and it will use the local version ofyarn injupyterlab/yarn.js when run in the repository or a builtapplication directory.

• If you decide to use thejlpm command and encounter thejlpm:commandnotfound error, try adding the user-level bindirectory to yourPATH environment variable. You alreadyinstalledjlpm along with JupyterLab in the previous command, butjlpm might not be accessible due toPATH environment variablerelated issues. If you are using a Unix derivative (FreeBSD, GNU /Linux, OS X), you can achieve this by usingexportPATH="$HOME/.local/bin:$PATH" command.

• At times, it may be necessary to clean your local repo with thecommandnpmrunclean:slate. This will clean the repository, andre-install and rebuild.

• Ifpip gives aVersionConflict error, it usually means thatthe installed version ofjupyterlab_server is out of date. Runpipinstall--upgradejupyterlab_server to get the latestversion.

• To install JupyterLab in isolation for a single conda/virtualenvironment, you can add the--sys-prefix flag to the extensionactivation above; this will tie the installation to thesys.prefix location of your environment, without writing anythingin your user-wide settings area (which are visible to all your envs):

• You can runjlpmrunbuild:dev:prod to build more accuratesourcemaps that show the original Typescript code when debugging.However, it takes a bit longer to build the sources, so is used onlyto build for production by default.

For installation instructions for contributors who want to write documentation, please seeWriting Documentation

Run JupyterLab#

Start JupyterLab in development mode:

jupyterlab--dev-mode

Development mode ensures that you are running the JavaScript assets thatare built in the dev-installed Python package. Note that when running indev mode, extensions will not be activated by default - referdocumentation on extension development to know more.

When running in dev mode, a red stripe will appear at the top of thepage; this is to indicate running an unreleased version.

If you want to change the TypeScript code and rebuild on the fly(needs page refresh after each rebuild):

jupyterlab--dev-mode--watch

Build and Run the Tests#

jlpmrunbuild:testutilsjlpmtest

You can run tests for an individual package by changing to theappropriate package folder:

cdpackages/notebookjlpmrunbuild:testjlpmtest--runInBand

We usejest for all tests, so standardjest workflows apply.Tests can be debugged in either VSCode or Chrome. It can help to add anit.only to a specific test when debugging. All of thetest*scripts in each package acceptjestclioptions.

Translatable strings update#

The translatable strings update cannot occur on patch release. Theymust be delayed on minor or major versions.

Benchmark parameters#

The benchmark can be customized using the following environment variables:

• BENCHMARK_NUMBER_SAMPLES: Number of samples to compute the execution time distribution; default 20.

• BENCHMARK_OUTPUTFILE: Benchmark result output file; defaultbenchmark.json. It is overridden in theplaywright-benchmark.config.js.

• BENCHMARK_REFERENCE: Reference name of the data; default isactual for current data andexpected for the reference.

More tests can be carried out manually on JupyterLab branches and run weekly on the default branch injupyterlab/benchmarks repository.

Good Practices for Integration tests#

Here are some good practices to follow when writing integration tests:

• Don’t compare multiple screenshots in the same test; if the first comparison breaks,it will require running multiple times the CI workflow to fix all tests.

The Debugger Adapter Protocol#

The following diagram illustrates the types of messages sent between the JupyterLab extension and the kernel.

Inspecting Debug Messages in VS Code#

Inspecting the debug messages in VS Code can be useful to understand when debug requests are made (for example triggered by a UI action), and to compare the behavior of the JupyterLab debugger with the Python debugger in VS Code.

The first step is to create a test file and a debug configuration (launch.json):

{"version":"0.2.0","configurations":[{"name":"Python: Current File","type":"python","request":"launch","program":"${file}","console":"integratedTerminal","env":{"DEBUGPY_LOG_DIR":"/path/to/logs/folder"}}]}

Then start the debugger:

The content of the log file looks like this:

...D00000.032:IDE-->{"command":"initialize","arguments":{"clientID":"vscode","clientName":"Visual Studio Code","adapterID":"python","pathFormat":"path","linesStartAt1":true,"columnsStartAt1":true,"supportsVariableType":true,"supportsVariablePaging":true,"supportsRunInTerminalRequest":true,"locale":"en-us"},"type":"request","seq":1}...

With:

• IDE = VS Code

• PYD = pydev debugger

• Messages follow theDAP

References#

• Dump cell and state restoration:jupyterlab/debugger#52

• Protocol Overview:https://microsoft.github.io/debug-adapter-protocol/overview

• Specification:https://microsoft.github.io/debug-adapter-protocol/specification

Build the NPM Packages from Source#

gitclonehttps://github.com/jupyterlab/jupyterlab.gitcdjupyterlabpipinstall-e.jlpmjlpmrunbuild:packages

Rebuild

jlpmruncleanjlpmrunbuild:packages

Writing Style#

• Write documentation in the second person, referringto the reader as “you”. Do not use the first person plural “we.”The author of the documentation is not sitting next to the user, sousing “we” can lead to frustration when things don’t work asexpected.

• Avoid words that trivialize using JupyterLab such as “simply” or“just.” Tasks that developers find simple or easy may not be forusers.

• Write in the active tense. For example, “drag the notebook cells…” ratherthan “notebook cells can be dragged…”.

• The beginning of each section should begin with a short (1–2sentence) high-level description of the topic, feature or component.

• Use “enable” rather than “allow” to indicate what JupyterLab makespossible for users. Using “allow” connotes that we are giving thempermission, whereas “enable” connotes empowerment.

User Interface Naming Conventions#

Build the JupyterLab server extension#

When you make a change to JupyterLab npm package source files, run:

jlpmrunbuild

to build the changes, and then refresh your browser to see the changes.

To have the system build after each source file change, run:

jupyterlab--dev-mode--watch

Linking/Unlinking Packages to JupyterLab#

If you want to make changes to one of JupyterLab’s external packages(for example,Lumino) and testthem out against your copy of JupyterLab, you can easily do so using thelink command:

1. Make your changes and then build the external package

2. Link JupyterLab to modded package

   • navigate to top level of your JupyterLab repo, then runjlpmlink<path-to-external-repo>--all

3. You can then (re)build JupyterLab (egjlpmrunbuild) and yourchanges should be picked up by the build.

To restore JupyterLab to its original state, you use theunlinkcommand:

1. Unlink JupyterLab and modded package

   • navigate to top level of your JupyterLab repo, then runjlpmunlink<path-to-external-repo>--all

2. Reinstall original version of the external package in JupyterLab

   • runjlpminstall--check-files

3. You can then (re)build JupyterLab and everything should be back todefault.

Possible Linking Pitfalls#

If you’re working on an external project with more than one package,you’ll probably have to link in your copies of every package in theproject, including those you made no changes to. Failing to do so maycause issues relating to duplication of shared state.

Specifically, when working with Lumino, you’ll probably have to linkyour copy of the"@lumino/messaging" package (in addition towhatever packages you actually made changes to). This is due topotential duplication of objects contained in theMessageLoopnamespace provided by themessaging package.