Skip to content

docs: consolidate nodeup.md into README and remove the standalone design doc#9

Merged
dipto0321 merged 1 commit into
mainfrom
chore/consolidate-nodeup-md
Jun 29, 2026
Merged

docs: consolidate nodeup.md into README and remove the standalone design doc#9
dipto0321 merged 1 commit into
mainfrom
chore/consolidate-nodeup-md

Conversation

@dipto0321

Copy link
Copy Markdown
Owner

Summary

Removes the internal nodeup.md design doc (1145 lines, 1 commit ever since
scaffolding) and consolidates the user-facing bits into README.md. Then
strips the now-dangling nodeup.md §X references from source, config, docs,
and issue templates so a grep nodeup.md against the tracked tree returns
nothing.

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

  • New "Compatibility notes" subsection after Features. Covers:
    • nvm is a shell function (sourced transparently)
    • Multi-manager install → user is prompted the first time
    • System Node (Homebrew/apt/Windows installer) is detected but cannot
      be upgraded
    • Bundled packages (npm, corepack, npx) are always skipped
      during migration
    • Native addons may need npm rebuild -g after a major Node bump
    • Concurrent runs blocked via ~/.nodeup/nodeup.lock; mid-upgrade
      crash leaves a snapshot that can be restored
  • Expanded Contributing. Was a 5-line TL;DR; now covers:
    • Full branch-type list (feat, fix, chore, docs, ci,
      test, refactor)
    • Commit type enum (matches commitlintrc.yml exactly)
    • Commit scope enum (detector, manager, packages, node,
      config, ui, platform, cli, deps, release, ci,
      docs, lint)
    • Breaking-change convention (! marker + BREAKING CHANGE: footer)
    • Squash-merge + delete-branch + tag-driven release
  • Removed the 3 dangling See [\nodeup.md`](./nodeup.md)` links.

CHANGELOG.md

  • New Unreleased / Changed entry describing the consolidation.
  • v0.0.0 entry rewritten to describe the blueprint by topic rather
    than by filename (since the file is gone).

Source / config / docs / templates

All updated to drop See nodeup.md §X cross-refs:

  • internal/cli/{config,version,check,list,upgrade,packages}.go — 6 files
  • internal/detector/{fnm,nvm,volta,asdf,detector}.go — 5 files
  • docs/managers.md, docs/configuration.md
  • .commitlintrc.yml (2 comments)
  • .goreleaser.yaml (1 trailing comment)
  • .github/ISSUE_TEMPLATE/feature_request.md (replaced the
    back-link with the explicit out-of-scope list inline)

nodeup.md

Deleted. .gitignore already lists it, so this is belt-and-suspenders
for anyone cloning from a commit before this PR.

Why now

nodeup.md was useful as scaffolding scaffolding — Phase 0 (repo
foundation) 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.yaml
configs, or has been superseded by CHANGELOG.md. The doc had become
a maintenance liability (any cross-ref update had to touch 11+
files) without adding user value beyond what README.md could 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 in CHANGELOG.md (intentional historical references) and .puku/plans/... (Puku's internal plans, gitignored)
  • YAML files parse: .commitlintrc.yml, .goreleaser.yaml
  • Commit message validated against .commitlintrc.yml: type docs
    is in type-enum, subject 76 chars (≤ 100), no scope, body lines
    all ≤ 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.go and the deleted file
itself.

Rollback

git revert 7aaf6e7 brings nodeup.md back unchanged.

…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.
@cocogitto-bot

cocogitto-bot Bot commented Jun 29, 2026

Copy link
Copy Markdown

✔️ 7aaf6e7 - Conventional commits check succeeded.

@dipto0321 dipto0321 merged commit 6d49cd8 into main Jun 29, 2026
10 checks passed
@dipto0321 dipto0321 deleted the chore/consolidate-nodeup-md branch June 29, 2026 14:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant