You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Implements §4 of the distilled-docs spec (#192), the one part of it with neither a PR nor
an issue. Opened now rather than "whenever", because 139 tags used exactly once will not
remind anyone of themselves.
Deliberately outside the explainer rollout (#216). It touches all 170 pmndrs.json
files and shares nothing with the prose work; mixing the two would make every delivery PR
unreadable. It is also not in #192's done-when, which is about description, apis and
explainers — so this does not gate that.
The measurement, today
distinct tags
195
used exactly once
139
examples with no tag at all
29
tags at ≥3 usages, before normalising
30
The head is short and sane: gltf(23) physics(17) html(15) transmission(15) postprocessing(14) animation(9) bloom(9) reflections(9) scroll(8) shader(8).
Order matters, and getting it backwards is the trap
The 139 singletons are not mostly noise. They are mostly variants of tags already in the
head, and thresholding the raw data would freeze the variants apart from the things they
are variants of.
Mechanically detectable today — case, separator, or plural only:
Typos, which no normaliser finds — each verified present:
typo
the real tag
gtlf (1)
gltf (23)
clell-fracture (1)
cell-fracture (1)
frosted-glas (1)
— no correctly-spelled sibling exists
box projected (1)
space instead of a hyphen
Synonyms, which are judgement and not mechanism — the numbers are what make them worth
merging:
merged
instances(5) + instancing(2)
7 — crosses the bar
dof(2) + depth-of-field(1)
3 — crosses the bar
bloom(9) + glow(3)
12
postprocessing(14) + effects(3)
17
merged(1) + merging(1)
2 — still below
Three of those merges create or strengthen a core tag that raw thresholding would have
thrown away. That is the whole argument for the ordering.
The work
Normalise. A mapping table, written once, covering the three classes above. It is
mechanical for two of them and editorial for the third, so the table is the reviewable
artifact — not the diff across 170 files.
Then threshold at ≥3 merged usages to get the core. It will be wider and truer than
the 30 a raw count suggests.
Hapax that survive normalisation are kept, as free tags.minecraft, tag-heuer, pinball genuinely describe their demo and nothing else does. The rule is at least one
tag from the core; anything beyond that is free.
The 29 untagged examples. With no tag and no description they exist in the index as a
directory name. Note that the description half of that is being fixed by The remaining 167, and the conditions under which the stack lands #216 — these 29
overlap the 31 empty descriptions and should be checked against them rather than guessed
at separately.
Lint it.≥1 core tag as an error in lint:metadata, carved out by the same
shrinking exception list as description — bin/description-exceptions.mjs is the
pattern, and its own header explains why the list has to be written down rather than
remembered.
libraries is already a closed enum and lint:metadata already runs, so enforcement costs
nothing new.
Done when
Every example carries at least one tag from the core; the mapping table is in the repo; the ≥1 core tag rule is an error in lint:metadata with an exception list that only shrinks.
Implements §4 of the distilled-docs spec (#192), the one part of it with neither a PR nor
an issue. Opened now rather than "whenever", because 139 tags used exactly once will not
remind anyone of themselves.
Deliberately outside the explainer rollout (#216). It touches all 170
pmndrs.jsonfiles and shares nothing with the prose work; mixing the two would make every delivery PR
unreadable. It is also not in #192's done-when, which is about
description,apisandexplainers — so this does not gate that.
The measurement, today
The head is short and sane:
gltf(23)physics(17)html(15)transmission(15)postprocessing(14)animation(9)bloom(9)reflections(9)scroll(8)shader(8).Order matters, and getting it backwards is the trap
The 139 singletons are not mostly noise. They are mostly variants of tags already in the
head, and thresholding the raw data would freeze the variants apart from the things they
are variants of.
Mechanically detectable today — case, separator, or plural only:
Typos, which no normaliser finds — each verified present:
gtlf(1)gltf(23)clell-fracture(1)cell-fracture(1)frosted-glas(1)box projected(1)Synonyms, which are judgement and not mechanism — the numbers are what make them worth
merging:
instances(5) +instancing(2)dof(2) +depth-of-field(1)bloom(9) +glow(3)postprocessing(14) +effects(3)merged(1) +merging(1)Three of those merges create or strengthen a core tag that raw thresholding would have
thrown away. That is the whole argument for the ordering.
The work
mechanical for two of them and editorial for the third, so the table is the reviewable
artifact — not the diff across 170 files.
the 30 a raw count suggests.
minecraft,tag-heuer,pinballgenuinely describe their demo and nothing else does. The rule is at least onetag from the core; anything beyond that is free.
directory name. Note that the description half of that is being fixed by The remaining 167, and the conditions under which the stack lands #216 — these 29
overlap the 31 empty descriptions and should be checked against them rather than guessed
at separately.
≥1 core tagas an error inlint:metadata, carved out by the sameshrinking exception list as
description—bin/description-exceptions.mjsis thepattern, and its own header explains why the list has to be written down rather than
remembered.
librariesis already a closed enum andlint:metadataalready runs, so enforcement costsnothing new.
Done when
Every example carries at least one tag from the core; the mapping table is in the repo; the
≥1 core tagrule is an error inlint:metadatawith an exception list that only shrinks.Notes
main— not stacked on #205. That stack isexplicitly frozen until the explainer rollout finishes (The remaining 167, and the conditions under which the stack lands #216, Decision 1), and this work
has no reason to wait for it.
how a bad merge slips through.