# Modernize Nu

Audit the requested code/config scope, not the whole machine.
Review requests are read-only; obtain approval before implementing findings.

## Procedure

1. Record `nu --version`, build features and `experimental_options` from `version`.
   Compare the installed release with the last reviewed release;
   do not assume online docs match it.
2. Read intervening [release notes](https://www.nushell.sh/blog/) and affected command help.
   Use the [book](https://www.nushell.sh/book/) for concepts;
   resolve conflicts with local probes or release-tagged source.
3. Query `scope commands` for relevant `deprecation_info` when supported.
   Match command and flag metadata against actual code,
   not comments or generated text templates.
   Removed commands may no longer appear; check release notes too.
4. Resolve imports, generators, and launch mode before diagnosing startup changes.
   Use `$nu` paths instead of hard-coded Linux paths.
   Keep secrets and real login side effects out of probes.
5. Run [the checker](../scripts/check.mjs) on reviewed, non-secret files.
   Treat its `ok` as a static diagnostic result only,
   not proof of runtime correctness or freedom from deprecations.
6. For every proposed migration, test old and replacement shapes
   against the same tiny fixtures.
   Include success, deliberate failure, missing/empty input, and output types.
   Record version, experimental options, commands, and results;
   delete temporary fixtures afterward.
7. Report confirmed migration, unchanged behavior,
   or unresolved discrepancy with evidence.
   Separate source defects, upstream bugs, expected failures, and harness limitations.
   Do not install upgrades, disable type checks, or rewrite unrelated config automatically.

## Reviewed checkpoint

Nu 0.115.1 on Linux; also reviewed intervening 0.114.1 and 0.115.0 notes.
This is an audit baseline, not a minimum supported version
or a reason to load a feature catalogue.

- [0.114.1](https://www.nushell.sh/blog/2026-07-11-nushell_v0_114_1.html):
  runtime annotation fixes; reproduce type mismatches before changing signatures.
- [0.115.0](https://www.nushell.sh/blog/2026-08-15-nushell_v0_115_0.html):
  structured deprecation metadata; YAML/KDL semantics;
  reserved `$ans`; script arguments and scope changes.
- [0.115.1](https://www.nushell.sh/blog/2026-08-23-nushell_v0_115_1.html):
  semver boolean comparisons, completion behavior, and keybinding merging fixes.

Only investigate a change when the requested scope uses the affected feature.
A newer feature is not automatically a better replacement.

## Verified traps

- On 0.115.1, `--ide-check` can emit Error diagnostics and exit zero.
  The helper parses diagnostics; a raw exit-code gate is insufficient.
- The same IDE mode can omit `str upcase` deprecation warnings
  that normal execution emits.
  Use deprecation metadata and reviewed isolated runtime probes
  as independent checks.
- On 0.115.1, `"not json" | from json` succeeds as a string.
  Use `--strict` when validating an external JSON contract.
- `complete` captures external `stdout`, `stderr`, and `exit_code` in one record.
  A later `$env.LAST_EXIT_CODE` lookup is not a reliable substitute
  across pipelines and failure modes.
- [File and pipe redirection][redirection] differ:
  `o+e> file` versus `o+e>| filter`.
- [Startup configuration](https://www.nushell.sh/book/configuration.html) depends on flags and mode.
  A config-free syntax pass does not validate interactive/login wiring.
- Use `help run`, `help source`, and `help use`
  before changing [script](https://www.nushell.sh/book/scripts.html) invocation.
  Probe pipeline input, top-level statements and `main` argument binding
  instead of assuming equivalence.

[redirection]: https://www.nushell.sh/book/stdout_stderr_exit_codes.html