docs: fix genuine passive-voice hits in docs/process
Fourth batch of hyperhive#4042's Passive pass (see #4098/#4099/#4100 for the first three and the read-every-hit discipline this pass uses). 44 hits across pr-review-gate.md (4), conventions.md (18), and gotchas.md (22) -- highest genuine-catch rate so far, 23/44 (~52%), because this architecture/mechanism documentation has a lot of "X does Y via Z" sentences where the actor is already named parenthetically or in a nearby clause -- the single most productive rewrite shape across every batch so far. Recurring rewrite shapes this batch: - Actor already named in the same sentence, just not as the grammatical subject: "X is configured per repo in its branch-protection settings" -> "Each repo's branch-protection settings configure X" (pr-review-gate.md); "the broker" (reserved names), "rsvg-convert" (PNG rendering), "the website repo" (HTML/CSS rendering), "systemd.globalEnvironment" (D-Bus address export), and several more -- all the same shape. - Subject already established one clause or one sentence earlier, just needs continuing rather than restarting with a new passive subject: "the harness reads HIVE_TOOL_GROUPS (...). Unrecognised tokens are logged and skipped." -> "...logging and skipping unrecognised tokens" (continues "the harness"), same pattern twice more (job_queue::templates::rebuild, HIVE_CAPABILITIES resolution). - Sibling-inconsistency: a bolded lead-in bullet was the one passive sentence in an otherwise-active paragraph/table (the read_host_journal capability row sat between two "may X" rows; the HTML+CSS bullet's own tail clauses were already active voice around the one passive lead phrase). - One caught-and-fixed authoring mistake worth noting for future passes: the first attempt at the "Nix treats X as a package" rewrite landed in the wrong sentence (a similarly-worded but unrelated passage two paragraphs up) -- caught by re-reading the diff before running vale, not by vale itself (which would have shown 0 remaining hits either way, since the intended sentence's hit just wouldn't have been touched -- a silently-wrong edit vale's own count can't catch). Re-reading the actual diff, not just trusting the before/ after hit count, is what caught it. 21 of 44 left alone -- same recurring legitimate shapes as prior batches (predicate-adjective copulas, quoted/literal text, generic- actor statements, negative-capability invariants, "is tracked/rooted/ scoped at X" property-description idioms, and two more thesis- statement headings matching the "Ownership is declared, not repaired" precedent from #4100). Verified: vale docs/process before/after -- 44 -> 21 write-good.Passive hits, exactly the 23 rewritten, re-read every changed line's full surrounding context after editing (not just the vale count) to catch exactly the kind of misplaced-edit mistake described above.
This commit is contained in:
parent
461c599e09
commit
c41c67c949
3 changed files with 37 additions and 38 deletions
|
|
@ -91,7 +91,7 @@ Two things to get right when a daemon needs outbound TCP:
|
|||
works until DNS hands back the other family;
|
||||
- list `AF_NETLINK` too. glibc's `getaddrinfo` opens a netlink socket to
|
||||
enumerate local addresses before it returns any, so name resolution
|
||||
fails without it even when `AF_INET` is allowed.
|
||||
fails without it even when the unit allows `AF_INET`.
|
||||
|
||||
**The directive is a claim about what the program does, and nothing
|
||||
re-checks it when the program changes.** A unit that only served a unix
|
||||
|
|
@ -143,15 +143,15 @@ to options the operator writes: **any** option of type `package` fed a
|
|||
store-path _string_ coerces through `lib.toDerivation`, i.e.
|
||||
`builtins.storePath`. `environment.systemPackages` and
|
||||
`systemd.services.<name>.path` both do it (the latter takes plain
|
||||
strings like `/run/wrappers` happily, but anything under
|
||||
`builtins.storeDir` is treated as a package). A path handed to the
|
||||
strings like `/run/wrappers` happily, but Nix treats anything under
|
||||
`builtins.storeDir` as a package). A path handed to the
|
||||
container as text has to be wrapped in a real derivation — a symlink
|
||||
farm built from the interpolated string — before it can go anywhere a
|
||||
package is expected.
|
||||
|
||||
The catch is that a path written into a generated flake is text, not a
|
||||
reference — the container's closure doesn't keep the binary alive.
|
||||
The **host** does: the package is interpolated into
|
||||
The **host** does: it interpolates the package into
|
||||
`/etc/hyperhive/serve.json`, so it lands in the host's system closure
|
||||
and is gc-rooted by the running generation. `builtins.toJSON` preserves
|
||||
string context, which is the load-bearing detail; discard the context
|
||||
|
|
@ -204,14 +204,14 @@ the `TIME_WAIT` case from a clean previous exit; retry covers the
|
|||
genuine "previous process is still alive during a systemd restart
|
||||
overlap" case. REUSEADDR does **not** allow two simultaneous
|
||||
`LISTEN` sockets on the same port (that would be `SO_REUSEPORT`,
|
||||
which we don't use) — exclusivity is preserved.
|
||||
which we don't use) — it preserves exclusivity.
|
||||
|
||||
## Approvals
|
||||
|
||||
### Orphan approvals
|
||||
|
||||
If state dirs are wiped out from under a pending approval (test
|
||||
scripts, manual `rm -rf`), the dashboard's next render marks them
|
||||
If test scripts or a manual `rm -rf` wipe state dirs out from under a
|
||||
pending approval, the dashboard's next render marks them
|
||||
`failed` with note `"agent state dir missing"` so they fall out of
|
||||
`pending`. They stay in sqlite for audit.
|
||||
|
||||
|
|
@ -323,7 +323,7 @@ rust build's `src` was the whole repo tree, any tweak to
|
|||
invalidated the cargo cache and forced a full rebuild. crane (and
|
||||
naersk before it) couldn't see "these inputs are unused by rust" on
|
||||
its own — the split breaks the coupling at the derivation boundary.
|
||||
The agent-configs PNG is rendered from the SVG via `rsvg-convert` at
|
||||
`rsvg-convert` renders the agent-configs PNG from the SVG at
|
||||
build time; librsvg dependency lives here, not in the rust
|
||||
derivation's `nativeBuildInputs`.
|
||||
|
||||
|
|
@ -400,10 +400,9 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
|
|||
= invisible window even though CDP works). The fix is **not** to wrap
|
||||
each client in its own `dbus-run-session` (a private throwaway bus per
|
||||
process — that's a _separate_ session, defeating the one-session
|
||||
model); it's this one shared bus, whose address is exported as
|
||||
`DBUS_SESSION_BUS_ADDRESS=unix:path=/run/gui/bus` via
|
||||
`systemd.globalEnvironment` so weston, the harness and every GUI client
|
||||
inherit it.
|
||||
model); it's this one shared bus; `systemd.globalEnvironment` exports
|
||||
its address as `DBUS_SESSION_BUS_ADDRESS=unix:path=/run/gui/bus` so
|
||||
weston, the harness and every GUI client inherit it.
|
||||
- **Fixed Wayland socket name (`--socket=wayland-0`)**: weston is
|
||||
launched with `--socket=wayland-0` so the socket path is
|
||||
deterministic. `nix/agent-modules/weston-vnc.nix` exports `WAYLAND_DISPLAY=wayland-0`
|
||||
|
|
@ -471,12 +470,12 @@ Pipeline:
|
|||
|
||||
- CommonMark from `nixosOptionsDoc.optionsCommonMark` is the only
|
||||
output — the source of truth, emitted as `.md`.
|
||||
- **HTML + CSS is rendered downstream by the website repo**
|
||||
(its own `options.nix`), which consumes this bundle's `host.md` /
|
||||
`agent.md`, renders them with `cmark-gfm`, and shares one
|
||||
- **The website repo renders HTML + CSS downstream**
|
||||
(its own `options.nix`), consuming this bundle's `host.md` /
|
||||
`agent.md`, rendering them with `cmark-gfm`, and sharing one
|
||||
stylesheet (`docs.css`) across `/options/` and the prose `/docs/`
|
||||
tree. Keeping rendering in the website means the theme has a single
|
||||
home and the colours are shared.
|
||||
home, sharing colours across both trees.
|
||||
- `transformOptions` strips the nix-store prefix from option
|
||||
declaration paths and rewrites them as forge URLs, so the
|
||||
rendered docs link back to the source.
|
||||
|
|
@ -512,7 +511,7 @@ The fix (`nix/docs/default.nix`):
|
|||
never forces a package — no stubs needed, and the Rust/frontend
|
||||
build closure stays out of the eval.
|
||||
|
||||
3. Both `hostEval` and `agentEval` are evaluated from `nixSrc` paths
|
||||
3. Nix evaluates both `hostEval` and `agentEval` from `nixSrc` paths
|
||||
(not `self`), so the docs drv dependency chain ends at `nixSrc`.
|
||||
|
||||
Why `builtins.unsafeDiscardStringContext`? The path string
|
||||
|
|
|
|||
Loading…
Reference in a new issue