Skip to content

Latest commit

 

History

History
248 lines (178 loc) · 6.48 KB

CONTRIBUTING.md

File metadata and controls

248 lines (178 loc) · 6.48 KB
Raw

Contributing

Prerequisites

  • Get Mambaforge

  • Get doit and git

    mamba install -c conda-forge doit git

  • Start a command prompt with the base environment activated

Get Started

Most work occurs on the dev branch of the GitHub repo: see below for more.

  • Clone the repo

    git clone https://github.com/jupyrdf/ipyforcegraph
cd ipyforcegraph
git checkout dev
doit env:dev

  • Activate the environment

    Linux/MacOS Windows
    source activate ./envs/py3.11_lab3.6 activate ./envs/py3.11_lab3.6

  • Get up to a running JupyterLab

    doit list --all # see what you can do
doit            # this is _basically_ what happens on binder
doit lab        # start lab

Important Paths

Path Purpose
atest/ Robot Framework source for acceptance tests
dodo.py task automation tool
js/ TypeScript source for @jupyrdf/jupyter-forcegraph
package.json/ npm package description for @jupyrdf/jupyter-forcegraph
pyproject.toml package description for ipyforcegraph
src/ Python source for ipyforcegraph
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

    • e.g., Firefox

  • After making changes, wait for webpack terminal output, then reload the browser

    • output should read something like: 
      webpack 5.75.0 compiled with 7 warnings in 1528 ms

  • If you add a new file, probably will have to restart the whole thing

Environment Variables

With python-dotenv (installed by default), the presence of a .env file will overload any values not set in dodo.py. This is an .ini-like file, with specific examples below.

Logging

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

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

http://localhost:8888/lab#FORCEGRAPH_DEBUG

Note: if a message will be helpful for debugging, make sure to import and guard console.* or higher with 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_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
  ...

Create an .env file:

# .env
ATEST_ARGS=["--exclude", "NOTsome:tag"]

Then run:

doit test

Full Coverage

To collect coverage from the browser and kernel, create a .env file like:

# .env
TOTAL_COVERAGE=1

Then run:

doit test

Building Documentation

To build (and check the spelling and link health) of what would go to ipyforcegraph.rtfd.io, 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

Making Pull Requests

There are two valid targets for pull request:

  • main
    • releases
    • fixes to the documentation
    • post-release "hot" fixes
  • dev
    • any new features
    • anything else

Releasing

  • Make a release issue
  • Follow the checklist

Updating Dependencies

Python Dependencies

  • Edit the dependencies section of the specs

    If this will impact multiple running contexts (e.g. testing in CI and Binder), consider adding a new environment and adding it in the _inherit_from section.

  • Run:

    doit lock

  • Commit the changes to the env specs, locks, and generated environments for ReadTheDocs and Binder.

    If all the lockfiles are deleted, the outer env needs 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.