Skip to content

docs: separate the dev and consumer Node floors - #57

Merged
camcima merged 1 commit into
mainfrom
docs/clarify-node-support-matrix
Aug 19, 2026
Merged

docs: separate the dev and consumer Node floors#57
camcima merged 1 commit into
mainfrom
docs/clarify-node-support-matrix

Conversation

@camcima

@camcima camcima commented Aug 19, 2026

Copy link
Copy Markdown
Owner

Follow-up to #56. Documentation only — no code or config changes.

While cleaning up after #56 merged, a release-it --dry-run surfaced a contradiction waiting for the next release.

The problem

Commit 4c0a23c (July 7, unreleased) carries:

BREAKING CHANGE: minimum supported Node.js is now 22.13 (was 20).

But it only changed two things: the private root package.json and the CI runner version. No published package was touched — all six still declare engines: >=20, and #56 added a compat job that verifies that claim by loading every built bundle on Node 20.

So the next release would announce a consumer-facing break that never happened, while shipping packages that say the opposite.

The resolution

The two floors are both correct, because they describe different audiences:

Where Node Why
Developing this repo ≥ 22.13 pnpm 11 loads node:sqlite, which doesn't exist before 22.13
Consuming a published package ≥ 20 What the built bundles actually need — verified in CI and against real Node 20.19.1

The root package.json is private: true, so its engines never reaches consumers. Raising the packages to match it would drop Node 20 users on a toolchain-parity argument rather than a technical one.

This PR records that reasoning so the mismatch doesn't read as an oversight and get "fixed" later, and adds a release checklist item to strike the stale bullet from the generated CHANGELOG.md before the next release goes out.

Changes

  • CONTRIBUTING.md — a Node versions section explaining the split, and a Releasing section documenting pnpm release / --dry-run plus the one-time changelog note.
  • README.md — the requirements section now distinguishes the consumer floor from the contributor one. The >=20 badge is unchanged and correct.

Verification

  • pnpm format:check and pnpm lint clean.
  • scripts/smoke-test.mjs re-run against real Node 20.19.1 to confirm the >=20 claim still holds.

Also worth a decision (not in this PR)

The same dry run computes the next version as 1.0.0 — conventional-changelog treats the breaking changes from #56 as major even at 0.x. If you'd rather ship 0.3.0, that needs a --preRelease-style override or an explicit version at release time; it isn't something this PR changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MsFZHTnQmAUMjtLUegFRPL

The root package.json requires Node >= 22.13 (pnpm 11 will not run below
that) while the six published packages declare >= 20. That reads like an
oversight, so record why it is not: the root is private and constrains
contributors, the packages describe what their built output needs, and
CI verifies the >= 20 claim by loading every bundle on Node 20.

Also flags a stale changelog entry for whoever cuts the next release.
Commit 4c0a23c carries "BREAKING CHANGE: minimum supported Node.js is
now 22.13 (was 20)", but it only touched the private root and the CI
runner — no published package ever dropped Node 20. Left in place it
would announce a consumer-facing break that never happened, so the
release checklist now says to strike that bullet.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MsFZHTnQmAUMjtLUegFRPL
Copilot AI lite review requested due to automatic review settings August 19, 2026 13:33

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@codecov

codecov Bot commented Aug 19, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (c744492) to head (f32f105).

Additional details and impacted files
@@            Coverage Diff            @@
##              main       #57   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           11        11           
  Lines          695       695           
  Branches       167       167           
=========================================
  Hits           695       695           
Flag Coverage Δ
unit 100.00% <ø> (ø)

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

☔ View full report in Codecov by Harness.
📢 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.

@camcima
camcima merged commit d2dab0f into main Aug 19, 2026
13 checks passed
@camcima
camcima deleted the docs/clarify-node-support-matrix branch August 19, 2026 13:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants