Skip to content

Bring three Javadocs up to the fail-closed opt-outs - #52

Merged
dmccoystephenson merged 1 commit into
mainfrom
feature/javadoc-fail-closed-drift
Nov 20, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
feature/javadoc-fail-closed-drift

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

Stage A documentation accuracy sweep. Every documentation source of truth was checked against the code: the README tables, the class Javadoc, the method Javadoc, pom.xml and build.yml. The only drift found is three comments in TraceClient.java that were not updated when #51 made every opt-out fail closed (0.8.0):

  • ENV_USAGE_REPORTING / ENV_DO_NOT_TRACK: these listed only the values that turn reporting off (off, false, 0, no and 1, true, yes). Under 0.8.0, any non-blank value outside the "keep reporting" set turns reporting off (environmentSaysOff). The Javadoc now says that, in the same words as the class Javadoc and the README "Opting out" table.
  • Builder.serverWideConfig: this said the file "honours enabled: false (or off, 0, no)". parseServerWideConfig now disables on any enabled: value other than true/on/yes/1, and readServerWideConfig returns UNREADABLE (disabled) for a file that is there but cannot be read. Both are now stated.
  • ServerWideConfig.NONE: the comment said it covers a file that "could not be read". Since 0.8.0 that case is UNREADABLE. NONE covers: no file asked for, the environment opted out first, or a missing file that could not be created or whose path could not be represented.

Only comments change. The behaviour, wire format, REASON_*/ENV_* values, and README are untouched. The README was checked and already matches the code.

Open issues not picked this cycle

Test plan

  • mvn -B verify locally: 123 tests run, 0 failures (comment-only change)
  • CI matrix build (8), build (17), build (21) green

No tracking issue: the gap was found during the triage docs 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

0.8.0 made every switch fail closed, but three comments still describe
the old lists of values that turn reporting off: the ENV_USAGE_REPORTING
and ENV_DO_NOT_TRACK constants, Builder.serverWideConfig, and
ServerWideConfig.NONE (an unreadable file is now UNREADABLE, not NONE).
They now say what disabledReason(Builder) and parseServerWideConfig do.

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

Copy link
Copy Markdown
Member Author

Self-review rubric (anchored on CI run 44689832145 for the PR head):

  • Scope: PASS. One file, +20/−6, comment lines only. Every hunk is one of the three drifted Javadocs named in the PR body.
  • Tests-new: PASS (not applicable). No new public members.
  • Tests-fix: PASS (not applicable). No behaviour change, and no bug fix to revert.
  • Sibling structure: PASS. No new files.
  • Sibling renames: PASS. Nothing renamed. Both ENV_* siblings were updated together.
  • Docs: PASS. The new wording was checked against environmentSaysOff / isOn / isNegative (the env lists), parseServerWideConfig lines 678–688 (any non-on enabled: disables), and readServerWideConfig (unreadable → UNREADABLE; missing and uncreatable, or unrepresentable path → NONE; env opt-out → NONE at the constructor). It agrees with the class Javadoc and the README "Opting out" table, which were not changed.
  • Issue resolution: PASS (not applicable). No Closes, because the gap was found during the triage sweep.
  • CI: PASS. build (8), build (17), build (21) all green. mvn -B verify locally ran 123 tests with 0 failures.
  • No dependencies: PASS. pom.xml is untouched, and every import is still java.*.
  • Single file: PASS. git ls-files src/main lists only TraceClient.java.
  • Java 8: PASS. The build (8) leg is green.
  • Never throws / non-blocking & bounded / environment seam: PASS. No code changed.
  • Version agreement: PASS. No version string touched.
  • Opt-out contract: PASS. The REASON_* / ENV_* values, the precedence, and the README table are unchanged. Only the constants' Javadoc was corrected to match them.

Judgment call noted: the new ServerWideConfig.NONE comment does not mention the unrepresentable-path case (toPath() throwing), which also returns NONE. It falls under "none was there", since no file can exist at such a path, so it was left implicit.

The comment-only change is accurate and in scope, and none of the do-not-auto-merge paths are touched.

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


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit da574d3 into main Nov 20, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/javadoc-fail-closed-drift branch November 20, 2026 06:45
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