From 76be303ed01ed65f6cf2f278e0591ef550bc6a71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Sun, 6 Sep 2026 13:31:33 -0700 Subject: [PATCH 1/3] docs: match the shared CONTRIBUTING skeleton Every osapi-io repo carries the same CONTRIBUTING sections in the same order, with project-specific material inserted between them. Comparing all five showed a few places where that skeleton had holes. Add File headers, which states the licence header rule this repo already enforces in source but never wrote down. Add Documentation under Code style, moving the markdown paragraph there from Code style's prose so the section exists where every other repo has it. Code style keeps the UI tooling. The Documentation section further down now covers running and building the site, and points at Code style for formatting rather than repeating the commands. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c --- CONTRIBUTING.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29e7b57ae..3398ae0db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,14 +128,23 @@ configuration changes. Generated files (`*.gen.go`, `*.pb.go`) are excluded from formatting. TypeScript and CSS in `ui/` are formatted by [Prettier] and linted by [ESLint]. -Markdown outside the Docusaurus site is formatted by [mdformat]; the site itself -is formatted by Prettier through the `docusaurus` module. ```bash just react-fmt # Auto-fix UI formatting just react-lint # Run ESLint -just md-fmt # Format markdown outside the site -just docusaurus-fmt # Format the site +``` + +### Documentation + +Markdown outside the Docusaurus site is formatted with [mdformat] through `uvx`. +The site itself is formatted by Prettier through the `docusaurus` module. Both +styles are enforced by CI. + +```bash +just md-fmt-check # Check formatting outside the site +just md-fmt # Auto-fix formatting outside the site +just docusaurus-fmt-check # Check site formatting +just docusaurus-fmt # Auto-fix site formatting ``` ## Code standards @@ -237,6 +246,12 @@ Three doubles are written by hand, because generating them buys nothing: The conventions below are specific to OSAPI. +### File headers + +Every `.go` file MUST start with the MIT license header. See any existing Go +file in the repo for the exact format. Build-tagged files put `//go:build` on +line 1, blank line, then the header. + ### Logging All logging uses Go's `log/slog` structured logger. @@ -414,13 +429,12 @@ layers, and SDK generation flow. ## Documentation OSAPI uses [Docusaurus] to host a documentation server. Content is written in -Markdown under `docs/docs/`, wrapped at 80 characters. +Markdown under `docs/docs/`, wrapped at 80 characters. Formatting is covered +under [Code style](#documentation). ```bash just docusaurus-start # Start local docs server just docusaurus-build # Build docs for production -just docusaurus-fmt-check # Check site formatting -just md-fmt-check # Check markdown outside the site ``` ## Before committing From 0221427628fa47c0dfc0c6bd7274f9c96cff99de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Sun, 6 Sep 2026 15:16:17 -0700 Subject: [PATCH 2/3] docs: state the validateFunc table convention The other repositories that share this skeleton end the test conventions with a sentence naming the external test package and the validateFunc callback. OSAPI had no such sentence, though it is the heaviest user of the convention anywhere: 241 of its 407 public test files already carry validateFunc, 524 uses in total. So the rule was invented here and documented everywhere else. State it, and the repositories that copied it stop being the only ones that can point at it. The setter form is deliberately left out. gohai documents SetXFn(fn) func() returning a restore func; OSAPI pairs SetXFn(fn) with a separate ResetXFn(). Writing one sentence over two different shapes would document a convention neither repository follows. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01CM5qrNtYQvdKcemkS5YpiP --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3398ae0db..412fe4d4d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -317,6 +317,9 @@ module. Change both together. setter. Do not use an alias to re-cover behavior the caller's own test already reaches; a helper with its own contract is what the pattern is for. +External tests in this repository live in a `_test` package beside the code they +cover, and tables carry `validateFunc` callbacks. + ### Test layers - **Unit tests** (`*_test.go`, `*_public_test.go`). Fast, mocked dependencies. From 5fd61fc7f1c8a593e8912c551779dda50ab9e00d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Sun, 6 Sep 2026 17:42:31 -0700 Subject: [PATCH 3/3] docs: state the setter form the tests already use Test helpers said to expose a symbol through export_test.go and to reset swapped variables in TearDownSubTest, but never named the shape those setters take. There are twenty-one of them, each a SetXFn paired with a ResetXFn, and forty-five of the fifty-one reset calls come from TearDownSubTest exactly as the next bullet asks. gohai documents its own form, which returns a restore func the caller defers. OSAPI's is the pair, so this says the pair rather than borrowing a sentence that would be wrong here. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01CM5qrNtYQvdKcemkS5YpiP --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 412fe4d4d..d0f207fea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -339,6 +339,8 @@ runs read-only tests by default; `OSAPI_INTEGRATION_WRITES=1` enables writes. - Use `export_test.go` to expose an unexported variable or function to the `_test` package, rather than writing an internal test or a hand-rolled stub. +- The setter form is `SetXFn(fn)` with a matching `ResetXFn()`: the setter swaps + the dependency, the reset puts the original back. - Use `suite.TearDownSubTest()` to reset swapped variables between table-driven sub-tests, not `defer` inside the loop. - Platform stubs: test that the Darwin and Linux stubs return `ErrUnsupported`