Say what an upgrade does not reach, and what to run about it - #695
Merged
Conversation
CommitLore — record lintTrailers: clean — 1 commit in Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR. |
An upgrade updates the CLI and reaches neither hooks already installed in a repository nor sessions already running. Both are visible in doctor and neither was written down, so a user meeting the warnings had no way to know they were expected rather than broken. The hook records the exact bundle it ran from, which pins that repository to one release, and the installer cannot fix it -- it has no way to know which repositories have hooks. That limit is stated rather than worked around. Also records why the version is there at all, because the obvious repair is wrong and was tried: recording the bin wrapper instead made hooks fail under the restricted PATH a hook actually runs in. The recorded path exists to be independent of PATH, and the interpreter is recorded beside it for the same reason. A version-free path that keeps both properties needs a stable directory the installer maintains, which is #693's remaining work rather than something to improvise. Limit: an upgrade cannot reach a repository's hooks or a running session Blast: system Undo: easy Certainty: firm Provenance: authored Record-Id: r-693docs
MongLong0214
force-pushed
the
docs-693-upgrade-doctor
branch
from
August 15, 2026 15:30
c530e1d to
55e6dc7
Compare
This was referenced Aug 16, 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.
Toward #693 — the half that does not require touching the install path again.
An upgrade updates the CLI and reaches neither:
hooks installrecords the exactbundle it ran from, pinning that repository to one release
Both show up in
doctor, and neither was written down anywhere. A user meetingthose warnings had no way to know they were expected rather than broken.
Why the version is in the recorded path
The obvious repair is wrong, and it was tried rather than reasoned about:
#694 recorded the
binwrapper instead, and hooks then failed under therestricted
PATHa hook actually runs in —The recorded path exists to be independent of
PATH, andcommitlore.nodeisrecorded beside it because a hook runs where
PATHmay carry nonode. A shellwrapper undoes both. Three local reproductions passed before CI caught it,
because my
PATHhadnodein it.A version-free path that keeps those properties needs a stable directory the
installer maintains — no such directory exists today, and creating one touches
install.sh, uninstall, and Windows symlink behaviour. That stays in #693.Why documentation rather than the fix
Six defects came out of the install and distribution path today, one of them mine
from an hour ago. v1.0.1 just shipped and its four controls all inverted. There
is no user-facing reason to reopen that path tonight, and the limit is real
enough to be worth stating either way — the installer genuinely cannot know which
repositories have hooks.
Documentation only; no code, no artifact change.