Thanks for contributing to JupyterLite!
We follow Project Jupyter’s Code of Conduct for a friendly and welcoming collaborative environment.
Get the Code¶
git clone https://github.com/jupyterlite/jupyterlite
if you don’t have
gityet, you might be able to use the instructions below to get it
Various package managers on different operating systems provide these.
A recommended approach for any platform is to install Mambaforge and use the Binder environment description checked into the repo.mamba env update --file .binder/environment.yml mamba activate jupyterlite-dev
For speed, in GitHub Actions,
nodejs are installed directly. Provided you
already have these, to install the full development stack:
python -m pip install -r requirements-docs.txt -r requirements-lint.txt
doit handles the full software lifecycle, spanning
between different nested tasks, usually as files that change on disk.
To see all of the tasks available, use the
doit list --all --status
To get information about a specific task, use the info
info action with the task
name from the first column of
doit info build:js:app:retro
Task and Action Defaults¶
doit action is
run which… runs the named tasks.
The default tasks are
docs:app:build, so the following are
doit doit lint build docs:app:build doit run lint build docs:app:build
On Linux and MacOS,
doit auto (which can also accept task names) will watch all files
and perform any dependent tasks, then reload the tasks, useful for rapidly seeing
doit lintwhich may change source files. This can be confusing to IDEs (or the
watch:jstasks) that might be performing their own watching, or run up against file system limits.
The JupyterLite core JS development workflow builds:
a ready-to-serve, empty website with:
lab/index.htmland supporting assets
retro/*/index.htmland supporting assets (for
common configuration tools
TBD: a set of component tarballs distributed on
npmjs.com. See #7.
a set of
@jupyterlitenamespace, , written in TypeScript
some un-compiled, vanilla JS for very early-loading utilities
TODO: fix this, perhaps with jsdoc tags
While most of the scripts below will be run (in the correct order based on changes) by
doit, the following scripts (defined in
package.json) are worth highlighting.
Most of the development tasks can be run with one command:
To build development assets:
To build production assets:
These are not real server solutions, but they will serve all of the assets types (including
.wasm) correctly for JupyterLite development, testing, and demo purposes.
To serve with
scripts/serve.js, based on Node.js’s
To serve with Python’s built-in
http.server module (requires
Run Unit Tests¶
yarn build:test yarn test
jupyterlite uses the
Galata framework for end
to end and visual regression testing. Galata is build on top of
Playwright provides a high level API to programmatically
interact with the JupyterLab UI, and tools for taking screenshots and generating test
Running the UI Tests locally¶
First install the dependencies:
cd ui-tests yarn install
The UI tests use a custom JupyterLite website:
# in ui-tests directory # build yarn build # start the HTTP server to server the JupyterLite website yarn start
Then run the
# in the ui-tests directory yarn test
You can pass additional arguments to
playwright by appending parameters to the
command. For example to run the test in headed mode,
yarn test --headed.
Checkout the Playwright Command Line Reference for more information about the available command line options.
Adding new UI tests¶
New test suites can be added to the
ui-tests/tests directory. You can see some
additional example test suites in the
JupyterLab repo. If
the tests in new suites are doing visual regression tests or HTML source regression
tests then you also need to add their reference images to the
Reference Image Captures¶
When adding a new visual regression test, first make sure your tests pass locally on your development environment, with a reference snapshots generated in your dev environment. You can generate new reference snapshots by running the following command:
To update the snapshots:
push the new changes to the branch
wait for the CI check to complete
go to the artifacts section and download the
extract the archives
-snapshotsdirectories to replace the existing ones
commmit and push the changes
The generated snapshots can be found on the Summary page of the CI check:
Lab Extension development¶
TBD: describe how the
@jupyterlite/labextensionworks with e.g. real serverextensions
(Browser) Python Development¶
TBD: describe successor to
pyolite, patches, etc. See #151.
(Server) Python Development¶
After all the
yarn-related work has finished, the terminal-compatible python uses the
npm-compatible tarball of
app to build new sites combined with original user
PYTEST_ARGS can be passed as a (gross) JSON string:
PYTEST_ARGS='["-s", "-x", "--ff"]' doit test:py:jupyterlite
Several tasks invoke the
jupyter lite CLI, which is further described in the main docs
The documentation site, served on jupyterlite.rtfd.io, uses information from different
parts of the software lifecycle (e.g. contains an archive of the built
so using the doit tools are recommended.
sphinx-buildarguments are set by the
SPHINX_ARGSenvironment variable. For example to fail on all warnings (the configuration for the ReadTheDocs build):SPHINX_ARGS='["-W"]' doit docs
This also respects the
SPHINX_ARGSvariable. If working on the theme layer,
SPHINX_ARGS='["-a", "-j8"]'is recommended, as by default static assets are not included in the calculation of what needs to be updated.
JupyterLite features and bug fixes start as issues on GitHub.
JupyterLite features and fixes become real as pull requests.
Pull requests are a great place to discuss work-in-progress, but it is highly recommended to create an issue before starting work so the community can weigh in on choices.
Fork the repo
Make a new branch off
Push to your fork
Start the pull request
gitCLI should offer you a link, as will the GitHub web UI
reference one or more issue so those that are interested can find your work
adding magic strings like
fixes #123help tie the collaboration history together
Wait for continuous integration
If stuff breaks, fix it or ask for help!
Each pull request is built and deployed on ReadTheDocs. You can view the live preview site by clicking on the ReadTheDocs check:
Additionally, several build artifacts are available from the each run on the Actions page, including:
an app archive ready to be used as the input to the
jupyter liteCLI with all the demo content and supporting extensions.
You must be logged in to GitHub to download these.
TBD: See #121.