docs: consolidate nodeup.md into README and remove the standalone design doc#9
Merged
Merged
Conversation
…ign doc The internal nodeup.md blueprint served its purpose during initial scaffolding and the Phase 1 detector rollout, but is no longer needed as a tracked file. Its useful user-facing content (compatibility notes, commit conventions, branching rules) now lives in README.md, and its internal-only content (architecture diagrams, CI YAML, scoped decision matrices) is either in code comments, in the .commitlintrc.yml / .goreleaser.yaml configs themselves, or has been superseded by CHANGELOG.md. Changes: - README.md: add 'Compatibility notes' subsection (nvm shell function, multi-manager prompt, system-Node detection, skip list, native addon rebuild, lock file); expand Contributing with full branch-type list, commit type/scope enums, and the breaking-change convention; remove the 3 dangling 'See nodeup.md' references. - CHANGELOG.md: add Unreleased 'Changed' entry for the consolidation; rewrite the v0.0.0 entry to describe what the blueprint covered (without back-linking the deleted file). - internal/cli/*.go and internal/detector/*.go: replace 11 '// See nodeup.md §X' doc comments with package-local pointers (typically 'see internal/detector/detector.go for the Manager interface contract'). - docs/managers.md, docs/configuration.md: strip the two 'See nodeup.md §X' cross-refs at the bottom. - .commitlintrc.yml: rewrite the two comments that pointed at nodeup.md §12 to be self-contained. - .goreleaser.yaml: drop the 'See nodeup.md §15' trailing comment. - .github/ISSUE_TEMPLATE/feature_request.md: replace the 'see nodeup.md §3' link with the explicit out-of-scope list (.nvmrc management, npm self-update, yarn/pnpm globals, self-update). - nodeup.md: removed. .gitignore already lists it, so this is belt-and-suspenders for users who clone from a commit before this change. No code behavior changes. Verified: go build, go vet, go test -race, and GOOS=windows go build/vet all clean.
|
✔️ 7aaf6e7 - Conventional commits check succeeded. |
This was referenced Jun 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Removes the internal
nodeup.mddesign doc (1145 lines, 1 commit ever sincescaffolding) and consolidates the user-facing bits into
README.md. Thenstrips the now-dangling
nodeup.md §Xreferences from source, config, docs,and issue templates so a
grep nodeup.mdagainst the tracked tree returnsnothing.
This is pure housekeeping — no code behavior changes, no public API changes,
no CI changes. The user-facing surface of the tool is identical; the README
just covers a few previously-implicit things that the blueprint used to
spell out (compatibility notes, full commit scopes enum, breaking-change
convention).
Changes
README.md
nvmis a shell function (sourced transparently)be upgraded
npm,corepack,npx) are always skippedduring migration
npm rebuild -gafter a major Node bump~/.nodeup/nodeup.lock; mid-upgradecrash leaves a snapshot that can be restored
feat,fix,chore,docs,ci,test,refactor)commitlintrc.ymlexactly)detector,manager,packages,node,config,ui,platform,cli,deps,release,ci,docs,lint)!marker +BREAKING CHANGE:footer)See [\nodeup.md`](./nodeup.md)` links.CHANGELOG.md
Unreleased / Changedentry describing the consolidation.than by filename (since the file is gone).
Source / config / docs / templates
All updated to drop
See nodeup.md §Xcross-refs:internal/cli/{config,version,check,list,upgrade,packages}.go— 6 filesinternal/detector/{fnm,nvm,volta,asdf,detector}.go— 5 filesdocs/managers.md,docs/configuration.md.commitlintrc.yml(2 comments).goreleaser.yaml(1 trailing comment).github/ISSUE_TEMPLATE/feature_request.md(replaced theback-link with the explicit out-of-scope list inline)
nodeup.mdDeleted.
.gitignorealready lists it, so this is belt-and-suspendersfor anyone cloning from a commit before this PR.
Why now
nodeup.mdwas useful as scaffolding scaffolding — Phase 0 (repofoundation) and Phase 1 (detector surface, now complete) referenced it
extensively because there was no other home for the rationale. After
PR #8 landed (8/8 managers merged), every section of the blueprint is
either in the code itself, in the
.commitlintrc.yml/.goreleaser.yamlconfigs, or has been superseded by
CHANGELOG.md. The doc had becomea maintenance liability (any cross-ref update had to touch 11+
files) without adding user value beyond what
README.mdcould carry.Verification
go build ./...✅go vet ./...✅go test -race ./...✅ (all existing tests still pass)GOOS=windows go build ./...✅GOOS=windows go vet ./...✅grep -rn "nodeup\.md" --include="*.md" --include="*.go" --include="*.yml" --include="*.yaml" .— only matches inCHANGELOG.md(intentional historical references) and.puku/plans/...(Puku's internal plans, gitignored).commitlintrc.yml,.goreleaser.yaml✅.commitlintrc.yml: typedocsis in
type-enum, subject 76 chars (≤ 100), no scope, body linesall ≤ 100 chars, no trailing period.
Risk
Effectively zero. Pure docs/comment edits plus file removal. No
production code paths touched. The only runtime surface in the diff is
a reworded comment in
internal/cli/version.goand the deleted fileitself.
Rollback
git revert 7aaf6e7bringsnodeup.mdback unchanged.