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​

PackageLineUpgrade rule
@nudojs/core2.x (stable SemVer line)SemVer: breaking → major
@nudojs/service2.x (stable SemVer line)SemVer: breaking → major
@nudojs/cli2.x (stable SemVer line)SemVer: breaking → major
@nudojs/parser0.xMinor may break — read CHANGELOG
@nudojs/lsp0.x (0.8.0 pre-1.x)Minor may break. 1.x gate: observe freeze via packages/lsp/PUBLIC_API.md — no automatic bump
@nudojs/env / @nudojs/harvester0.x (0.3.0 / 0.2.5)Minor may break; pin a minor for stable IDE/CI analysis. Handwritten env wins on overlapping modules/exports (mergeHarvestUnderEnv)
nudojs (npm shell)0.xPrefer @nudojs/cli / @nudojs/core directly
vite-plugin-nudo0.xMinor may break
nudo-vscodeMarketplaceFollow extension release notes

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.3.0 (pre-1.0)workspace / ~0.3.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.2.5 (pre-1.0)workspace / ~0.2.5Harvest 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 / InferJson / 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 1.x service/cli — 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 (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/lsp@0.8.0
# read node_modules/@nudojs/lsp/CHANGELOG.md for BREAKING bullets

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.

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.0.1" } }

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

// 0.x: only take patches automatically
{ "dependencies": { "@nudojs/lsp": "~0.8.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 still follows the 0.x table above. VS Code packaging checklist: repo packages/vscode/RELEASE_CHECKLIST.md. LSP freeze inventory: repo packages/lsp/PUBLIC_API.md.

See also​