Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
101 lines (73 loc) · 3.1 KB

CONTRIBUTING.md

File metadata and controls

101 lines (73 loc) · 3.1 KB

Contributing

Install

  1. Clone the repo locally and navigate in the created folder
  2. Prepare a virtual environment with mamba, conda or micromamba
  3. Run the following commands in your newly created environment
# Prepare environment (replace `mamba` by `conda` if needed)
mamba install -c conda-forge nodejs=24 "jupyterlab==4.4.6" jupyter-packaging jupyterlab-h5web

# Install package in development mode
pip install -e .

# Build the extension's Typescript source
jlpm run build

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

# Server extension must be manually enabled in develop mode
jupyter server extension enable jupyterlab_h5web

# Check your setup
jupyter server extension list
jupyter labextension list

Develop

# Start JupyterLab
jupyter lab

# In a separate terminal, watch and rebuild the front-end automatically
jlpm run watch

# Alternatively, rebuild when needed
jlpm run build

Whenever the front-end rebuilds, make sure to refresh JupyterLab in your browser to see the changes.

By default, jlpm run build builds the front-end in development mode and generates source maps for easier debugging with the browser dev tools. To also generate source maps for the JupyterLab core extensions, run:

jupyter lab build --minimize=False

Unfortunately, building the front-end in development mode breaks H5Web's R3F-based visualisations (Heatmap, Line, etc.) The current workaround is to built in production mode with jlpm run build:prod.

Uninstall

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

In development mode, you will also need to remove the symlink created by jupyter labextension develop command. To find its location, you can run jupyter labextension list to figure out where the labextensions folder is located. Then you can remove the symlink named jupyterlab-h5web within that folder.

Format

This extension uses prettier to format *.ts files and black to format *.py files.

Release

The release process is adapted from the one from h5web.

To release a new version:

  1. Check out main and pull the latest changes.
  2. Make sure your working tree doesn't have uncommitted changes and that the latest commit on main has passed the CI.
  3. Run npm version [ patch | minor | major | <new-version> ]

This command bumps the version number in package.json, commits the change and then tags the commit with the same version number. The postversion script then runs automatically and pushes the new commit and the new tag. This, in turn, triggers the Release workflow on the CI, which builds and publishes the package to PyPI.

Once the Release worklow has completed:

  • Make sure the new package version is available on PyPI
  • Write and publish release notes on GitHub.