Skip to content

Describe usage reporting's fail-closed switch accurately in TESTING.md - #265

Merged
dmccoystephenson merged 1 commit into
mainfrom
fix/testing-md-usage-fail-closed
Nov 20, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
fix/testing-md-usage-fail-closed

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

  • docs/TESTING.md's tests/test_usage.py paragraph still said "only an explicit 0/false/no/off opts out, an unreadable file degrades to a stderr warning". fix: keep usage reporting off once it is turned off #263 and fix: count a near-miss usage-reporting opt-out as off #264 changed both. The switch now fails closed: only true/on/yes/1 keeps reporting on. An unreadable notify.env counts as off, and so does an opt-out under a near-miss name. The paragraph now describes what TestSettings actually asserts: test_the_setting_fails_closed, test_the_notify_env_setting_fails_closed_too, test_an_opt_out_written_under_a_near_miss_name_is_an_opt_out, test_near_miss_names_that_say_on_are_not_an_opt_out, test_other_programs_switches_in_the_environment_are_not_gardeners and test_a_missing_config_file_means_defaults_and_an_unreadable_one_means_off.
  • README.md's "Usage reporting" section and gardener/usage.py's module docstring said an unreadable notify.env turns reporting off, with no exception. usage.enabled checks a non-blank GARDENER_USAGE_REPORTING_ENABLED env var before it looks at an unreadable file, so an env var saying on still wins. tests/test_usage.py:213-216 asserts this. Both docs now state that exception.

Documentation only. usage.py changes only in its docstring, and no code behaviour changes.

Test plan

  • python3 -m compileall gardener passed.
  • Both unittest runs (tests/ and integration/'s offline tier): CI on this PR is the anchor of record. The sandbox's python3 is 3.8.10, below pyproject.toml's >=3.10 floor, so a local run would not be meaningful.
  • No manual dispatch verification is required: dispatch.py, dev_loop.py and the prompt templates are not touched.

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

docs/TESTING.md still said only an explicit 0/false/no/off opts out and an
unreadable notify.env just warns, which #263 and #264 changed: the switch
fails closed, an unreadable notify.env is off, and near-miss opt-out
spellings count as off. README and usage.py's docstring now also say that
an environment variable saying on wins over an unreadable notify.env, as
tests/test_usage.py asserts.

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

Copy link
Copy Markdown
Member Author

Self-review: no issues found. The code-review skill was run at low effort on this diff and reported no findings, and the hand pass below found none either.

  • docs/TESTING.md:255-264: each clause was checked against a test in tests/test_usage.py's TestSettings. Fail-closed values are covered at lines 85-98, near-miss opt-outs at 100-123, near-miss names that say on plus endpoint/key at 125-136, other programs' switches at 138-140, and the unreadable file at 196-216. No clause describes behaviour that no test asserts.
  • README.md:277-279 and gardener/usage.py:43-45: the env-var exception was checked against usage.enabled. A non-blank GARDENER_USAGE_REPORTING_ENABLED returns at lines 168-170, before the config is None branch at 171, so an env var saying on does win over an unreadable notify.env, as the new wording states.
  • Doc-truth table: the README "Usage reporting" row and the docs/TESTING.md row were re-walked and are now consistent with usage.py. dispatch.py, dev_loop.py, MODE_SPECS and the prompt templates are untouched, so neither dispatch-safety invariant is affected and no manual dispatch verification is owed.
  • Anchor: CI on the PR head passed: test (3.10), test (3.x), city-still, fleetcity and garden3d. The sandbox's python3 is 3.8.10, below the floor, so no local suite run is relied on.

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 a2e777e into main Nov 20, 2026
5 checks passed
@dmccoystephenson
dmccoystephenson deleted the fix/testing-md-usage-fail-closed branch November 20, 2026 05:40
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