docs: correct ARCHITECTURE.md against the code, link the README badges - #21
Merged
Conversation
ARCHITECTURE.md had drifted from the implementation. Verified each claim against the source rather than editing around it: - WebSocket client claimed "Reconnection: Exponential backoff (max 5 retries)" and "Heartbeat: 30-second ping interval". Neither exists — there is no reconnect, backoff, retry or ping anywhere in internal/. README repeated the same claim in Troubleshooting. Both now say what actually happens: the stream ends and exits 1. - "No Pulse | Exit 2" — nothing in the codebase exits 2. Every error path goes through exitWithError, which exits 1. - Dependency table listed nhooyr/websocket; go.mod has coder/websocket v1.8.15. - Formatter interface was missing FormatConsumptionHistory. - Directory tree was missing consumption.go, every _test.go file, CONTEXT.md and .goreleaser.yml. - The build-all snippet showed a platform loop the Makefile does not have. - Testing Strategy omitted websocket_test.go. - Title said "Tibber CLI"; the project, module and binary are powerctl. Also documents the release pipeline, which was undocumented in both ARCHITECTURE.md and CONTRIBUTING.md despite being the only way to ship. README badges were bare images that linked nowhere. They are now links, the tests badge is pinned to main, and a release-notes badge points at the releases page. All four URLs verified to return 200 with live values.
14 tasks
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
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.
Two parts: a factual audit of the docs, and the README badge update.
The docs described behaviour that does not exist
I checked each claim against the source instead of editing around it. Four were wrong:
grep -riE "reconnect|backoff|retry|ping|heartbeat" internal/returns nothing outside tests.websocket.gohas five functions and none of them reconnect.exitWithError, which isos.Exit(1).nhooyr/websocketgo.modhasgithub.com/coder/websocket v1.8.15— the package was renamed.The reconnect one is the reason this is worth doing: someone reading Troubleshooting would wait for a recovery that is never coming. Both spots now say the stream ends and exits 1, and suggest a supervisor if you need it to stay up.
Also stale, less severely:
Formatterinterface was missingFormatConsumptionHistory(added in feat: implement consumption history command #12)consumption.go, every_test.go,CONTEXT.md,.goreleaser.ymlbuild-allsnippet showed aPLATFORMSloop the Makefile does not havewebsocket_test.gopowerctlRelease pipeline was undocumented
Tagging is the only way to ship, and neither ARCHITECTURE.md nor CONTRIBUTING.md said so. ARCHITECTURE.md gains a Release Pipeline section; CONTRIBUTING.md gains a Releasing section with the tag commands, the dry-run that renders notes without publishing, and how the changelog grouping behaves.
Badges
They were bare
<img>tags that linked nowhere. Now:/releases/latest/releases?branch=main, links to the workflowLICENSEAll four verified to return 200 with live values (
release: v0.4.2,release notes: today,tests: passing,license: MIT) rather than assumed.Verification
make checkpassesUser-Agent: powerctl-cli/1.0claim confirmed againstwebsocket.go:18before documenting itNo code changes.
⚡ Built on gilfoyle with Claude Code