Skip to content

docs: fix the quickstart a reader would paste, and add the files a public repo is judged on - #183

Merged
raspbeguy merged 1 commit into
mainfrom
docs/public-release-polish
Aug 13, 2026
Merged

docs: fix the quickstart a reader would paste, and add the files a public repo is judged on#183
raspbeguy merged 1 commit into
mainfrom
docs/public-release-polish

Conversation

@raspbeguy

Copy link
Copy Markdown
Member

A pre-first-public-release pass over documentation, examples and repo hygiene. Two real defects, three missing files, and a lot that turned out fine.

The README's flagship demo did not work

The "Quick demo: add a firewall rule" body sends "dest_port": [22]. The schema types those items as strings, so the first thing a curious reader pastes returns:

422  { "field": "match.dest_port[0]", "code": "invalid_type",
       "message": "must be string, got integer" }

["22"] returns 200 with the rule's id. Verified both ways on a device.

Found by validating every documented request body against its endpoint's request schema rather than reading them, which is the same conformance approach that found this cycle's schema defects. 4 bodies matched the extractor, 1 was invalid.

A shipped example failed when run

examples/curl/uhttpd_instances.sh exits 52. Patching the main uhttpd instance restarts the server answering the request, so curl reports "Empty reply from server" even though the write committed. Nothing in the script said so, and a newcomer running the examples would conclude uapi is broken.

It now says what happens, tolerates the disconnect, and reads the instance back once uhttpd is listening again. All 16 examples run green against a real device; before this, 15 did.

Three files a public repo is judged on

  • CODE_OF_CONDUCT.md. Reporting goes to guy.godfroy@gugod.fr, the identity that already authors the commits and signs the tags, so it publishes nothing new. Security stays on SECURITY.md's private path. Change the address if you would rather route it elsewhere.
  • .editorconfig. *.uc is tab-indented (878, 231 and 222 tab-started lines in the three largest lib files, against 1 to 3 space-started continuation lines), and a contributor's editor should not have to guess.
  • .gitattributes. * text=auto eol=lf. This tree lands on OpenWrt, where a CRLF in an init script or a uci-defaults hook fails at a shell that gives no useful error.

One stale claim in CONTRIBUTING

make test was described as "lint + 600+ unit tests"; the suite is at 1230. Rewritten to not carry a number that rots, since that is the second time today a hand-written count has gone stale.

What was checked and is clean

  • No TODO, FIXME, HACK, XXX or debug output in shipped code. The two marker hits are debug.syslog doing its job and uci's cfgXXXXXX anonymous-section naming; every printf is in the CLI, where printing is the point.
  • 0 dead links across 27 markdown files, relative paths and anchors both.
  • The CLAUDE.md pointer table matches docs/ exactly: 22 entries, 22 files, no orphans and nothing dangling.
  • Every make target README and CONTRIBUTING tell a contributor to run exists in the Makefile.
  • Every example is on /api/v3.
  • Nothing internal is tracked: uc.out, feedback/ and .claude/ are all untracked or ignored.

Was it verified against a real device, or only by CI? On a device throughout: the README body both ways, all 16 examples end to end, and the uhttpd example's restart-and-recover path including confirming the API came back and ucode_prefix survived. make lint, 1230 unit tests, coverage and openapi-check pass.

Does this change the wire surface? No. Documentation, examples and repo metadata only.

@raspbeguy
raspbeguy merged commit 0d2fe02 into main Aug 13, 2026
6 checks passed
@raspbeguy
raspbeguy deleted the docs/public-release-polish branch August 13, 2026 14:29
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