Documentation Cleanup - #15
Merged
Merged
Conversation
The guidance for AI agents still described version 0.8's code: fixed brownout voltages, four named swerve modules, match phases from mode transitions, a memory-mapped file with an LRU cache, and "no health scores". It now states the rules the code enforces and points to the documents that own the details: the result contract, the no-guessing rule and the signal resolver, the three testing rules and the suites that hold them, the source conventions (license header, indentation, dated comments, commit messages), the disk cache's versioning, the extension's structure, security, concurrency, and the changelog's form. Season-specific numbers and names are left to the documents and the code, so the file does not go stale with each WPILib or hardware release. Two of its pointers were made true rather than removed. CI now runs ./gradlew license, which only ./gradlew build ran, so a Java file without the license header no longer reaches main unnoticed. doc/STANDALONE.md now says why the TBA key belongs in the configuration file or the environment rather than on the command line, where the process list shows it. DEVELOPMENT.md describes the CI change, and the changelog records both. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wo6ufDtEY27NQ8ctU5ns5
CI failed on the first run of ./gradlew test shadowJar license: Gradle refuses a run in which licenseMain reads the generated-sources folder, an output of generateVersionSource, without depending on that task. ./gradlew license alone passed, since it schedules no generator, which is why the check looked fine before it reached CI. The license tasks now depend on the generator. Reproduced with clean compileJava license, and CI's command passes from a clean build directory. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wo6ufDtEY27NQ8ctU5ns5
The release workflow now publishes every release without a suffix to the Marketplace, with vsce, when the VSCE_PAT repository secret holds a Marketplace token; without the token it says so and the .vsix from the GitHub release is uploaded by hand. The Marketplace refuses a version with a suffix, so test builds (0.9.0-dev2) stay on GitHub. The step runs after the GitHub release is published, so a Marketplace problem never holds up the release. The package carries the license file (vsce warned that none was beside package.json; the repository's is copied in at packaging time, by the workflow and by buildExtension, and git ignores the copy) and the manifest links the issue tracker and the README and sets the gallery banner. The READMEs install the extension from the Marketplace, with the .vsix on the releases page for a particular build, and DEVELOPMENT.md has a section on publishing. The extension's tests, the manifest and build-file tests, and buildExtension pass; the .vsix holds the license. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wo6ufDtEY27NQ8ctU5ns5
The header gains an Install line that links the extension's Marketplace page, with the standalone install as the alternative for clients outside VS Code, and the installation section says that most people want the extension and that nothing else is downloaded. The extension's README links the listing and says that installing from the Extensions view works in the WPILib VS Code distribution too. Marketplace badges were tried and left out: the shields.io ones are retired, and the other two services were unavailable or failing for the listing. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wo6ufDtEY27NQ8ctU5ns5
The README opened with two questions and then, one paragraph later, a section of nine more, which read as repetition. The example questions now follow "How It Works", where the reader has learned that the model does the finding, and the header keeps the two as a hook. The installation section no longer says twice that most people want the extension, and the header no longer mentions WPILib's log reader, a detail that belongs in the architecture guide. The header and the installation section name the agents the server works with: Claude, GitHub Copilot, Gemini, Cursor, and ChatGPT over the HTTP transport, since ChatGPT reaches MCP servers only over the network. A new "Supporting Triple Helix" section, adapted from the Pit Dash app's about text, links the Intentional Innovation Foundation and its donation page. Every paragraph got an editorial pass for pacing and punctuation: chained "and" clauses became series set off by semicolons or colons, and the long note on model quality and context is two paragraphs. Verified: every internal link and anchor resolves, including the two anchors the standalone and extension READMEs link to; the tool table is unchanged and ClaimChecksTest passes; the three new external links respond. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wo6ufDtEY27NQ8ctU5ns5
Four reviewers read the extension README, the standalone guide, the
architecture and development guides, the tools reference, the ideas
file, and the unreleased changelog section for grammar and structure.
Every finding was checked against the text and, where it made a claim
about behavior, against the code (the CAN counter name rule, what
power_analysis reports per channel, which Java candidate gets the
version check, the renamed-file rule in LogFileName) before it was
applied.
Grammar: pronouns with no clear antecedent ("it", "them", "that
entry"), wrong words ("passed" for "missed", "in any case" for "in
either case", "weigh" for "are weighed"), a garden-path "Since 2023
playoffs", a dangling participle, and two stacked articles. Chained
"and" clauses became series set off by semicolons or colons.
Structure, by document:
- STANDALONE.md: the -debug row was stranded below a paragraph that
had been inserted inside the flags table; it is back in the table.
HTTP Transport and Containerization are sections of their own, the
command-line notes on several log directories sit under the flags,
the general rule on top-level settings precedes its stresstest
example, and the Docker section restates the no-authentication
warning where the server binds to every interface.
- vscode-extension/README.md: Requirements precede Install, Upgrading
covers the Marketplace path, the non-robot-folder paragraph follows
the robot-project behavior it contrasts with, and a fact stated
twice about the TBA key is stated once.
- TOOLS.md: the REV signal and device-key reference, the low-
confidence troubleshooting, and the example workflow move from
under individual tools into the RevLog section's introduction; the
four tools with a use-case list share one heading in one place;
the RevLog headings use the file's sentence case; moi_regression's
parameter annotations match every other tool's.
- DEVELOPMENT.md: the test suites are paragraphs with bold lead-ins
instead of eight paragraph-length bullets, the extension build sits
beside the server build, and releasing step 4 is split from what
the workflow does and from the pre-release and immutability notes.
- ARCHITECTURE.md: the background-start protocol is a paragraph after
the startup list, the finding-logs paragraph is four, and the
Security section points at the sections that explain its rules.
- IDEAS.md: 6.8 is marked done in 0.9.0, the AdvantageScope hand-off
is described once, and a sentence that did not parse is two.
Verified: every internal link and anchor in the edited documents
resolves; ./gradlew test passes, including the claim checks that
compare TOOLS.md's parameter lists with the schemas and the README's
tool table with the registry.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015wo6ufDtEY27NQ8ctU5ns5
Main carries the squash merge of this branch's first two commits (CLAUDE.md and the CI license check, #14). The same text therefore sat on both sides of CHANGELOG.md and doc/DEVELOPMENT.md, in hunks the branch's editorial pass later rewrote, and git could not pair them. Both files keep the branch's version, which already contains everything main added; the merge changes no file. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wo6ufDtEY27NQ8ctU5ns5
A loaded log answered from its first load for as long as it stayed in memory: a log copied off the robot again once it had grown kept its old contents; a file overwritten in place (cp keeps the inode) had the old record offsets applied to the new bytes, hiding new records or decoding garbage; and a read of a file truncated under its memory mapping threw an InternalError that nothing caught, which in stdio mode ended the server. REV logs were found only when the wpilog was loaded, so one copied in later was never synchronized. Now the log manager keeps each loaded log's file snapshot (size, modification time, inode) from just before the log was read, and compares it with the file on every call. A changed file is loaded again; a missing one is an error. The log-reading tool base compares again after the call and discards a result read across a change with an error that says what changed, since the result may hold old data or mix old and new bytes. An InternalError from a mapped read becomes the same explained error, in the tool base and in the message handler, and the log is unloaded. Each session is told once, in _metadata.log_reloaded and a warning, when a log it used was reloaded; a session that first used the log after the change is not told. The REV log tools look again for REV files, at most every two seconds, and synchronize again when the candidates or their files changed, keeping an offset set by hand for a file that did not. The cache's eviction callback now receives the evicted instance, so a reload cannot clear the records of the log that replaced it; a pending sync is cancelled unless the sync cache already holds another instance's entry. LogRequiringTool gains the injecting constructor its documentation already described, so a test can give a tool a log manager of its own. Verified: eleven new tests (LogReloadTest, FaultingToolTest) cover an in-place overwrite, a rename into place, a removed file, a change during a call, a simulated and a real fault on a truncated mapping (the real one on Linux and macOS; Windows refuses the truncation), the once-per-session notice, a REV log copied in later, and a kept hand-set offset. All eleven fail against the previous code, run in a separate worktree with only the two shims they need to compile, and pass with this change. The full suite passes, and the license check. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wo6ufDtEY27NQ8ctU5ns5
Six of the new reload tests failed on Windows CI: they truncated, renamed over, or deleted a file while it was memory-mapped, which Windows refuses (the limit doc/IDEAS.md records under 8.5). What Windows does allow is rewriting a mapped file's bytes in place at the same size, and that still changes the modification time, which the reload check detects. The tests of a reload, a result discarded across a change, and the once-per-session notice now rewrite the file in place with a log of the same length and a different shape (cos for sin), and check the new values. The tests that grow, replace, or remove the file, and the one that truncates it under its mapping, state the Windows limit and run elsewhere. A new FileSnapshotTest covers the comparison itself, the size change included, without mapping a file, so that path is checked on every system. Verified: the reload, snapshot, and faulting-tool tests pass locally (Linux); the Windows job is the check that matters and is watched. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015wo6ufDtEY27NQ8ctU5ns5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.