Skip to content

docs(watch): correct the three (#683) source comments (#988) - #989

Open
fujibee wants to merge 1 commit into
mainfrom
fix/988-watch-sh-683-comments
Open

docs(watch): correct the three (#683) source comments (#988)#989
fujibee wants to merge 1 commit into
mainfrom
fix/988-watch-sh-683-comments

Conversation

@fujibee

@fujibee fujibee commented Aug 25, 2026

Copy link
Copy Markdown
Owner

Fixes #988. Follow-up to #987, which corrected the (#683) tags in tests/. The same miscitation survived in three scripts/watch.sh comments — and a source comment is read by the person about to change that code, so a wrong pointer there costs more than a wrong test name.

#683 is "Per-team migration copies a global read cursor without preserving its sequence floor" — read-cursor migration. Each comment was checked one at a time against that subject; keeping the tag was an allowed outcome (the goal is that every remaining #683 be correct, not that there be none). None of the three is about cursor migration:

line comment subject verdict
279 the sharing warning for two unfiltered watchers on unclaimed pairs not migration, not the claim-race, no matching issue → tag removed
550 the held-pair set that de-duplicates departure/return announcements ("said" = announced, not read) bookkeeping, not migration, no matching issue → tag removed
626 a stale process consuming a message for a pair another session claimed the #983 hazard — this comment sits on the FIRST actas_lock_state check, and #983 is the still-open window BETWEEN that check and the later fetch. It names the hazard; it does not close it → retagged (#983)

Comments only — no code changes. bash -n clean, enforced-assertions at baseline. (#983 remains open; nothing here fixes it.)

Why one wrong number is worth this much care

The genealogy of this single miscitation — traced by git log -S to the introducing commits — is the whole argument:

one wrong (#683) on watcher-series commit subjects
  e3844c2 (subject did not even cite it; the tag was added to the body later)
  e4db061  "step aside while a pair is held … (#683)"      → CHANGELOG L275
  be48ecf  "release a pair another session has claimed (#683)" → CHANGELOG L276

lands in three kinds of place:

fixable not fixable
tests/ tags — done (#987, landed) git history: (#683) is in the squash-merge commit subjects, immutable
scripts/ comments — this PR published CHANGELOG.md L274–276, regenerated by git-cliff from those subjects (a hand edit reverts next release)
published release notes / distributed tarballs

Three people reached "L550 is not #683" by independent routes (the code de-dups announcements, not reads; no independent evidence it was ever judged #683; its tag descends straight from a miscited subject). The point of the asymmetry: a single wrong issue number is cheap to write and, once it rides a squash merge and a release, impossible to take back.

#987 fixed the (#683) tags in tests/; the same miscitation survived in three
scripts/watch.sh comments. #683 is "Per-team migration copies a global read cursor
without preserving its sequence floor" -- read-cursor migration. Each of the three
was compared, one at a time, against that subject; keeping the tag was an allowed
outcome, but none of the three is about cursor migration:

- L279 "Say when this watcher is sharing an inbox with another" -- the sharing
  WARNING for two unfiltered watchers on unclaimed pairs. Not migration, and not
  the claim-race either; no issue states this behaviour, so the tag is removed.
- L550 "it only records what has already been said" -- the held-pair set that
  de-duplicates the departure/return announcements ("said" = announced, not read).
  Bookkeeping, not migration; no matching issue, so the tag is removed.
- L626 "the message is gone, delivered to a stream nobody is reading" -- a STALE
  process consuming a message for a pair ANOTHER SESSION has claimed. That is the
  #983 HAZARD ("watch.sh consumes a message for a role claimed between the lock
  read and the fetch"). This comment sits on the FIRST actas_lock_state check;
  #983 is the still-open window BETWEEN that check and the later fetch, so the
  comment NAMES the hazard -- it does not close the issue. Retagged (#983).

Comments only -- no code changes. CHANGELOG.md and the git history are left alone
on purpose: cut-release.sh regenerates the changelog from Conventional-Commit
subjects (a hand edit reverts at the next release), both are released history, and
the squash-merge subject that carries (#683) is immutable.
@fujibee
fujibee force-pushed the fix/988-watch-sh-683-comments branch from 39fb613 to 8bb01cb Compare August 25, 2026 07:20
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.

(#683) miscitation survives in source comments outside tests/

1 participant