Skip to main content

Versioning & Releases

Nudo is a pnpm monorepo that publishes per-package versions via changesets. The monorepo root version is private and is not a publish unit.

Package lines​

Versions below are the published lines at the time of writing — check npm view <pkg> version for the current one. The line (0.x vs 1.x+) is the stable part; the exact patch number will always move.

PackageLineUpgrade rule
@nudojs/core1.x(1.20.1)SemVer: breaking → major
@nudojs/service1.x(1.12.3)SemVer: breaking → major
nudojs1.x(1.9.3)SemVer: breaking → major
@nudojs/parser1.x(1.5.11)SemVer: breaking → major. 2.0.0 was published by mistake and withdrawn; the planned breaking release will land as an explicitly confirmed major (see the gate note under Changesets)
@nudojs/lsp1.x(1.10.3)SemVer: breaking → major. Freeze inventory: packages/lsp/PUBLIC_API.md
@nudojs/env / @nudojs/harvester0.x(0.5.11 / 0.6.3)Minor may break; pin a minor for stable IDE/CI analysis. Handwritten env wins on overlapping modules/exports (mergeHarvestUnderEnv)
vite-plugin-nudo0.x(0.7.4)Minor may break
nudo-vscodeMarketplaceFollow extension release notes; align bundled lsp before packaging (packages/vscode/RELEASE_CHECKLIST.md)

0.x in one sentence​

0.x.y patches are safe; 0.(x+1).0 minors may contain breaking changes. Pin exact versions in CI if you need bit-stable diagnostics.

1.x in one sentence​

Patches fix soundness (results may get more correct); minors add APIs/codes/flags; majors remove or rename public surfaces.

Full policy (what Nudo treats as breaking): docs/versioning.md in the repo.

Ecosystem packages (@nudojs/env / @nudojs/harvester)​

Authoritative long form lives in repo docs/versioning.md § Ecosystem packages. This section is the consumer-facing summary.

PackageCurrentPin styleNotes
@nudojs/env0.5.11 (pre-1.0)workspace / ~0.4.0 for bit-stable IDE/CI analysisNew Abs modules (e.g. events / stream / querystring) ship as minor; signature display may change. Handwritten env wins over harvest on overlapping modules/exports.
@nudojs/harvester0.6.3 (pre-1.0)workspace / ~0.6.3Harvest is a side channel — not the type-system source of truth. Budget defaults: maxFiles=12, maxMs=2500, disable via NUDO_HARVEST_NODE=off.

Rules:

  • Handwritten @nudojs/env wins over harvest / auto-harvest when both supply the same module key or export name. Analysis injects via mergeHarvestUnderEnv in @nudojs/service; harvest only fills missing slots. Changing that priority is service-breaking.
  • Coverage reports (pnpm run coverage:env → docs/reports/env-coverage-baseline.*) are optional release-notes content, not a soundness gate. Prefer leaf-clean counts over raw resolved ratios.
  • Production bare-import harvest injects through abs-modules-graph / harvest-to-abs (bareSpecToAbsModules). autoHarvestModules remains a library helper for programmatic harvest, not a second analysis path.

What usually breaks​

  • Removing package export subpaths
  • CheckJson / CaseJson / generated .d.ts schema or shape changes
  • Renaming diagnostic codes or flipping default severity
  • Removing CLI flags or changing analysis defaults without an escape hatch
  • Default analysis.mode flip (directives → exports in fix-2): intentional on the stable service/cli line — escape hatch package.json#nudo.analysis.mode; treat as major in release notes
  • Directive grammar / sidecar binding-key changes
  • Class-method / export-alias sidecar keys use the local declaration name (Local.method for export { Local as Public }), not the public export alias
  • Removing LSP nudo.* commands or custom requests

Non-breaking: new diagnostic codes, new optional package.json#nudo keys, more precise inference, new CLI flags with safe defaults.

Following releases​

Each published package ships a CHANGELOG.md maintained by changesets. Breaking entries are prefixed **BREAKING**: and include a one-line migration.

Example (@nudojs/core 1.0.0): evaluator subpath moved from @nudojs/cli/evaluator to @nudojs/service/evaluator.

# after a minor bump on a 0.x package
npm i @nudojs/env@0.4.1
# read node_modules/@nudojs/env/CHANGELOG.md for BREAKING bullets

Docs versioning​

The site documents main — the announcement bar shows which package versions that corresponds to (read from packages/*/package.json at build time), and the table above is generated from the same source. Per-package release history: Releases and each package's CHANGELOG.md.

Versioned docs (/docs/<version>/… snapshots) stay off for the 1.x line: nudojs / @nudojs/service / @nudojs/parser still move in lockstep, every snapshot would double the en/zh mirror plus the docs-as-code gates that keep it honest, and the announcement bar already answers "which versions does this page describe". The revisit trigger is concrete — the first 2.0, or the first release where the published CLI and service lines diverge. Until then, pin package versions (table above) when you need bit-stable behaviour.

Changesets (contributors)​

pnpm exec changeset

Pick packages + bump type, then write a short who breaks / how to migrate summary. CI on main runs changeset version → publish → docs/VS Code packaging.

Major bumps are fail-closed​

Publishing an unpublished major version (any 2.x+ version, a major jump, or a first 1.0.0) is blocked by scripts/gate-major.mjs until someone re-runs the Release workflow via workflow_dispatch with confirm_major=true. That dispatch is a human decision — CI, bots, and coding agents must never set confirm_major/CONFIRM_MAJOR on their own to get a green run; a red Release run in this state means "waiting for a maintainer", not "broken". The only exemption is a version that already has its release git tag (a previously published version re-attempted by a changeset-free push — a no-op).

SituationBump
0.x package, breakingminor
0.x package, fix/additivepatch
1.x package, API/schema breakmajor
1.x package, additiveminor
1.x package, soundness fixpatch (note result changes)

Pinning recipes​

// reproducible CI
{ "dependencies": { "@nudojs/core": "1.2.0" } }

// 1.x: track compatible fixes
{ "dependencies": { "@nudojs/core": "^1.2.0" } }

// 0.x: only take patches automatically
{ "dependencies": { "@nudojs/env": "~0.4.0" } }

IDE extensions​

VS Code (wmzy.nudo-vscode) and Zed (nudojs/nudo-zed) bundle or resolve @nudojs/lsp. Extension release notes are the source of truth for editor-facing changes; the language server follows the stable 1.x SemVer line above. VS Code packaging checklist: repo packages/vscode/RELEASE_CHECKLIST.md. LSP freeze inventory: repo packages/lsp/PUBLIC_API.md.

See also​