Contributors#

This page is for people who wish to contribute to Jupyter Scheduler directly.

Developers wishing to extend or override Jupyter Scheduler should instead refer to our developer’s guide.

Development install#

The commands below will install a development environment for Jupyter Scheduler locally. Before running these commands, you should ensure that NodeJS is installed locally. The jlpm command is JupyterLab’s pinned version of yarn that is installed with JupyterLab. You may use yarn or npm in lieu of jlpm below.

# Clone the repo to your local environment
git clone https://github.com/jupyter-server/jupyter-scheduler.git

# Change dir to the cloned project
cd jupyter-scheduler

# Install the project in editable mode
pip install -e .

# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite

# Server extension must be manually installed in develop mode
jupyter server extension enable jupyter_scheduler

# Rebuild extension Typescript source after making changes
jlpm build

You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension’s source and automatically rebuild the extension.

# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm watch
# Run JupyterLab in another terminal
jupyter lab

With the watch command running, every file change will be built immediately and made available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).

Development uninstall#

# Server extension must be manually disabled in develop mode
jupyter server extension disable jupyter_scheduler
pip uninstall jupyter_scheduler

In development mode, you will also need to remove the symlink created by jupyter labextension develop command. First, find the lab extension folder:

$ jupyter labextension list

...
/opt/anaconda3/envs/jupyter-scheduler/share/jupyter/labextensions
        @jupyterlab/scheduler v1.1.4 enabled OK

Then, remove the symlink named jupyter-scheduler within that folder.

# Remove the symlink
rm /opt/anaconda3/envs/jupyter-scheduler/share/jupyter/labextensions/jupyter_scheduler

Testing#

Server tests#

This extension uses Pytest for Python code testing.

Install test dependencies (needed only once):

pip install -e ".[test]"

To execute them, run:

pytest -vv -r ap --cov jupyter_scheduler

Frontend tests#

This extension is using Jest for JavaScript code testing.

To execute them, execute:

jlpm
jlpm test

Integration tests#

This extension uses Playwright for the integration tests (user-level tests). More precisely, the JupyterLab helper Galata is used to test the extension in JupyterLab.

Install test dependencies (needed only once):

cd ./ui-tests
jlpm install
jlpm playwright install
cd ..

To execute them, run:

cd ./ui-tests
jlpm playwright test

You can find more information in the ui-tests README.

Documentation#

First, ensure GNU Make is installed locally, and then install the docs dependencies:

pip install -e ".[docs]"

Documentation is built with the Sphinx documentation generator, by running the following command from the project root:

make -C docs html

Documentation source files are written in MyST, a rich and more expressive flavor of Markdown. These files are located under docs/.

The generated documentation files placed under docs/_build/html can be directly opened in the browser. We recommend bookmarking these file links if you will be editing and reviewing documentation frequently in the browser.

Sphinx by default only rebuilds files it detects were changed, though this detection logic is sometimes faulty. To force a full rebuild of the documentation:

make -C docs clean && make -C docs html

Releasing#

Releases should be done via Jupyter Releaser. If you have admin permissions on the repository, you can go to the “Actions” panel on GitHub and follow the following instructions to release a new version of Jupyter Scheduler.

Select the “Step 1: Prep Release” workflow on the left-hand panel, and then select “Run workflow”. This will open the workflow form. Replace the “Next Version Specifier” with the next version of Jupyter Scheduler (e.g. 1.2.3). “Branch to Target” should be replaced with the branch that should be released. Usually this will be main. Then select “Run workflow” button to run the workflow.
Verify the draft release changelog in the Releases page for Jupyter Scheduler.
Return to the Actions panel and select the “Step 2: Publish Release” workflow. Run this workflow with the target branch set to the same branch specified in Step 1.
Wait for the workflow to complete, and then verify the publish on PyPi and NPM.

Manual release#

In the unlikely scenario Jupyter Releaser fails in Step 2, the below steps should be followed to perform a manual release. Make sure to publish the draft release changelog afterwards.

Python package#

This extension can be distributed as Python packages. The Python packaging instructions in the pyproject.toml file can wrap your extension in a Python package. Before generating a package, we first need to install build.

pip install build twine tbump

Check out your local main branch and keep it up to date with the remote version.

git checkout main
git remote update
git pull upstream main

Bump the version using tbump. By default this will create a tag.

tbump --no-push <new-version>

Push the bump version commit and tag to main upstream branch.

git push upstream main
git push upstream <new-version-tag>

Checkout the new tagged commit.

git checkout <new-version-tag>

Build the extension

jlpm run build:prod

To create a Python source package (.tar.gz) and the binary package (.whl) in the dist/ directory, do:

python -m build

python setup.py sdist bdist_wheel is deprecated and will not work for this package.

Then to upload the package to PyPI, do:

twine upload dist/*

NPM package#

To publish the frontend part of the extension as a NPM package, do:

npm login
npm publish --access public