blob: 399d52013b59c4415d7c4e4a45782e9d72206cc0 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
|
#+TITLE: ADR-2: Auto-fetch on local miss
#+DATE: 2026-04-30
#+STATUS: Accepted
* Context
When the user runs =gloss-lookup= on a term that isn't in the local
cache, the package can either prompt before going online or fall
through silently. The trade-off is between explicit consent (no
surprise network calls) and frictionless typical use.
* Decision
Silent fall-through. On a cache miss, =gloss-lookup= calls the online
fetcher without asking. Network failures surface clearly via the
error rollup (see ADR on the error taxonomy in the design doc).
If a user wants a strict offline mode, they can wrap =gloss-lookup= or
unbind =gloss-fetch-sources= to nil. v1 does not ship a defcustom toggle.
* Consequences
*Positive.*
- The common case (term not in glossary, want a definition) takes
one keystroke (=C-h g g=) instead of two.
- The user-facing message on a network failure is the same shape as
any other failure mode — there's no special "you would have hit
the network" affordance to explain.
*Negative.*
- A user on a metered connection or in a restricted environment
might prefer an explicit prompt. v1 doesn't accommodate that.
- A typo on the term means a wasted network call. The cost is small
(one HTTP request to Wiktionary) and the failure is fast.
* Alternatives Considered
*y/n prompt before fetch.* Rejected: the answer would be "yes" 99%
of the time, and the prompt becomes friction the user trains
themselves to ignore. The 1% offline case is better handled by
detecting the failure than by pre-asking permission.
*Defcustom =gloss-auto-fetch=.* Rejected for v1: adds a knob with no
clear default. If shakedown reveals a real need, adding the knob in
v1.1 is straightforward — silent fall-through is the harder default
to walk back.
*Hard-fail offline.* Rejected: turns "not in glossary" into a fatal
error, which is the wrong shape for what should be a soft fall-through.
|
