CONTRIBUTING.md

Contributing to ipyelk

Install

• Get Mambaforge
• Get doit

mamba install doit

Get Started

git clone https://github.com/jupyrdf/ipyelk
cd ipyelk
doit list --all # see what you can do
doit            # this is _basically_ what happens on binder
doit lab        # start lab

Branches

Presently, on GitHub:

• master: the 1.x line, which distributes the lab extension inside the python distribution for JupyterLab >3
  • generates the latest tag on ReadTheDocs
  • PRs welcome for new features or bugfixes here, backport fixes to 0.3.x
• 0.3.x: the JupyterLab 1 (and, theoretically, 2) -compatible maintenance branch
  • generates the 0.3.x tag on ReadTheDocs
  • PRs welcome for fixes here, forward-port to master

Important Paths

Path	Purpose
atest/	Robot Framework source for acceptance tests
dodo.py	task automation tool
js/	TypeScript source for @jupyrdf/jupyter-elk
package.json/	npm package description for @jupyrdf/jupyter-elk
pyproject.toml	package description for ipyelk
src/	Python source for ipyelk
src/ipyelk/schema/elkschema.json	JSON schema derived from the TypeScript source
yarn.lock	frozen npm dependencies

• Run doit to get ready to develop
• Most commands are run with doit all (this is what CI does)

Live Development

You can watch the source directory and run JupyterLab in watch mode to watch for changes in the extension's source and automatically rebuild the extension and application.

• Run:

doit watch

• Open a tab with the provided URL in a standards-compliant browser of choice
• After making changes, wait for webpack terminal output, then reload the browser
• If you add a new file, probably will have to restart the whole thing

Logging

In the browser, jupyter-elk should only emit console.warn (or higher) messages if there's actually a problem.

For more verbose output, add ELK_DEBUG anywhere in a new browser URL, e.g.

http://localhost:8888/lab#ELK_DEBUG

Note: if a message will be helpful for debugging, make sure to import and guard console.* or higher with ELK_DEBUG &&

On the python side, each Widget has .log.debug which is preferable to print statements. The log level can be increased for a running kernel through the JupyterLab's Log Console, opened with the Show Log Console command.

Quality Assurance

• Run:

doit lint

• Ensure the examples work. These will be tested in CI with:
  • nbconvert --execute
  • in JupyterLab by Robot Framework with Restart Kernel and Run All Cells
• If you add new features:
  • Add a new, minimal demonstration notebook to the examples.
    • Treat each feature as a function which can be reused for other examples, with:
      • the example in a humane name, e.g. a_basic_elk_example
      • some suitable defaults and knobs to twiddle
  • Add appropriate links to your new example.
  • Add appropriate Robot Framework tests

Limiting Testing

To run just some acceptance tests, add something like:

*** Test Cases ***
Some Test
  [Tags]  some:tag
  ...

Then run:

ATEST_ARGS="--exclude NOTsome:tag" doit test:atest

Building Documentation

To build (and check the spelling and link health) of what would go to ipyelk.readthedocs.org, we:

• build with sphinx and myst-nb
• check spelling with hunspell
• check links with pytest-check-links

doit -n8 checkdocs

Watch the Docs

sphinx-autobuild will try to watch docs sources for changes, re-build, and serve a live-reloading website. A number of files (e.g. _static) won't often update correctly, but will usually work when restarted.

doit watch_docs

Releasing

• After merging to master, download the ipyelk dist artifacts
• Inspect the files in ./dist.
• Check out master
• Tag appropriately

git push upstream --tags

• Ensure you have credentials for pypi and npmjs
  • npmjs requires you have set up two-factor authentication (2FA)... this is strongly recommended for pypi
  • do not use jlpm publish or yarn publish, as this appears to drop files from the distribution

npm login
npm publish
npm logout
twine upload where-you-expanded-the-archive/ipyelk-*

Updating Dependencies

Python Dependencies

• Edit the dependencies section of environment specs or the binder environment.
• Run:

doit lock

• Commit the changes to the env specs and the lock files.

if you delete all the lockfiles, you'll need to conda-lock on path with e.g.

mamba install -c conda-forge conda-lock

Browser Dependencies

• Edit the appropriate section of the package file.
• Run:

doit setup:js || doit setup:js || doit setup:js
doit lint

• Commit the changes to the package file and the yarn lock file.