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> versionfor the current one. The line (0.x vs 1.x+) is the stable part; the exact patch number will always move.
| Package | Line | Upgrade rule |
|---|---|---|
@nudojs/core | 1.x(1.20.1) | SemVer: breaking → major |
@nudojs/service | 1.x(1.12.3) | SemVer: breaking → major |
nudojs | 1.x(1.9.3) | SemVer: breaking → major |
@nudojs/parser | 1.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/lsp | 1.x(1.10.3) | SemVer: breaking → major. Freeze inventory: packages/lsp/PUBLIC_API.md |
@nudojs/env / @nudojs/harvester | 0.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-nudo | 0.x(0.7.4) | Minor may break |
nudo-vscode | Marketplace | Follow 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.
| Package | Current | Pin style | Notes |
|---|---|---|---|
@nudojs/env | 0.5.11 (pre-1.0) | workspace / ~0.4.0 for bit-stable IDE/CI analysis | New Abs modules (e.g. events / stream / querystring) ship as minor; signature display may change. Handwritten env wins over harvest on overlapping modules/exports. |
@nudojs/harvester | 0.6.3 (pre-1.0) | workspace / ~0.6.3 | Harvest 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/envwins over harvest / auto-harvest when both supply the same module key or export name. Analysis injects viamergeHarvestUnderEnvin@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).autoHarvestModulesremains a library helper for programmatic harvest, not a second analysis path.
What usually breaks
- Removing package export subpaths
CheckJson/CaseJson/ generated.d.tsschema or shape changes- Renaming diagnostic codes or flipping default severity
- Removing CLI flags or changing analysis defaults without an escape hatch
- Default
analysis.modeflip (directives→exportsin fix-2): intentional on the stable service/cli line — escape hatchpackage.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.methodforexport { 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).
| Situation | Bump |
|---|---|
| 0.x package, breaking | minor |
| 0.x package, fix/additive | patch |
| 1.x package, API/schema break | major |
| 1.x package, additive | minor |
| 1.x package, soundness fix | patch (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.