Skip to content

Say what the server-id, value and event name rules actually are - #18

Merged
dmccoystephenson merged 2 commits into
mainfrom
feature/docs-sweep-server-id-and-value
Oct 16, 2026
Merged

dmccoystephenson merged 2 commits into
mainfrom
feature/docs-sweep-server-id-and-value

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Stage A: a documentation accuracy sweep. Every doc source of truth (README sections, class and method Javadoc, pom.xml description, build.yml comment) was checked against TraceClient.java, and three claims were found that did not match the code:

  • README "Resetting it" and the parseServerWideConfig Javadoc: both said a server-id: value may use any of [A-Za-z0-9_.-]. The parser checks the value against TAG_KEY ([A-Za-z0-9][A-Za-z0-9_.\-]*), so the value must also start with a letter or digit. A value like _mine is ignored, and the next start appends a fresh server-id: line (resolveInstallId). Both docs now say this.
  • README "The wire format": said value is omitted only "when not given". json() also drops NaN and ±Infinity. This is now stated.
  • report(String, Double, Map) Javadoc: did not say that a null or blank name sends nothing (the early return in report, already pinned by report_ignoresABlankName). This is now stated.

installId_anExistingServerIdIsUsedAndAnUnusableOneIsIgnored gains assertions that pin the documented server-id rule: a leading _ or - is ignored, and so is a value over MAX_TAG_LENGTH. These are characterization assertions only. No production code changed.

The docs that were checked and found accurate: README example, "What report promises", "Opting out" (not edited), "Server-wide tags", "Getting it" (0.6.1 agrees with pom.xml, the header and VERSION), "Keys" (not edited), "Building" (matches the 8/17/21 matrix), class Javadoc, close() / disabledReason() / Builder.* Javadoc, the pom.xml description, and the build.yml comment.

Skipped issue: #13 (withVersion exceeds MAX_TAGS) was not picked. It changes what is sent on the wire, so it needs a maintainer decision between the options listed in the issue.

Test plan

  • mvn -B verify locally (Java 21): 76 tests run, 0 failures
  • CI matrix build (8), build (17), build (21) green

No tracking issue. The drift was found during a Stage A sweep.

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 October 14, 2026 02:22
The README and parseServerWideConfig Javadoc allowed any server-id made
of [A-Za-z0-9_.-], but the parser also wants a letter or digit first;
the wire-format section said value is only omitted when not given, but
NaN and infinities are dropped too; and report's Javadoc did not say a
null or blank name sends nothing. A test now pins the server-id rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
resolveInstallId appends, so it does not land below the unusable line
unless that line was last.

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

Copy link
Copy Markdown
Member Author

Self-review rubric (CI anchor: run 38534789699 on head 6fecafe; build (8), build (17) and build (21) all succeeded):

  • Scope: PASS. The three files touched each carry one of the three drift fixes, or the assertions that pin one of them. No formatting churn.
  • Tests-new: PASS (n/a). No new public members were added. The new assertions in installId_anExistingServerIdIsUsedAndAnUnusableOneIsIgnored pin the server-id rule the README now states.
  • Tests-fix: n/a. No production behaviour changed. The edits in TraceClient.java are Javadoc only.
  • Sibling structure / renames: PASS (n/a). No new files and no renames.
  • Docs: FAIL → fixed. The first draft said a replacement server-id: is appended "below" the unusable line. resolveInstallId appends with StandardOpenOption.APPEND, so it goes to the end of the file. This was corrected in 6fecafe. After the fix, every Phase 7 row was re-checked.
  • Issue resolution: n/a. This was a Stage A sweep with no tracking issue.
  • CI: PASS. All three matrix legs are green on the PR head.
  • No dependencies / single file / Java 8: PASS. pom.xml is untouched, git ls-files src/main lists only TraceClient.java, and every main-file import is java.*.
  • Never throws / non-blocking / environment seam: PASS. The production code is unchanged apart from comments.
  • Version agreement / opt-out contract: PASS (n/a). No version string, REASON_* constant, ENV_* constant, or "Opting out" row was touched.

Inline notes:

  • README.md:83 — the stated rule matches TAG_KEY ([A-Za-z0-9][A-Za-z0-9_.\-]*) plus the MAX_TAG_LENGTH check in parseServerWideConfig.
  • README.md:227 — matches the !value.isNaN() && !value.isInfinite() guard in json() (already pinned by json_dropsInfiniteValuesAndKeepsFiniteOnes).

Out-of-diff observation: the CI run warns that the ubuntu-latest label moves to Ubuntu 26 from 2026-10-19. No action is needed now, but a red run after that date should be checked against the runner migration first.

Merge gate: none of the touched paths are on the do-not-auto-merge list. Merging is not authorised for this dispatch, so the PR is left open for the maintainer.

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 74ac0f0 into main Oct 16, 2026
3 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