Skip to content

Normalise the tags, then close a core #217

Description

@abernier

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:

animation(9)/animations(1)      shader(8)/shaders(4)        portal(3)/portals(1)
scrollcontrols(3)/scroll-controls(1)   soft-shadows(3)/softshadows(1)
shadows(2)/shadow(1)            contact shadows(1)/contact-shadows(1)
decal(1)/decals(1)              god-rays(1)/godray(1)       mesh-line(1)/meshline(1)
spring(1)/springs(1)            trail(1)/trails(1)          transform(1)/transforms(1)

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

  1. 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.
  2. Then threshold at ≥3 merged usages to get the core. It will be wider and truer than
    the 30 a raw count suggests.
  3. 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.
  4. 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.
  5. Lint it. ≥1 core tag as an error in lint:metadata, carved out by the same
    shrinking exception list as descriptionbin/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.

Notes

  • Its own PR, on its own branch, off mainnot stacked on #205. That stack is
    explicitly 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.
  • The mapping table should be reviewed as a table. A 170-file diff reviewed line by line is
    how a bad merge slips through.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions