Skip to content

Say what an upgrade does not reach, and what to run about it - #695

Merged
MongLong0214 merged 1 commit into
mainfrom
docs-693-upgrade-doctor
Aug 15, 2026
Merged

Say what an upgrade does not reach, and what to run about it#695
MongLong0214 merged 1 commit into
mainfrom
docs-693-upgrade-doctor

Conversation

@MongLong0214

Copy link
Copy Markdown
Owner

Toward #693 — the half that does not require touching the install path again.

An upgrade updates the CLI and reaches neither:

  • hooks already installed in a repositoryhooks install records the exact
    bundle it ran from, pinning that repository to one release
  • sessions already running — a host loads its runtime once and keeps it

Both show up in doctor, and neither was written down anywhere. A user meeting
those 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 bin wrapper instead, and hooks then failed under the
restricted PATH a hook actually runs in —

outcome: the hook exited 1 under the restricted PATH —
         commitlore: cannot find the CLI this hook was installed with.

The recorded path exists to be independent of PATH, and commitlore.node is
recorded beside it because a hook runs where PATH may carry no node. A shell
wrapper undoes both. Three local reproductions passed before CI caught it,
because my PATH had node in 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.

@github-actions

github-actions Bot commented Aug 15, 2026

Copy link
Copy Markdown

CommitLore — record lint

Trailers: clean — 1 commit in origin/main..55e6dc7b50bd7bc0936b0d3422ecf7f2c1fe42f7
Active constraints: not read — commitlore: git log --follow accepts exactly one pathspec, so renames are not followed for 2 paths; query one path at a time to follow its rename chain (2 changed paths)

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
MongLong0214 force-pushed the docs-693-upgrade-doctor branch from c530e1d to 55e6dc7 Compare August 15, 2026 15:30
@MongLong0214
MongLong0214 merged commit a987a7a into main Aug 15, 2026
12 checks passed
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