Skip to content

docs: fix cleanup-related inaccuracies in CHANGELOG, managers.md, README#97

Merged
dipto0321 merged 1 commit into
mainfrom
fix/docs/managers-md-cleanup-fixes
Jul 3, 2026
Merged

docs: fix cleanup-related inaccuracies in CHANGELOG, managers.md, README#97
dipto0321 merged 1 commit into
mainfrom
fix/docs/managers-md-cleanup-fixes

Conversation

@dipto0321

Copy link
Copy Markdown
Owner

Summary

Three docs-only inaccuracies introduced alongside the post-upgrade cleanup
feature (PR #56 / issue #41), all surfaced by issue #60:

  1. CHANGELOG.md cited the wrong issue for the native-mutation-commands
    bullet.
    It said "Closes chore(ci): gitignore the local bin/ and coverage.out #40", but chore(ci): gitignore the local bin/ and coverage.out #40 is chore(ci): gitignore the local bin/ and coverage.out — completely unrelated. The preceding
    bullet already closes feat(cleanup): post-upgrade cleanup prompt with version-by-version confirmation #41, so the redundant citation is just dropped
    (rather than double-citing feat(cleanup): post-upgrade cleanup prompt with version-by-version confirmation #41).

  2. docs/managers.md described a fabricated nvm-windows suppression
    note.
    The paragraph claimed the cleanup prompt is suppressed for
    nvm-windows with a specific explanatory message. No such message
    exists in internal/cli/cleanup.go or internal/cli/upgrade.go. In
    reality, the cleanup prompt still runs against nvm-windows — each
    Uninstall() returns ErrNVMWindowsNotImplemented and surfaces that
    via the generic per-candidate "Failed to delete %s: %v" line. The
    Current() call also returns the sentinel, which triggers the
    ForcePerVersion downgrade (bug(cli): Current() failure leaves the active Node version unprotected from cleanup deletion #58), so even --cleanup / --yes /
    cleanup.auto: true fall back to y/N per candidate. The corresponding
    table row also said "prints a clear note" — corrected to describe the
    actual behavior.

  3. docs/managers.md's "Manager not on PATH" failure mode was wrong.
    It said "the cleanup step is skipped entirely; the upgrade itself
    still completes." In reality, detector.ResolveManager returns
    ErrNoManager, and runUpgrade returns immediately at
    internal/cli/upgrade.go:111-114 — the entire upgrade aborts before
    install/migrate/cleanup. Rewritten to match.

  4. README.md and docs/managers.md disagreed about Phase 7. README
    said "Phase 7 ✅" (done); managers.md said "Phase 7 in progress."
    Reconciled by flipping README to "Phase 7 🔧 (in progress)" with a
    pointer at the remaining distribution packaging work (chore(release): finalize GoReleaser config and npm wrapper #17 / chore(release): prepare v1.0.0 release #18),
    and clarifying managers.md's banner so the two are aligned on the
    same definition (cleanup + mutation shipped, distribution outstanding).

Linked issues

Closes #60

Type of change

  • docs — documentation only
  • feat — new feature (MINOR bump)
  • fix — bug fix (PATCH bump)
  • refactor — no behavior change
  • perf — performance improvement
  • test — tests only
  • chore — maintenance / dependency bump
  • ci — CI/CD only
  • build — build system only
  • Breaking change (MAJOR bump) — explain below

Checklist

  • Title follows Conventional Commits (docs(scope): subject)
  • I ran make ci locally and it passes (the change is docs-only; the
    Go pipeline still runs and stays green)
  • I added or updated tests for the change (no test added — the "test"
    for a doc accuracy fix is git grep against the affected code paths,
    which is what verified the new wording matches reality)
  • I updated relevant docs (this PR is the doc update; CHANGELOG.md
    gets a ### Fixed entry under [Unreleased])
  • No new linter warnings (make lint green)
  • If breaking: I documented the migration path in the PR body and
    updated CHANGELOG.md

Screenshots / output

Pre-fix, the CHANGELOG cited an unrelated CI/gitignore issue:

- Per-manager cleanup behavior is documented in
  `docs/managers.md#post-upgrade-cleanup`. Closes #40.

Post-fix (citation dropped; the adjacent bullet already closes #41):

- Per-manager cleanup behavior is documented in
  `docs/managers.md#post-upgrade-cleanup`.

Pre-fix, docs/managers.md claimed a fabricated single-note UX:

For nvm-windows, the upgrade proceeds normally but the cleanup
prompt is suppressed with a note: "nvm-windows cleanup is not yet
implemented — leave the old versions in place or remove them
manually via nvm uninstall <v> from an elevated shell."

Post-fix (describes the real per-candidate failure behavior):

For nvm-windows, the cleanup prompt still runs — it just
operates against a manager whose Uninstall() returns
ErrNVMWindowsNotImplemented for every candidate. Each
per-version Uninstall() call surfaces that sentinel via the
generic "Failed to delete %s: %v" line, so the user sees one
failure per version and can remove them manually via nvm uninstall <v> from an elevated shell. Because Current() also
returns the sentinel, the ForcePerVersion downgrade (see #58)
kicks in — even --cleanup / --yes / cleanup.auto: true will
prompt y/N for each candidate instead of mass-deleting.

Pre-fix, the "Manager not on PATH" failure mode was actively wrong:

Manager not on PATH — the cleanup step is skipped entirely;
the upgrade itself still completes (Install/SetDefault will
have already failed loudly if the manager wasn't there).

Post-fix (matches internal/cli/upgrade.go:111-114):

Manager not on PATHdetector.ResolveManager returns
ErrNoManager, and the entire upgrade command aborts before
reaching install/migrate/cleanup. There's no "cleanup-only
skipped" path; if the upgrade returns, the cleanup either
ran or was opted out of via --no-cleanup.

Pre-fix, README and managers.md disagreed on Phase 7's status
(README said done, managers.md said in progress); both now
reflect the same definition — cleanup + mutation shipped,
distribution packaging (#17 / #18) outstanding.

Files touched

  • CHANGELOG.md — drops the wrong Closes #40 citation; adds a
    ### Fixed entry under [Unreleased] documenting the doc
    refresh with docs: post-upgrade cleanup docs inaccuracies (wrong issue ref, fabricated nvm-windows note, false PATH failure mode, Phase 7 status conflict) #60 reference.
  • docs/managers.md — replaces the fabricated nvm-windows
    suppression-note paragraph with the real per-candidate failure
    behavior; corrects the "Manager not on PATH" failure-mode
    description; reconciles the Phase 7 status banner with README;
    updates the nvm-windows table row to describe the actual
    ErrNVMWindowsNotImplemented behavior instead of "prints a
    clear note."
  • README.md — flips the Phase 7 row from "✅" to "🔧 (in
    progress)" with a pointer at the remaining distribution work
    so the two docs agree.

Four doc inaccuracies surfaced by issue #60:

- CHANGELOG.md cited Closes #40 (unrelated chore(ci): gitignore) for
  the native-mutation-commands bullet; the citation is dropped because
  the preceding bullet already closes #41.
- docs/managers.md described a fabricated nvm-windows cleanup
  suppression message that doesn't exist in code. Replaced with the
  real behavior: the cleanup prompt still runs, each Uninstall()
  surfaces ErrNVMWindowsNotImplemented via the generic per-candidate
  failure line, and the ForcePerVersion downgrade (#58) prevents
  mass-deletion even with --cleanup / --yes / cleanup.auto: true.
  Same fix applied to the corresponding table row.
- docs/managers.md's "Manager not on PATH" failure mode claimed the
  upgrade still completes and only cleanup is skipped; reality is
  ResolveManager returns ErrNoManager and runUpgrade aborts at
  upgrade.go:111-114 before install/migrate/cleanup.
- README's "Phase 7 done" line disagreed with managers.md's
  "Phase 7 in progress" banner. Reconciled by flipping README to
  "Phase 7 in progress" and clarifying both refer to distribution
  packaging (#17 / #18) being outstanding while cleanup + mutation
  have shipped.

Closes #60
@cocogitto-bot

cocogitto-bot Bot commented Jul 3, 2026

Copy link
Copy Markdown

✔️ dcebccc - Conventional commits check succeeded.

@dipto0321 dipto0321 merged commit e94dfb5 into main Jul 3, 2026
10 checks passed
@dipto0321 dipto0321 deleted the fix/docs/managers-md-cleanup-fixes branch July 3, 2026 06:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant