92 lines
4.4 KiB
Markdown
92 lines
4.4 KiB
Markdown
# Workshop: link-taxonomy-migration
|
|
|
|
- **Run key:** `link-taxonomy-migration` (this directory's name - there is no other identifier)
|
|
- **Input:** none - this run is not an ingest
|
|
- **Started:** 2026-09-02
|
|
- **Session id form:** `WIKITOOL_SESSION_ID="link-taxonomy-migration/u<N>"`, one per unit
|
|
- **Issue:** Gitea #40, sections *Label werden Enum* and *Toolgeführte Blöcke*
|
|
|
|
## Goal
|
|
|
|
Move every relationship in `kb/` from free-text German prose in a body bullet to a machine
|
|
value in `related:`, and every tool-owned body region from heading-matching to a marker pair.
|
|
Afterwards the compiler contains no heading text and no relationship label, and `lint` can
|
|
enforce the vocabulary because there is one.
|
|
|
|
## Why this is `assisted` and not `mechanical`
|
|
|
|
Measured on 2026-09-02, against the corpus rather than against the documentation:
|
|
|
|
| | |
|
|
|---|---|
|
|
| Pages | 180 |
|
|
| Distinct relationship labels in body bullets | **152** |
|
|
| Labelled bullets | 337 |
|
|
| Labels occurring exactly once | 102 |
|
|
| Top 20 labels cover | 167 of 337 |
|
|
| Bare `- [[X]]` bullets under `## Siehe auch` | 555 |
|
|
| ...of those, provably redundant (a labelled edge already exists) | 353 |
|
|
| ...of those, the only connection between the two pages | **202**, across 63 target pages |
|
|
|
|
`kb/CONVENTIONS.md` documents thirteen labels. Nothing ever checked that, and the corpus does
|
|
not follow it - so there is no mapping table to apply, and roughly 539 edges need a judgment
|
|
call each. A large minority are reverse directions (`Verwendet von` 20x, `implementiert durch`,
|
|
`Ersetzt durch`), which under authored directional edges are exactly the edges that stop being
|
|
stored and start being rendered.
|
|
|
|
Rejected alternative, recorded so it is not re-proposed: map the top 20 mechanically and set
|
|
everything else to `see-also`. That would start the new taxonomy with ~370 of ~539 edges on its
|
|
weakest label - the `verwandt mit` sediment this whole change exists to end, re-created as the
|
|
documented initial state.
|
|
|
|
## Closes when
|
|
|
|
Every unit in `plan.md` is published, and:
|
|
|
|
- `wikitool lint` reports zero unlabelled edges and zero labels outside the authorising
|
|
collection's `outbound:` block
|
|
- `wikitool migrate verify --from <pre-migration rev>` reports no wikilink or citation count
|
|
change, and no unbalanced marker
|
|
- `wikitool migrate done 4.0.0 --pages <N>` has run
|
|
|
|
## Checklist
|
|
|
|
- [x] u0 mechanism - taxonomy, `links.py`, `blocks.py`, `xref` rewrite, lint checks,
|
|
`links show` for the inbound view, deletion of the matching layer. No page touched.
|
|
- [x] u1 `kb/entities/` (systems, tools, technologies) - 57 pages, 199 edges, run as five
|
|
sub-sessions (`u1`, `u1-technologies`, `u1-technologies-2`, `u1-tools-1`, `u1-tools-2`,
|
|
`u1-close`) against one 60-call-per-session ceiling; published together as commit
|
|
`b137359`. Deferred cross-collection edges recorded in `glossary.md` for u2/u3.
|
|
- [ ] u2 `kb/entities/` (projects, people) + `kb/comparisons/`
|
|
- [ ] u3 `kb/concepts/`
|
|
- [ ] u4 `kb/sources/`
|
|
- [ ] u5 close-out - `migrate done`, version bump, `CHANGES.md`, workshop close
|
|
|
|
## Measured after u0
|
|
|
|
`lint` against the corpus, with the machinery in place and no page touched:
|
|
|
|
| Finding | Count |
|
|
|---|---|
|
|
| `unlabelled_edges` | **480** - every `related:` entry, since none carries a label yet |
|
|
| `unauthorised_labels` | 0 - nothing declares a label at all, so nothing can be unauthorised |
|
|
| `malformed_edges` | 0 |
|
|
| `unbalanced_markers` | 0 |
|
|
| `orphan_pages` | 1 (`GRUB`, pre-existing) |
|
|
| `broken_links`, `dangling_frontmatter_refs`, `schema_validation_errors` | 0 |
|
|
|
|
480 is the number u1-u4 have to bring to zero. It is larger than the 337 labelled body bullets
|
|
because `related:` also holds entries whose bullet was lost or never written - which is itself a
|
|
finding: the frontmatter and the body had already drifted apart under the old model, and nothing
|
|
could see it while the label lived only in the prose.
|
|
|
|
## Open decisions
|
|
|
|
- **Settled 2026-09-02:** edges are directional; the reverse edge is authored only when it is a
|
|
primary statement on its own page. The inbound view is rendered, not stored.
|
|
- **Settled 2026-09-02:** the 353 provably-redundant `## Siehe auch` edges are dropped
|
|
mechanically. The 202 that are the only connection get a real label each, or are dropped with
|
|
a reason - never converted to `see-also` in bulk.
|
|
- **Settled 2026-09-02:** labels are not localized. `- **depends-on:** [[Hermes]]` is what a
|
|
German page carries.
|