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
: the1.x
line, which distributes the lab extension inside the python distribution for JupyterLab>3
generates the
latest
tag on ReadTheDocsPRs welcome for new features or bugfixes here, backport fixes to
0.3.x
0.3.x
: the JupyterLab 1 (and, theoretically, 2) -compatible maintenance branchgenerates the
0.3.x
tag on ReadTheDocsPRs welcome for fixes here, forward-port to
master
Important Paths#
Path |
Purpose |
---|---|
|
Robot Framework source for acceptance tests |
|
task automation tool |
|
TypeScript source for |
|
|
|
package description for |
|
Python source for |
|
JSON schema derived from the TypeScript source |
|
frozen |
Run
doit
to get ready to developMost 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 browserIf 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 guardconsole.*
or higher withELK_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
andmyst-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 artifactsInspect the files in
./dist
.Check out master
Tag appropriately
git push upstream --tags
Ensure you have credentials for
pypi
andnpmjs
npmjs
requires you have set up two-factor authentication (2FA)… this is strongly recommended forpypi
do not use
jlpm publish
oryarn 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.