From 1b8768e431e7c3f8794c955640981bda30f64e01 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Wed, 2 Sep 2026 18:32:11 +0200 Subject: [PATCH] Record the compatibility policy, the override consequence and the deferred data de-duplication --- AGENTS.md | 8 ++++++++ README.md | 15 +++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 87d73c9..daf3121 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,3 +7,11 @@ - One spelling per result: reject the other at `New`, and let the error name the spelling to use. - A standing choice a reader would relitigate goes under Decisions in the README, not in a comment. - A README example is a `json` block that loads and renders as a category; `readme_test.go` runs every one. + +# Deferred + +- **Shipped-data de-duplication (2026-09-02).** `email.json`'s `local` is a + drifted copy of `username.json`, and no shipped file yet uses a held path, an + operand or a reference. Fixed in the data fill before the first tag, when the + shipped set is rewritten anyway; premise: nothing depends on the shipped data's + shape until then. Not raised in review before that. diff --git a/README.md b/README.md index e775105..9849ef3 100644 --- a/README.md +++ b/README.md @@ -364,6 +364,21 @@ tokens add cost in proportion to the output. folder, `..` the folder above — what those spellings already mean to anyone who has typed a path. A locale's files reach each other without naming the locale, so a folder renames and copies without editing its references. +- **After the first tag, a new fence is a major version.** Data files are the + public API, and one spelling per result grows by tightening, so every fence + invalidates some file. Each such release names the rejected spelling and its + replacement in the changelog and in the load error, and that is the whole + migration: a fence rejects one spelling with one replacement, so the fix is + local to each site. A fence that would need a non-local rewrite ships a + converter with its release instead. Before the first tag there is no + compatibility promise. +- **A `--data-path` override rebinds every reference to the category it + replaces.** References bind against the merged tree, so once shipped data uses + `{.person}`, a consumer's `sv_SE/person.json` is what every shipped reference + into `person` reads, and `New` fails on shipped data the consumer never wrote + when that file lacks a field those references read. Accepted: overriding is the + point of layering, the error names the reference and the field, and the fix is + the consumer's file carrying the fields the shipped tree reads. - **Samples say what they emit, transforms what they do.** `{upper(2)}` is two letters, `{uppercase(x)}` is `x` upper-cased; one name for both would turn on whether the argument looks like a number.