Skip to content

Say where a hand-set server-id counts, and when a count goes untagged - #46

Merged
dmccoystephenson merged 2 commits into
mainfrom
feature/readme-server-id-and-count-tag-drift
Nov 12, 2026
Merged

dmccoystephenson merged 2 commits into
mainfrom
feature/readme-server-id-and-count-tag-drift

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Stage A — documentation accuracy sweep. Two README claims were found to drift from TraceClient.java; both are corrected here, in sections that are not on the do-not-auto-merge list.

Summary

  • "Every event carries a random server ID" → Resetting it: the paragraph did not say that only a server-id: line at column 0, outside the tags: block, is read (SERVER_ID_LINE is anchored at ^, and parseServerWideConfig treats indented lines in a tags: block as tags), nor that a quoted value is accepted (scalar() unquotes it), nor that the first valid line wins. An operator who indented the line would have seen a fresh ID appended with no explanation. Each claim is already pinned in TraceClientTest ("column 0 only", the tags: / server-id: x case, server-id: "abc-123" # mine, first/second).
  • "The wire format": the text said the count of a coalesced event always carries coalesced. withCount skips the tag when the event already carries MAX_TAGS (32) tags, as the "Repeated events are coalesced" section already says. The wire-format sentence now says the same.

The full sweep also checked the example snippet, the "What report promises" table, "Opting out", "Server-wide tags", "Getting it" (version 0.7.0 agrees with pom.xml, the header and VERSION), "Building" (matches the build.yml matrix 8/17/21), the class and method Javadoc, and the pom.xml description. No further drift was found.

Test plan

  • README-only change; no code or test touched. The anchor (mvn -B verify) validates no file in this diff (UNVERIFIED-not-applicable), and the CI matrix is still expected green on the head.
  • Each new README claim was checked against parseServerWideConfig, scalar, withCount and the existing tests named above.

Deferred issues

Every open issue (#13, #15, #27, #31, #39, #40, #42) was skipped this cycle: each needs a maintainer decision on the opt-out contract, the wire format, or the user-facing "Opting out" wording, all of which are human-gated.

No tracking issue — gap found during triage.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

dmccoystephenson and others added 2 commits November 11, 2026 19:45
The README's "Resetting it" paragraph did not say that only a column-0
server-id: line outside the tags: block is read, nor that a quoted value
is accepted, so an operator who indented the line would see a new ID
appended. "The wire format" said a coalesced count always carries the
coalesced tag, which withCount skips at 32 tags.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric (scored against the diff, CI run 43143677395 and the source):

  • Scope: PASS — git diff --name-only origin/main lists only README.md; both hunks fix the two drifts named in the body.
  • Tests-new: PASS (n/a) — no public method was added.
  • Tests-fix: PASS (n/a) — no bug fix; documentation only.
  • Sibling structure: PASS (n/a) — no new file.
  • Sibling renames: PASS (n/a) — nothing renamed.
  • Docs: PASS — "Resetting it" now matches SERVER_ID_LINE (^server-id\s*:(.*)$, column 0), the inTags branch of parseServerWideConfig (indented lines in a tags: block are tags), scalar() (quoted values unquoted) and the serverId == null guard (first valid line wins). "The wire format" now matches withCount (merged.size() < MAX_TAGS) and agrees with the existing "Repeated events are coalesced" exceptions paragraph.
  • Issue resolution: PASS (n/a) — no Closes #N; the gap was found during the sweep.
  • CI: PASS — build (8), build (17) and build (21) all green on the first head; the follow-up commit is README-only.
  • No dependencies / Single file / Java 8 / Never throws / Non-blocking / Environment seam / Version agreement: PASS (n/a) — pom.xml and src/ are untouched.
  • Opt-out contract: PASS — the "Opting out" and "Keys" sections are untouched.

One finding, fixed in ecae0e6: README.md:85 read "a server-id: line at the start of a line", which was reworded to "a server-id: line that starts at column 0".

Anchor: mvn -B verify validates nothing in this diff (UNVERIFIED-not-applicable); CI is the gate and is green.

This review comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit dcb457b into main Nov 12, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/readme-server-id-and-count-tag-drift branch November 12, 2026 02:48
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