Skip to content

docs: call out Node 22 prerequisite in installation guide (#512)#668

Open
jbbqqf wants to merge 1 commit intointerpretml:mainfrom
jbbqqf:feat/512-install-guide-node-version
Open

docs: call out Node 22 prerequisite in installation guide (#512)#668
jbbqqf wants to merge 1 commit intointerpretml:mainfrom
jbbqqf:feat/512-install-guide-node-version

Conversation

@jbbqqf
Copy link
Copy Markdown

@jbbqqf jbbqqf commented May 9, 2026

Summary

The installation guide doesn't mention which Node.js version to use,
so users following it on systems with older Node (e.g. the Node 8 that
ships as the default nodejs package on older Ubuntu LTS releases)
hit a wall on npm install for the visualization bundle (issue #512).
Add a small "Prerequisites" subsection that calls out Node 22 (matching
CI) and shows the nvm install 22 / nvm use 22 recipe.

Fixes #512Development installation: Requirements?

Context

CI uses Node 22 for the JS bundle (see the comment in the repo's
CLAUDE.md: "Build (matches CI, Node 22): cd shared/vis && npm install && npm run build-prod"). The installation guide
(docs/interpret/installation-guide.ipynb) just instructed the user to
run npm install with no version guidance, which is what tripped up
the user in #512: their system Node was 8, the dependency tree refused
to resolve, and there was no signpost in the docs to tell them why.

This PR is documentation-only.

Changes

  • docs/interpret/installation-guide.ipynb — insert a new
    "Prerequisites" <h2> between the optional conda step and the main
    install block. The new section:
    • states use Node 22 (matches CI);
    • gives the nvm install 22 / nvm use 22 / node --version recipe;
    • mentions the Visual Studio 2022 + vcvars64.bat requirement on
      Windows and the implicit g++/clang++ expectation on
      Linux/macOS so platform requirements live in one place rather than
      being scattered through the guide.

No other content moved; the existing build steps follow unchanged.

Reproduce BEFORE/AFTER yourself (copy-paste)

# --- one-time setup ---
git clone https://github.com/interpretml/interpret.git /tmp/repro && cd /tmp/repro

# --- BEFORE (origin/main) ---
git checkout origin/main
grep -n "Node\|nvm\|node 22\|Node 22" docs/interpret/installation-guide.ipynb | head
# Expected: no hits — there is no Node version guidance.

# --- AFTER (this PR) ---
git fetch https://github.com/jbbqqf/interpret.git feat/512-install-guide-node-version
git checkout FETCH_HEAD
grep -n "Node\|nvm\|node 22\|Node 22" docs/interpret/installation-guide.ipynb | head
# Expected: lines mentioning "Node 22" and "nvm install 22".

To preview rendered output: open the notebook in JupyterLab, or
jupyter nbconvert --to html docs/interpret/installation-guide.ipynb.

What I ran locally

  • python3 -c "import json; json.load(open('docs/interpret/installation-guide.ipynb'))"
    parses cleanly (3 cells, nbformat 4).
  • git diff docs/interpret/installation-guide.ipynb → 18 inserted
    lines inside the existing cell 3724ac29, no other cells touched.

Edge cases tested

# Scenario Verified by
1 Notebook stays valid nbformat-4 JSON json.load(...) round-trip clean
2 Only the install-guide cell is modified git diff --stat shows 1 file, 18 +/0 -
3 Existing build steps unchanged the cd interpret, ./build.sh, cd shared/vis, npm run …, pip install -e … block is byte-identical to origin/main

Risk / blast radius

Documentation-only. No code paths affected. The new prose only adds
recommendations; existing readers who already had Node 22 see no
behavioural change.

Release note

Documentation: installation guide now lists Node 22 as a prerequisite
for building the visualization bundle (issue #512).

PR drafted with assistance from Claude Code. The change was reviewed
manually against interpretml/interpret's source and the cited issue.
The reproducer block above was used during development; it is the same
one a reviewer can paste verbatim.

…l#512)

The installation guide jumps straight from "create a conda env" to
"build the JS visualization bundle with `npm install`", which is the
exact step that fails on older systems where the default `nodejs`
package is Node 8 (issue interpretml#512). The CLAUDE.md / CI configuration
already pins Node 22 for this build, but the user-facing
installation-guide.ipynb did not mention any version requirement.

Add a "Prerequisites" subsection between the optional conda step and
the main install block. The new section: tells the reader to use Node
22 (matching CI), shows the `nvm install 22 / nvm use 22` recipe, and
notes the Visual Studio 2022 / `vcvars64.bat` requirement on Windows
plus the implicit "any reasonably recent g++/clang++" expectation on
Linux/macOS. Nothing else in the guide changes.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Signed-off-by: jbbqqf <jbaptiste.braun@gmail.com>
@codecov
Copy link
Copy Markdown

codecov Bot commented May 9, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 66.84%. Comparing base (6c79a67) to head (dc6e64c).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #668      +/-   ##
==========================================
- Coverage   66.86%   66.84%   -0.02%     
==========================================
  Files          77       77              
  Lines       11724    11724              
==========================================
- Hits         7839     7837       -2     
- Misses       3885     3887       +2     
Flag Coverage Δ
bdist_linux_311_python 66.59% <ø> (ø)
bdist_linux_312_python 66.58% <ø> (-0.02%) ⬇️
bdist_linux_313_python 66.56% <ø> (-0.04%) ⬇️
bdist_linux_314_python 66.48% <ø> (+0.01%) ⬆️
bdist_linuxarm_311_python 66.61% <ø> (ø)
bdist_linuxarm_312_python 66.59% <ø> (-0.04%) ⬇️
bdist_linuxarm_313_python 66.61% <ø> (+0.01%) ⬆️
bdist_linuxarm_314_python 66.50% <ø> (-0.02%) ⬇️
bdist_mac_311_python 66.74% <ø> (-0.02%) ⬇️
bdist_mac_312_python 66.76% <ø> (ø)
bdist_mac_313_python 66.72% <ø> (-0.04%) ⬇️
bdist_mac_314_python 66.66% <ø> (ø)
bdist_win_311_python 66.77% <ø> (ø)
bdist_win_312_python 66.77% <ø> (ø)
bdist_win_313_python 66.76% <ø> (-0.02%) ⬇️
bdist_win_314_python 66.68% <ø> (ø)
sdist_linux_311_python 66.54% <ø> (ø)
sdist_linux_312_python 66.54% <ø> (ø)
sdist_linux_313_python 66.54% <ø> (ø)
sdist_linux_314_python 66.45% <ø> (ø)
sdist_linuxarm_311_python 66.51% <ø> (-0.05%) ⬇️
sdist_linuxarm_312_python 66.55% <ø> (ø)
sdist_linuxarm_313_python 66.55% <ø> (ø)
sdist_linuxarm_314_python 66.42% <ø> (-0.04%) ⬇️
sdist_mac_311_python 66.65% <ø> (-0.02%) ⬇️
sdist_mac_312_python 66.65% <ø> (-0.02%) ⬇️
sdist_mac_313_python 66.65% <ø> (-0.02%) ⬇️
sdist_mac_314_python 66.54% <ø> (-0.04%) ⬇️
sdist_win_311_python 66.76% <ø> (-0.02%) ⬇️
sdist_win_312_python 66.76% <ø> (-0.02%) ⬇️
sdist_win_313_python 66.76% <ø> (-0.02%) ⬇️
sdist_win_314_python 66.68% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

Development installation: Requirements?

1 participant