Skip to content

Commit 8883a20

Browse files
committed
docs: explain adoption value and integration costs
1 parent e3e0cc4 commit 8883a20

2 files changed

Lines changed: 101 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,19 @@ The host keeps its renderer, numeric parser, units, command dispatch and undo hi
1212
`edit-session` holds small draft parameters and a context supplied by the host. It neither
1313
applies edits nor promises that a renderer's preview equals the committed output.
1414

15+
## What problem does this solve?
16+
17+
An open draft can outlive the document revision it was based on. In the proposed
18+
PdfCraft consumer, two real widget regressions show the consequence: an old title
19+
overwrites a newer edit, or confirmation after Undo discards Redo. Both fail on the
20+
baseline and pass with the guarded consumer patch.
21+
22+
[Evidence and adoption trade-offs](docs/ADOPTION.md) includes pinned sources, exact
23+
before/after behavior and reproduction commands. It also counts the cost: that patch
24+
adds a net 217 production UI lines. A local helper can provide the same protection;
25+
neither faster execution nor less total code has been demonstrated. Use this library
26+
when sharing the tested lifecycle is worth the dependency and integration cost.
27+
1528
## Use from another project
1629

1730
Add this entry to your crate's `[dependencies]` to use the alpha 2 API at a fixed revision:

‎docs/ADOPTION.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# When edit-session earns its dependency
2+
3+
The useful behavior is protecting an in-progress edit from a changed document, target
4+
or revision, including an edit followed by Undo to the same original value. Preview
5+
alone is not a reason to add this library: many editors already preview and cancel well.
6+
7+
## A demonstrated failure in a real consumer
8+
9+
The proposed [PdfCraft Document Properties integration](https://github.com/storytold/pdfcraft/pull/4594)
10+
has two regression tests against real egui widgets and the existing document engine:
11+
12+
| Workflow | Baseline behavior | Proposed guarded behavior |
13+
| --- | --- | --- |
14+
| Type "Old draft", apply "Newer title" elsewhere, confirm the old dialog | Overwrites the newer title with "Old draft" | Dismisses the stale dialog; keeps the newer title and revision |
15+
| Type "Old draft", apply another edit, Undo, confirm the old dialog | Applies the stale draft and loses the Redo branch | Rejects the stale revision; preserves the original value and Redo |
16+
17+
Baseline `418ac6a2af49b7ac2fed44ca2cae8d5d1d2cec0d`: **0/2 pass**. Proposed consumer
18+
`535d990d10832baf3b0a64910c51b280c224bd5c`: **2/2 pass**. These are the recorded
19+
25 October before/after checks, not newly discovered bugs or a survey of every dialog.
20+
The [tests](https://github.com/PerchAnton/pdfcraft/blob/535d990d10832baf3b0a64910c51b280c224bd5c/crates/ui-egui/tests/it/properties_session.rs)
21+
and [consumer reproduction instructions](https://github.com/PerchAnton/pdfcraft/blob/535d990d10832baf3b0a64910c51b280c224bd5c/docs/document-properties-sessions.md)
22+
make the behavior reviewable. [Validation details](VALIDATION.md) record the environment
23+
and broader 10-scenario / 79-step widget/engine checks.
24+
25+
This benefit comes from the complete consumer patch: the host supplies revision changes,
26+
document identities, permissions, dialog dismissal and serialized command dispatch.
27+
The library checks the context/value and returns at most one change. A correct in-tree
28+
helper can provide the same protection. Passing these tests does not establish that an
29+
external library is preferable to that helper.
30+
31+
## Count the cost as well
32+
33+
At the pinned consumer revision above, the production UI diff contains **267 added /
34+
50 removed lines (net +217)** across `dialogs.rs`, `lib.rs` and `properties_session.rs`.
35+
These are physical Git diff lines, including comments/formatting; tests, examples,
36+
manifests, lockfiles and documentation are excluded. This is added behavior and host
37+
integration, **not demonstrated code reduction**. Reproduce in a PdfCraft checkout
38+
containing the integration commit:
39+
40+
```sh
41+
git diff --numstat \
42+
418ac6a2af49b7ac2fed44ca2cae8d5d1d2cec0d...535d990d10832baf3b0a64910c51b280c224bd5c \
43+
-- crates/ui-egui/src
44+
```
45+
46+
The library has **0 runtime dependencies**, uses `no_std` and forbids unsafe code.
47+
An existing instrumented test performs **999 proposal/check pairs with 0 additional
48+
library-triggered snapshot clones** after the one clone at construction. Reset adds
49+
one clone; finishing adds none. This counts calls to `T::clone`, not allocations inside
50+
the caller's proposal, `Clone`/`PartialEq` implementation, CPU time or memory saved versus
51+
a native helper. It is not a speed claim. Reproduce:
52+
53+
```sh
54+
cargo test --locked proposing_and_checking_do_not_clone_snapshots_per_event
55+
```
56+
57+
On 26 October, all **16 lifecycle tests + 1 compile-fail doctest**, formatting and strict
58+
Clippy pass locally on Rust 1.99.1/macOS arm64. The API remains alpha.2 with MSRV 1.88;
59+
the current local check does not replace the CI MSRV check. No API growth was needed
60+
to address these adoption questions.
61+
62+
## What feedback changes our approach
63+
64+
- [Oculante](https://github.com/woelper/oculante/pull/799#issuecomment-6400163844)
65+
already has a largely non-destructive workflow. Wait for its UI rewrite and demonstrate
66+
a specific missing guarantee before suggesting another dependency.
67+
- [SSBH Editor](https://github.com/ScanMountGoat/ssbh_editor/issues/216#issuecomment-6400206516)
68+
already offers preview and workspace reload. There is no demonstrated regression here
69+
that justifies replacing that workflow.
70+
- [Tarsier](https://github.com/Its-Just-Nans/tarsier/issues/2#issuecomment-6400421930)
71+
prefers its backup/reset approach and closed the proposal. Respect that decision.
72+
- [PdfCraft's review](https://github.com/storytold/pdfcraft/pull/4594#pullrequestreview-5641786055)
73+
identifies a real dependency-policy cost. Both the runtime library and executing the
74+
external replay tool in CI need policy-owner approval; immutable pins do not grant it.
75+
76+
## Decision rule for the next integration
77+
78+
1. Reproduce a stale edit, no-op history loss or duplicated lifecycle logic in the host.
79+
2. Add a regression using the host's native test facilities before changing behavior.
80+
3. Compare a small local helper with the library under the same tests. Include the host
81+
bridge, dependency review and maintenance cost in the comparison.
82+
4. Use the external library only when shared tested behavior across consumers earns that
83+
cost. A local or ecosystem-owned helper is a valid outcome.
84+
85+
PhotoCraft and PdfCraft are proposed consumers, not adopted dependencies. We have
86+
demonstrated behavior protection in a consumer patch; we have not demonstrated lower
87+
total source size or faster editing. The next valuable milestone is a maintainer-reviewed
88+
workflow and ownership decision, not more adapters or a larger API.

0 commit comments

Comments
 (0)