serhiy-bzhezytskyy Track whose court the ball is in
Purpose
A maintainer can reach you on any of several channels, and hand-checking one of them
silently misses the rest. The failure mode is concrete: reporting an issue as "0
comments, untouched" when a committer had commented that day — in a channel you
weren't querying. To answer "is anything waiting on me?" honestly, you have to sweep
all the channels, then compare the last human commenter to yourself to decide
whose turn it is. This ships as a runnable tool (tools/check-status.sh) so the
sweep is complete by construction, not by memory.
Scope note: the tool is wired for Apache Solr / Lucene / Jetty (GitHub + ASF JIRA +
lists.apache.org). The method is general; the specific endpoints and the JIRA/
mailing-list steps are ASF-shaped, hence scope: apache/solr.
When to use
- Any "check status", "whose turn is it", or "anything waiting on me" request.
- Before a stand-up-style summary of open PRs/issues.
- Deciding nudge-vs-wait on a specific thread.
When NOT to use
You already know a specific claim needs proving before you post it — that's verify-before-a-committer-comment; this skill answers whose turn, not is my claim true.
The practice (checklist)
Check all six channels a maintainer can use, plus git diffs as a seventh:
-
- GitHub PR issue-comments —
gh api repos/<repo>/issues/<n>/comments
- GitHub PR issue-comments —
-
- GitHub inline review-comments —
gh api repos/<repo>/pulls/<n>/comments
- GitHub inline review-comments —
-
- GitHub reviews (APPROVE/CHANGES_REQUESTED/COMMENTED) —
gh api repos/<repo>/pulls/<n>/reviews
- GitHub reviews (APPROVE/CHANGES_REQUESTED/COMMENTED) —
-
- Watched-issue comments —
gh api repos/<repo>/issues/<n>/comments
- Watched-issue comments —
-
- ASF JIRA comments (public REST, no auth) —
curl -s https://issues.apache.org/jira/rest/api/2/issue/<KEY>?fields=status,comment
- ASF JIRA comments (public REST, no auth) —
-
- dev@ mailing list — lists.apache.org has a no-auth JSON API
(
stats.lua?list=dev&domain=<d>&d=YYYY-MM); don't punt it to "manual".
- dev@ mailing list — lists.apache.org has a no-auth JSON API
(
-
- git diffs — read the actual
git show <sha>, not just commit messages (the diff often corrects the story the message tells).
- git diffs — read the actual
Whose-court logic: compare the LAST commenter to you — but grade the CONTENT before the actor. Read what the latest message asks for, then decide who wrote it. Both directions of this have already gone wrong:
- Actor counted as content: a commit notice ("ASF subversion and git services", "ASF GitHub Bot") read as a maintainer pinging you, producing a fake TODO.
- Actor overriding content: a bot comment classified as noise while its body addressed you — "When it's ready for review, please add the relevant reviewers: @… or @…". In that house review is routed by the author, so until that ping is posted the PR sits in nobody's queue. The sweep printed "bot noise — no human is waiting" and the verdict was repeated twice before anyone read the sentence.
A bot is a channel, not a sender. CLA bots, DCO bots, rebase bots and reviewer-routing bots all carry author-addressed imperatives inside actor-labelled envelopes. So: grep the last bot body for request verbs ("please add", "relevant reviewer", "action required", "please sign", "please rebase") before conceding noise. Done when you have read the body of the latest message on any artifact you own — whoever wrote it — before repeating a court verdict. The keyword list is a tripwire, not a parser; it will miss a novel phrasing, and the reading is the rule that does not.
Keep the tool's lists current: add every PR/JIRA the moment it opens. A real miss happened because a PR wasn't in the array, so "check status" silently skipped it.
Rationalizations
| Shortcut | Why it fails |
|---|---|
| "No reply — I'll just ping again." | Check whose court it's actually in first; the last human move may be yours, and a nudge on your own turn reads as noise. |
| "GitHub shows no new comment, so it's on them." | A maintainer can reach you on six channels (JIRA, dev@, inline reviews…); one-channel checks reported "0 comments" the day a JIRA comment landed. |
| "A commit notification counts as their reply." | Filter bot authors ("ASF subversion and git services") — a commit notice false-positives as a maintainer ping and flips the court wrongly. |
| "It's from a bot, so nobody is waiting on me." | The opposite error, and the one that actually cost two status reports: github-actions[bot] asked the AUTHOR to add named reviewers, and until that ping was posted the PR was in no one's queue. Grade the content, then the actor — a bot is a channel, not a sender. |
RECEIPT
Runnable tool: tools/check-status.sh (ships in this repo). It exists because a
hand-check missed a real comment: a committer's comment on SOLR-17764 lived only in
ASF JIRA — a channel not being queried — so the status was reported as "0 comments,
untouched" the day the comment landed. The tool sweeps all six channels + git diffs
and prints whose court each item is in.
Two fixes baked in from real misses:
- Bot filter: "ASF subversion and git services" commit notices false-positived as maintainer pings (SOLR-3284) until filtered out.
- List completeness: the #600 comment (2026-07-21) was missed because #600 wasn't in the PR array — hence "add every PR the moment it opens".
This is a JOURNAL receipt (the miss is self-reported, not a maintainer quote), but the tool is a concrete, runnable artifact — strong lived evidence.
Lifecycle
- Signals it worked: no "you missed my comment" surprises; every open thread's court is known before you report status.
- What to log on a misfire: which channel or which un-listed PR/JIRA hid the
comment; add it to the tool's arrays and, if a new channel, to the sweep.
Record it in
LEDGER.md. - Death criterion: retire a channel only if a project abandons it (e.g. moves fully off JIRA or the mailing list); the tool's arrays are meant to be edited.
- Relates to: covers whose-court / turn-tracking across channels and nudge-vs-wait timing (who owes the next move, don't be the Nth watcher), and it ships a tool to sweep the channels.