Skip to content

docs: name the real debug switch and list the teardown script - #271

Merged
dmccoystephenson merged 1 commit into
mainfrom
feature/docs-debug-toggle-and-teardown
Nov 15, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
feature/docs-debug-toggle-and-teardown

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

A Stage A documentation accuracy sweep was run against the source. Two drifts were found and fixed. No code is changed.

  • docs/REBUILD_PLAN.md: the Notes section said debug tools are kept behind spring.profiles.active=debug. No profile is used anywhere in the repository. DebugController is @ConditionalOnProperty(prefix = "viron.debug", name = "enabled", havingValue = "true"), fed by viron.debug.enabled=${VIRON_DEBUG_ENABLED:false} in application.properties. The note now names that property and its environment variable.
  • README.md: the project-structure tree described db-scripts/ as setup scripts and migrations, but left out db-scripts/teardown/delete_tables.sql. The teardown script is now listed.

What the sweep checked and found consistent

  • Postman collection vs. docs/openapi/viron-api.json: all 37 routes match in both directions. This was checked with a throwaway script that is not committed.
  • docs/MVP.md checklist vs. the spec: 37 endpoints and the DTO list agree. Its claims about placement, move and removal behaviour were checked against LocationController.
  • Success status codes (200/201/204) in the spec vs. the @ResponseStatus annotations on every controller method: all agree.
  • Every NotFoundException, ConflictException and InvalidRequestException thrown by a controller sits on a route whose spec lists the matching 404/409/400.
  • README.md configuration tables vs. application.properties, compose.yml and sample.env: all agree.

Skipped issues

All four open issues were deferred this cycle:

Test plan

  • Docs-only diff (README.md, docs/REBUILD_PLAN.md); no Java or Python file is touched.
  • Each new claim was verified against DebugController.java:38, application.properties:31 and db-scripts/teardown/.
  • CI green on the PR head.

No tracking issue. The gap was found during the documentation 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

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

Copy link
Copy Markdown
Member Author

Self-review rubric (anchored on CI run 43673591074: build, python-client (3.8) and python-client (3.12) all green on the PR head):

  • Scope: PASS. Two lines changed in two docs files, and each corrects one drift the sweep found. No formatting or comment churn.
  • Tests-new: PASS (not applicable). No public method is added.
  • Tests-fix: PASS (not applicable). This is not a bug fix, and no behavioural file is touched.
  • Sibling structure: PASS. The README tree line keeps the # comment column format. The REBUILD_PLAN note stays a single bullet in the Notes list.
  • Sibling renames: PASS (not applicable). Nothing is renamed.
  • Docs: PASS. The new REBUILD_PLAN wording matches README.md:84, docs/MVP.md:76, the spec's debug-route descriptions (viron-api.json:795,817) and sample.env, all of which already named viron.debug.enabled / VIRON_DEBUG_ENABLED. With this change, no doc still mentions a debug profile. tickets.md Ticket 7 ("via profile or property") is left alone, since it states the choice that was open at ticket time.
  • Issue resolution: PASS (not applicable). No Closes. The gap was found by the sweep.
  • CI: PASS. All three jobs are green. Being docs-only, the diff gives CI nothing to exercise, so the green run is UNVERIFIED-not-applicable as verification of the change itself. The claims were instead checked against DebugController.java:38 (@ConditionalOnProperty(prefix = "viron.debug", name = "enabled", havingValue = "true")) and application.properties:31.
  • DTO boundary / Spec alignment / Java-Python parallelism / Override correctness: PASS (not applicable). No controller, spec, client or Java code is touched.

Out-of-diff observation, recorded without a fix:

  • db-scripts/teardown/delete_tables.sql drops the seven tables but not the four viron.*_id_seq sequences created by db-scripts/setup/create_sequences.sql. Those sequences are standalone (not OWNED BY a column), so CASCADE on the tables does not remove them. After a teardown and re-setup, IDs therefore continue from where they stopped rather than restarting at 1.
  • The README wording added here ("a teardown script that drops the tables") is accurate as written. Whether the teardown should also drop the sequences and the schema is a script-behaviour question, outside a docs PR.

Summary: a docs-only correction of two verified drifts. CI is green, nothing is left to address, and the PR is ready to merge.

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 dd2e728 into main Nov 15, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/docs-debug-toggle-and-teardown branch November 15, 2026 03:44
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