From 8a2a17383881c50847b322ee838fe594766d921c Mon Sep 17 00:00:00 2001 From: goelakash Date: Sat, 23 May 2026 23:43:16 -0700 Subject: [PATCH 1/2] Improve dev environment setup docs in CONTRIBUTING.md Add prerequisites table (Python >= 3.10, Node.js 22.x), two additional setup paths (pixi, pip+yarn/npm) alongside the existing mamba instructions, dev server flags for local development, and a troubleshooting guide for common issues. Preserves all original content and wording. Addresses jupyter/notebook#7701 and jupyter/notebook#7029. --- CONTRIBUTING.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 373fd858fd0..1965370d001 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,11 +7,35 @@ for a friendly and welcoming collaborative environment. ## Setting up a development environment +### Prerequisites + +| Tool | Required Version | How to check | +| ------- | ---------------- | ------------------ | +| Python | >= 3.10 | `python --version` | +| Node.js | 22.x | `node --version` | + Note: You will need NodeJS to build the extension package. The `jlpm` command is Jupyter's pinned version of [yarn](https://yarnpkg.com/) that is installed with Jupyter Builder. You may use `yarn` or `npm` in lieu of `jlpm` below. +### Option A: Using pixi + +[pixi](https://pixi.sh/) handles Python, Node.js, and all dependencies in one step. [Install pixi](https://pixi.prefix.dev/latest/#installation), then from the repo root: + +```bash +# Install everything and set up the dev environment +pixi install +pixi run develop + +# Start the notebook server +pixi run start +``` + +This installs the correct Python and Node.js versions automatically and links the extension for development. + +### Option B: Using mamba/conda + **Note**: we recommend using `mamba` to speed up the creation of the environment. ```bash @@ -35,6 +59,31 @@ jlpm develop jupyter server extension enable notebook ``` +### Option C: Using pip + yarn/npm (no conda) + +If you prefer not to use conda/mamba, you can set up the environment with pip and yarn (or npm) directly. Make sure you have Python >= 3.10 and Node.js 22.x installed on your system. + +```bash +# Create and activate a virtual environment +python -m venv .venv +source .venv/bin/activate # On Windows: .venv\Scripts\activate + +# Install the package in development mode +pip install -e ".[dev,docs,test]" + +# Install JavaScript dependencies (use yarn or npm) +yarn install # or: npm install +yarn build # or: npm run build + +# Link the notebook extension for development +yarn develop # or: npm run develop + +# Enable the server extension +jupyter server extension enable notebook +``` + +### Building and running + `notebook` follows a monorepo structure. To build all the packages at once: ```bash @@ -47,6 +96,16 @@ There is also a `watch` script to watch for changes and rebuild the app automati jlpm watch ``` +To start the notebook server with development-friendly flags: + +```bash +jupyter notebook --no-browser --ServerApp.token='' --NotebookApp.allow_origin='*' +``` + +This disables the auth token (convenient for local dev) and allows cross-origin requests (useful if you're working with a separate frontend dev server). + +### Verifying your setup + To make sure the `notebook` server extension is installed: ```bash @@ -70,6 +129,29 @@ Then start Jupyter Notebook with: jupyter notebook ``` +### Troubleshooting + +**`jlpm: command not found`**\ +`jlpm` is installed as part of Jupyter Builder. Make sure you ran `pip install -e ".[dev,docs,test]"` first. Alternatively, use `yarn` or `npm` directly. + +**JavaScript build fails with missing modules**\ +Try clearing the build cache and reinstalling: + +```bash +jlpm clean +jlpm +jlpm build +``` + +**`ModuleNotFoundError` when running `jupyter notebook`**\ +Make sure you installed in editable mode (`pip install -e .`) and that your virtual environment is activated. + +**Node.js version mismatch**\ +This project requires Node.js 22.x. Check with `node --version`. If you're using nvm: `nvm install 22 && nvm use 22`. + +**Pre-commit hooks not running**\ +Run `pre-commit install` manually. The hooks should have been set up automatically by the dev install, but may need to be reinitialized if you cloned before installing. + ### Local changes in Notebook dependencies The development installation described above fetches JavaScript dependencies from `npm`, From 8ec7a88214adadaf9ed3e6b3d289908a00dee2e2 Mon Sep 17 00:00:00 2001 From: goelakash Date: Wed, 3 Jun 2026 19:04:19 -0700 Subject: [PATCH 2/2] Use jlpm exclusively in CONTRIBUTING dev setup Drop the yarn/npm alternates from Option C and the troubleshooting section. The repo only ships yarn.lock, so plain yarn or npm may resolve different package versions and break the build; jlpm is the pinned yarn version installed with Jupyter Builder. --- CONTRIBUTING.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1965370d001..aed573d39dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,8 +16,7 @@ for a friendly and welcoming collaborative environment. Note: You will need NodeJS to build the extension package. -The `jlpm` command is Jupyter's pinned version of [yarn](https://yarnpkg.com/) that is installed with Jupyter Builder. You may use -`yarn` or `npm` in lieu of `jlpm` below. +The `jlpm` command is Jupyter's pinned version of [yarn](https://yarnpkg.com/) that is installed with Jupyter Builder. Use `jlpm` for all JavaScript dependency and build commands below; the repo only ships a `yarn.lock`, so plain `yarn` or `npm` may resolve different versions and break the build. ### Option A: Using pixi @@ -59,24 +58,24 @@ jlpm develop jupyter server extension enable notebook ``` -### Option C: Using pip + yarn/npm (no conda) +### Option C: Using pip + jlpm (no conda) -If you prefer not to use conda/mamba, you can set up the environment with pip and yarn (or npm) directly. Make sure you have Python >= 3.10 and Node.js 22.x installed on your system. +If you prefer not to use conda/mamba, you can set up the environment with pip directly. Make sure you have Python >= 3.10 and Node.js 22.x installed on your system. ```bash # Create and activate a virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate -# Install the package in development mode +# Install the package in development mode (this also installs jlpm) pip install -e ".[dev,docs,test]" -# Install JavaScript dependencies (use yarn or npm) -yarn install # or: npm install -yarn build # or: npm run build +# Install JavaScript dependencies and build +jlpm install +jlpm build # Link the notebook extension for development -yarn develop # or: npm run develop +jlpm develop # Enable the server extension jupyter server extension enable notebook @@ -132,7 +131,7 @@ jupyter notebook ### Troubleshooting **`jlpm: command not found`**\ -`jlpm` is installed as part of Jupyter Builder. Make sure you ran `pip install -e ".[dev,docs,test]"` first. Alternatively, use `yarn` or `npm` directly. +`jlpm` is installed as part of Jupyter Builder. Make sure you ran `pip install -e ".[dev,docs,test]"` first. **JavaScript build fails with missing modules**\ Try clearing the build cache and reinstalling: