layer5io / layer5io/sistent

Node version support is stated in three places and wrong in all of them (README, copilot-instructions, workflows)

Open
#1,751 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
137
Forks
239
Avg merge
4d 14h
Merged PRs (30d)
5

Description

Current Behavior

Two docs each state the supported Node versions, and both contradict the workflows:

Source Claim
README.md:19 "Make sure you have npm on node@16 and above. The CI workflows checks for in node@16, node@18 and node@20"
.github/copilot-instructions.md:23 "Current CI runs the main checks on Node 20 and 22"
.github/workflows/node-checks.yml:18 (actual) node-version: [22, 24]

Neither doc names a version the main checks actually run on. node@16 and node@18 have both
been end-of-life for some time, so a new contributor following the README can set up an environment
no workflow covers and hit failures the project never sees.

The rest of the workflows are not aligned with each other either, which is worth settling in the
same pass:

Workflow Node
node-checks.yml (lint, build, test) [22, 24]
release.yml:64 (publish) 24
test-meshery-integration.yml:25 22
notify-dependents.yml (4 jobs) 22

package.json has no engines field, so nothing declares the supported range to consumers either.

Expected Behavior

One authoritative statement of the supported Node versions, with everything else pointing at it
rather than restating it.

Suggested fix
  1. Add an engines.node field to package.json reflecting what CI actually verifies. That is the
    machine-readable source of truth, and it is the only one npm can enforce for consumers.
  2. Reduce README.md and .github/copilot-instructions.md to a pointer at engines and
    node-checks.yml instead of restating the matrix. Two docs independently restating the same CI
    matrix is precisely how this drifted three ways.
  3. Decide whether the 22 used by test-meshery-integration.yml and notify-dependents.yml should
    track the node-checks.yml matrix, or is deliberately pinned - and say which, in a comment.
Context

Surfaced by the documentation step of a local validation pipeline while reviewing an unrelated
permission-keys/type-surface change (see #1749 for the other follow-up from that same review). It
was deliberately left out of that PR to keep it scoped; filing here so the fact does not stay wrong
in three places.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with package.json and compare its missing engines field against node-checks.yml, release.yml, test-meshery-integration.yml, and notify-dependents.yml. Then update README.md and .github/copilot-instructions.md to point to the authoritative sources. Done means the supported Node range is declared once, documentation no longer duplicates stale values, and any deliberate workflow pinning is explained in a comment.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, node.js
Domain
build-system, ci-cd, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.