mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-17 01:44:25 +00:00
docs: sweep: neutral wording, craft-automation module table, broken link
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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 |
|
||||
|
||||
+3
-3
@@ -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 <crate> <Component>` (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 <Component>` 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 <crate> <Component>` (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 <Component>` 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
|
||||
|
||||
|
||||
+1
-1
@@ -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::<L>()` | `craft_ui::contract` | 19.2 |
|
||||
| `words::<L>()` | The `WordSetCx` method that returns the word set `L` | `WordSetCx` method | 19.2 |
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
+5
-5
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user