Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
165 lines (103 loc) · 4.1 KB

CONTRIBUTING.md

File metadata and controls

165 lines (103 loc) · 4.1 KB
Raw

Development

Prerequisites

Before you begin, make sure your environment matches the following versions:

  • Node.js: >= 18.20.0 (20.x LTS recommended)
  • npm: >= 9.x (npm 10+ works with Node 20)

Check your versions:

node --version
npm --version

Tip: Use nvm or volta to manage and switch Node.js versions.

For reproducible installs, use:

npm ci

Dependencies

Refer to package.json for the full list of dependencies and devDependencies.

Setup

To prepare your environment after cloning the repo, run:

npm install

Compiles and hot-reloads for development

npm run dev

Compiles and minifies for production

npm run build

Analyzing the production bundle

Generate a production bundle and produce a bundle size breakdown report:

npm run build:analyze

Lints and fixes files

npm run lint

Quality checks

The pre-commit hook and CI run node scripts/checks/check.mjs. It compares the files you changed with the base (HEAD locally, the target branch in CI), so existing code is left alone and only a change that makes a file worse fails.

  • Complexity: in src, a function stays within cyclomatic complexity 10, nesting depth 3 and 4 parameters, and a file within 600 lines. A file already over a limit may not go further over, and a new file must be within all of them.
  • Duplication: a change to the tests may not add a block of 60 or more tokens that repeats another test.
  • Conventions: no new binary files outside the directories that already hold them, such as tests/baseline.

The limits are in scripts/checks/config.mjs. Stage your changes before running the script by hand, since it reads the index. CHECKS_SKIP=1 git commit skips it for one commit.

Testing

# unit tests
npm run test

# e2e tests (Chrome)
npm run test:e2e:chrome

When running end-to-end tests, baseline images are saved to tests/baseline. Baseline diffs and actual snapshots are saved to .tmp/runs/<port>, where <port> is the static server port this checkout uses. Locally, a passing run deletes that directory on the way out, so the snapshots stay around only after a failure. CI always keeps it, so the artifacts below are there whether the run passed or not.

Downloaded test datasets are cached in .tmp/datasets and shared by every run, so deleting a run directory does not force a re-download.

Two checkouts get different ports and different run directories, so their suites can run at the same time. Two suites out of one checkout cannot: they would share dist/ and tests/baseline. Set VOLVIEW_E2E_PORT and VOLVIEW_E2E_AUX_PORT if something else already holds the ports a checkout picked.

When adding a new baseline image and test, the image should be pulled from GitHub Actions. Every test run will upload artifacts containing the snapshots taken, and those should be used when verifying and committing the baseline images.

Run one e2e spec file

npm run test:e2e:dev -- -- --spec ./tests/specs/remote-manifest.e2e.ts

Versioning

Merging to main automatically publishes prerelease packages to NPM:

  1. Merge creates a prerelease tag (e.g. v4.4.0-dev.)
  2. Tag triggers automatic NPM publish with @dev dist-tag
npm install volview          # Gets latest stable release (e.g., 4.4.0)
npm install volview@dev      # Gets latest dev package (most recent commit to main branch)

To publish a new release via CI/CD, manually create and push a tag, e.g.:

git tag v4.5.0  # must match format 'v[0-9]+.[0-9]+.[0-9]+'
git push origin --tags

Developing with VTK.js

Follow these steps to develop against a custom development branch of VTK.js:

  1. Build and package VTK.js:
path/to/vtk-js > npm run build:esm
  1. Create a symbolic link to the VTK.js distribution folder on your local system:
cd path/to/vtk-js/dist/esm
npm link
  1. Reference the symbolic link in your local VolView build:
cd path/to/VolView
npm link --no-save @kitware/vtk.js
  1. Build and run VolView:
npm run dev