From e80cbd30ab2709d0c33ca35793a375be57df31cc Mon Sep 17 00:00:00 2001 From: aiongg Date: Fri, 13 Nov 2026 12:49:28 +0000 Subject: [PATCH] docs: sweep: neutral wording, craft-automation module table, broken link --- crates/harfbuzz-subset-sys/README.md | 2 +- docs/craft-framework.md | 7 +++++++ docs/development.md | 6 +++--- docs/glossary.md | 2 +- docs/language-testing.md | 4 ++-- docs/porting.md | 10 +++++----- 6 files changed, 19 insertions(+), 12 deletions(-) diff --git a/crates/harfbuzz-subset-sys/README.md b/crates/harfbuzz-subset-sys/README.md index 0375847ef..f55b6d14c 100644 --- a/crates/harfbuzz-subset-sys/README.md +++ b/crates/harfbuzz-subset-sys/README.md @@ -19,7 +19,7 @@ wraps them in a safe API. The crate is one of the places that allow `unsafe` shapers, unit tests, generator scripts and inputs, meson files, and the `harfbuzz.cc` and `harfbuzz-world.cc` amalgamations. `harfbuzz/COPYING` is HarfBuzz's licence ("Old MIT", SPDX `MIT-Modern-Variant`). That identifier is -allowed for this vendored source only (the owner's exception, 2026-11-12); it is +allowed for this vendored source only (an exception recorded 2026-11-12); it is not on the house licence allowlist for other dependencies. ## Updating diff --git a/docs/craft-framework.md b/docs/craft-framework.md index 46f7be575..58bda30cf 100644 --- a/docs/craft-framework.md +++ b/docs/craft-framework.md @@ -1109,6 +1109,13 @@ Control channel, screenshot queue, profiler and recorded actions for tests and s | --- | --- | --- | | `actions`, `ui::actions` | Recorded actions and the actions list | exists | | `control` | Automation control channel | exists | +| `args` | Command-line values and environment fallbacks of the control channel | exists | +| `protocol` | JSON-lines wire format and parameter validators | exists | +| `security` | Tokens, the `auth` handshake and transport limits | exists | +| `server` | Loopback JSON-lines TCP transport (native) | exists | +| `client` | JSON-lines client for tests and command-line tools (native) | exists | +| `synthetic` | Synthetic pointer and keyboard input: `ui.click`, `ui.move`, `ui.key`, `ui.type` | exists | +| `dialogs` | `ui.dialog.set`, `ui.dialog.confirm` and `ui.dialog.cancel` over a `DialogHost` | exists | | `profiler` | Frame profiler | exists | | `screenshot` | Screenshot request queue | exists | | `trace` | Frame timing trace | exists | diff --git a/docs/development.md b/docs/development.md index 5ed8d7a63..5235b5ca7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -22,7 +22,7 @@ For a crate whose tests you build next, skip `cl check`: a check is a separate c ### The one-minute component loop -A fix to one gallery component, from the edit to its old/new picture on a page: edit the component's crate, then `cl render ` (about 10–25 s warm: the changed crate, the renderer's link, the render) and compare the PNGs with the previous ones; the box's comparison page does the compare step (`gal-sheet/pair.py`, box only). `story-render` links the framework and only the domain crates its features name, so a change in craft-color rebuilds craft-color and the renderer, not the gallery and its 17 crates. `cl render ui ` renders the framework's own components. +A fix to one gallery component, from the edit to its old/new picture on a page: edit the component's crate, then `cl render ` (about 10–25 s warm: the changed crate, the renderer's link, the render) and compare the PNGs with the previous ones; put the old and the new image side by side in whatever image viewer or comparison page you use. `story-render` links the framework and only the domain crates its features name, so a change in craft-color rebuilds craft-color and the renderer, not the gallery and its 17 crates. `cl render ui ` renders the framework's own components. ## One feature resolution @@ -52,11 +52,11 @@ No workflow runs the tests of: craft-behavior, craft-host and craft-ui-macros; t - Dependencies build at `opt-level = 2` in dev and test builds, once per target directory, so screen tests and the debug gallery run at a usable speed. - `lto = "off"` in dev: with cargo's default (`lto = false`) rustc runs thin-local LTO across every optimised crate's codegen units on each rebuild; off, a one-line edit re-optimises only the changed units (widgets' one-line rebuild went from 41 s to 4 s). - craft-theme, craft-behavior and craft-proof build at `opt-level = 1`: their code runs in every screen-test frame (colour maths, behaviour cores) or in dictionary-sized tests, and they are rarely edited. Every other workspace crate, the runtime (craft-ui-contract) included, builds at 0, where rustc shares generic instantiations across crates and an edit rebuilds in seconds (the runtime's 65k lines cost 35–90 s of codegen per edit at opt-level 1). -- The `gallery` profile (the owner's native gallery): release optimisation, incremental, 256 codegen units, and the workspace's own crates at `opt-level = 1`, which keeps rustc sharing generics across crates so a framework edit does not re-generate every dependant's copies; dependencies keep `opt-level = 3`. +- The `gallery` profile (the native gallery): release optimisation, incremental, 256 codegen units, and the workspace's own crates at `opt-level = 1`, which keeps rustc sharing generics across crates so a framework edit does not re-generate every dependant's copies; dependencies keep `opt-level = 3`. ## Measuring frame time -Frame-time numbers come from the gallery profile, the build the owner runs: `cl cargo build --profile gallery -p craft-ui-gallery --bin craft-ui-gallery` (the same command as `cargo run --profile gallery -p craft-ui-gallery`, with nothing added). Build it in a worktree kept for measuring only, so its gallery profile stays warm and a rebuild after a change compiles only the crates the change reaches. Build the old gallery with the same settings (for a tree without the gallery profile, release with the gallery profile's values passed as `--config profile.release...` overrides), so a ratio compares the code and not the optimisation. Measure the old and the new gallery at the same time, on two virtual displays, in every round: load on a shared machine moves both by more than one fix does, and the same load cancels in the comparison. What a frame runs (passes per frame, measuring runs, runs per interaction) is asserted by count trials, not counted in the measured build. +Frame-time numbers come from the gallery profile, the build a developer runs on the target machine: `cl cargo build --profile gallery -p craft-ui-gallery --bin craft-ui-gallery` (the same command as `cargo run --profile gallery -p craft-ui-gallery`, with nothing added). Build it in a worktree kept for measuring only, so its gallery profile stays warm and a rebuild after a change compiles only the crates the change reaches. Build the old gallery with the same settings (for a tree without the gallery profile, release with the gallery profile's values passed as `--config profile.release...` overrides), so a ratio compares the code and not the optimisation. Measure the old and the new gallery at the same time, on two virtual displays, in every round: load on a shared machine moves both by more than one fix does, and the same load cancels in the comparison. What a frame runs (passes per frame, measuring runs, runs per interaction) is asserted by count trials, not counted in the measured build. ## The job pool diff --git a/docs/glossary.md b/docs/glossary.md index a4def902e..0fc7daa5f 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -299,7 +299,7 @@ One row per name in the author table (Overview) and per `pub` item a component a | `WheelUnit`, `WheelPhase` | A wheel event's unit and phase, craft-behavior copies of egui's | craft-behavior | 8.6 | | `WindowChrome` | How a window's frame is drawn (OS, custom, none), part of `WindowInfo` | craft-host (`target`) | 21.1 | | `WindowInfo` | A window's kind, chrome, state, insets and `active` (OS focus), refreshed in `set_input` | craft-host (`target`) | 21.1 | -| `WordSet` | The trait a `words!` block writes | the word core (owner question 13) | 19.2 | +| `WordSet` | The trait a `words!` block writes | the word core (open question 13) | 19.2 | | `WordSetCx` | The trait on every context with `label()` and `words::()` | `craft_ui::contract` | 19.2 | | `words::()` | The `WordSetCx` method that returns the word set `L` | `WordSetCx` method | 19.2 | diff --git a/docs/language-testing.md b/docs/language-testing.md index d7cd2e08b..0f5f8bca4 100644 --- a/docs/language-testing.md +++ b/docs/language-testing.md @@ -14,8 +14,8 @@ Leave these to the automated tests; repeat them by hand only to investigate a fa | Automated | Where | |---|---| -| Linux input methods on this box: fcitx5 on Xvfb (XIM), fcitx5 on headless sway (text-input-v3) and IBus on Xvfb; Pinyin, Hangul, Telex and Anthy compositions, a click into a composing field, a pointer unplugged while composing | [IME harness](https://github.com/storytold/craft-libs/pull/212), `tools/ime-harness/` | -| Each app's key screens in Arabic, Japanese, Traditional Chinese, Korean, Thai and Vietnamese with no system fonts; one scripted IME composition and one non-Latin shortcut per app | `craft_ui::testing` ([craft-ui README](../crates/ui/README.md#testing-screens-in-each-language)) | +| Linux input methods in the test setup: fcitx5 on Xvfb (XIM), fcitx5 on headless sway (text-input-v3) and IBus on Xvfb; Pinyin, Hangul, Telex and Anthy compositions, a click into a composing field, a pointer unplugged while composing | [IME harness](https://github.com/storytold/craft-libs/pull/212), `tools/ime-harness/` | +| Each app's key screens in Arabic, Japanese, Traditional Chinese, Korean, Thai and Vietnamese with no system fonts; one scripted IME composition and one non-Latin shortcut per app | `craft_ui::testing` ([gates](craft-framework.md#82-gates)) | | The shortcut rule for Russian, Arabic 101, Hebrew, Greek, Thai, AZERTY, Dvorak and QWERTZ presses as egui reports them | craft-keymap's tests | The manual list covers what those can't reach: the input methods and layouts of Windows and diff --git a/docs/porting.md b/docs/porting.md index 997f4315a..bf3843108 100644 --- a/docs/porting.md +++ b/docs/porting.md @@ -95,15 +95,15 @@ Turn the map into tasks: ## 6. Porting one task -A task keeps one owner from start to finish: review fixes and later follow-ups go back to the same person or agent. +A task keeps one assignee from start to finish: review fixes and later follow-ups go back to the same person or agent. ### 6.1 Brief -The brief is complete before work starts: the map sections, the app files, the framework components with their files, the test verdicts, the states to compare, the done-when, and any decisions already made. If the brief leaves a design question open, the owner stops and asks rather than guessing. +The brief is complete before work starts: the map sections, the app files, the framework components with their files, the test verdicts, the states to compare, the done-when, and any decisions already made. If the brief leaves a design question open, the assignee stops and asks rather than guessing. ### 6.2 Plan checkpoint -Before editing, the owner writes a short plan: the mechanism, the files, and how the result will be checked. A reviewer (the lead, or a second agent) checks it against the map and the rules below. A plan that adds a framework mechanism, or departs from the map, needs the lead's answer before code is written. +Before editing, the assignee writes a short plan: the mechanism, the files, and how the result will be checked. A reviewer (the lead, or a second agent) checks it against the map and the rules below. A plan that adds a framework mechanism, or departs from the map, needs the lead's answer before code is written. ### 6.3 Write and prune @@ -254,7 +254,7 @@ Send the steps with `ControlClient::call`: a call returns after the input it que ### 6.6 Review and merge -- A reviewer reads the diff and the last old/new comparison, then passes the task or lists fixes. Fixes go back to the same owner; a fix that restructures gets reviewed again. +- A reviewer reads the diff and the last old/new comparison, then passes the task or lists fixes. Fixes go back to the same assignee; a fix that restructures gets reviewed again. - Merge the framework branch to `next` first, then the app branch onto the port branch. ### 6.7 Rules the review checks @@ -270,7 +270,7 @@ Send the steps with `ControlClient::call`: a call returns after the input it que At the end of a batch of tasks (a "wave"): 1. Repin the port branch to the `next` head that holds the batch's framework merges, and run a compile check. -2. Run the app's whole test suite once, and sort each failure to the task that caused it; it goes back to that task's owner. +2. Run the app's whole test suite once, and sort each failure to the task that caused it; it goes back to that task's assignee. 3. Build and run the app on each platform it ships on, and check what the batch changed by eye. Platform-only behaviour (GPU drawing, cursors, window chrome) is checked here. 4. Record what the batch cost (time, tool calls, review rounds) and change the process where it went wrong.