Skip to content

Latest commit

 

History

History
267 lines (183 loc) · 6.21 KB

CONTRIBUTING.md

File metadata and controls

267 lines (183 loc) · 6.21 KB

Contributing

Thanks for contributing to JupyterLite!

We follow Project Jupyter's Code of Conduct for a friendly and welcoming collaborative environment.

Setup

Get the Code

git clone https://github.com/jtpio/jupyterlite

if you don't have git yet, you might be able to use the instructions below to get it

Prerequisites

You'll need:

  • git
  • nodejs >=12
  • yarn <2
  • python >=3.8

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

Development Tasks

doit

doit handles the full software lifecycle, spanning JavaScript to documentation building. It understands the dependencies between different nested tasks, usually as files that change on disk.

List Tasks

To see all of the tasks available, use the list action:

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 list:

doit info build:js:app:retro

Task and Action Defaults

The default doit action is run which... runs the named tasks.

The default tasks are lint and build, which do basically everything performed by continuous integration, so the following are equivalent:

doit
doit lint build
doit run lint build

Core JavaScript development

The JupyterLite core JS development workflow builds:

  • a ready-to-serve, empty website with:
    • a lab/index.html and supporting assets
    • a retro/*/index.html and supporting assets (for tree, editor, etc)
    • common configuration tools
  • typedoc documentation
    • TBD: a set of component tarballs distributed on npmjs.com

from:

  • a set of packages in the @jupyterlite namespace, , written in TypeScript
  • some buildutils
  • some webpack configuration
  • some un-compiled JS for very early loading utilities

    • TODO: fix this, perhaps with typedoc 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.

Quick start

Most of the development tasks can be run with one command:

yarn bootstrap

Install JavaScript Dependencies

yarn

Build Apps

To build development assets:

yarn build

To build production assets:

yarn build:prod

Serve Apps

These are not real server solutions, but they will serve all of the assets types (including .wasm) correctly for JupyterLite under development, testing, and demo purposes.

To serve with scripts/serve.js, based on Node.js's http module:

yarn serve

To serve with Python's built-in http.server module (requires Python 3.7+):

yarn serve:py

Watch Sources

yarn watch

Lint/Format Sources

yarn lint

Run Unit Tests

yarn build:test
yarn test

Lab Extension development

TBD: describe how the @jupyterlite/labextension works with e.g. real serverextension

(Browser) Python Development

TBD: describe successor to pyolite, patches, etc.

(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 content.

On testing

Extra 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 site.

Documentation

The documentation site, served on jupyterlite.rtfd.io, uses information from different parts of the software lifecycle (e.g. contains a copy of the built app directory), so using the doit tools are recommended.

Build Documentation

doit docs

Extra sphinx-build arguments are set by the SPHINX_ARGS environment variable. For example to fail on all warnings (the configuration for the ReadTheDocs build):

SPHINX_ARGS='["-W"]' doit docs

Watch Documentation

doit watch:docs

Community Tasks

Issues

JupyterLite features and bug fixes start as issues on GitHub.

  • Look through the existing issues (and pull requests!) to see if a related issue already exists or is being worked on
  • If it is new:
    • Start a new issue
    • Pick an appropriate template
    • Fill out the template
    • Wait for the community to respond

Pull Requests

JupyterLite 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 main
  • Make changes
  • Run doit lint test
  • Push to your fork
  • Start the pull request
    • your git cli 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 #123 help tie the collaboration history together
  • Wait for continuous integration
    • If stuff breaks, fix it or ask for help!

Previews

Each pull request is built and deployed on Read The Docs. You can check the live preview by clicking on the Read The Docs check:

rtd-pr-preview

Releasing

TBD