types/: Seiten-Type-Spec-Anleitungsprosa in stackeigene guidance-Datei ausgelagert (schliesst #104)
Files changed: - AGENTS.md - CHANGES.md - VERSION - docs/ownership-and-templates.md - instructions/migrations/6.0.0-type-guidance-split.md - instructions/setup-instance.md - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/types_cmd.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_dist_upgrade.py - tools/chemenu/tests/test_type_resolver.py - tools/chemenu/tests/test_types_cmd.py - tools/chemenu/type_resolver.py - tools/chemenu/types_core.py - types/comparison.guidance.md - types/comparison.md - types/concept.guidance.md - types/concept.md - types/entity.guidance.md - types/entity.md - types/source.guidance.md - types/source.md - types/type-guidance.md - types/type-guidance.schema.yaml - types/type-spec.md
This commit is contained in:
@@ -0,0 +1,116 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: 6.0.0-type-guidance-split
|
||||
description: "Add a guidance: field to an adopted root:kb type-spec so it starts receiving the stack's authoring-prose improvements again, without touching the type-spec's own frontmatter or template."
|
||||
manual: true
|
||||
migrates_to: 6.0.0
|
||||
migration_kind: assisted
|
||||
obligation: offered
|
||||
---
|
||||
# Link an adopted type-spec to its stack-owned guidance file (6.0.0)
|
||||
|
||||
Before 6.0.0, a `root: kb` type-spec (`entity`, `concept`, `source`, `comparison`, or one this
|
||||
instance added itself) carried its generic authoring prose - when to use the type, when not to,
|
||||
mechanism-level advice such as citation and provenance rules - in the same file as its frontmatter
|
||||
configuration and its `## Template` block. Adopting the type-spec at setup meant adopting all of
|
||||
it at once, and an upgrade never touched the adopted file again: the prose an instance received
|
||||
was frozen at the day it ran `setup-instance.md`, while every later improvement shipped only in
|
||||
the `.template` beside it (`docs/ownership-and-templates.md` § "Where the file boundary used to
|
||||
strain").
|
||||
|
||||
6.0.0 splits that prose into a separate, stack-owned `types/<name>.guidance.md`, linked from the
|
||||
type-spec via an optional `guidance:` frontmatter field. The new file ships verbatim and upgrades
|
||||
like any other machinery file from here on - but only once a type-spec actually points at it.
|
||||
Taking this offer is exactly that: adding one frontmatter line per adopted type-spec. It is
|
||||
`assisted`, not `mechanical`, because whether this instance's own copy of the prose has diverged
|
||||
from the shipped default is a judgment call a script cannot make.
|
||||
|
||||
This migration is **offered, not required**. A type-spec with no `guidance:` keeps working
|
||||
exactly as it did before 6.0.0 - it is described from its own body alone. Declining costs nothing
|
||||
except future improvements to the prose half; nothing about the machinery stops fitting.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to run](#when-to-run)
|
||||
- [Steps](#steps)
|
||||
- [How to tell a migrated type-spec from an unmigrated one](#how-to-tell-a-migrated-type-spec-from-an-unmigrated-one)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to run
|
||||
|
||||
Any time after installing 6.0.0 machinery over an instance that adopted at least one `root: kb`
|
||||
type-spec before this migration existed. `tools/wikitool migrate status` lists it under "optional
|
||||
upgrade(s) available"; taking it is not gated on anything else being current.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Confirm the new guidance files actually arrived.** `dist upgrade` writes `types/<name>.guidance.md`
|
||||
as an ordinary new/unchanged file - it does not depend on this migration at all. If
|
||||
`ls types/*.guidance.md` shows nothing, the machinery upgrade has not landed yet; run that
|
||||
first.
|
||||
|
||||
2. **For each adopted `root: kb` type-spec, decide whether its authoring prose still matches the
|
||||
shipped default.** Compare the type-spec's current prose (everything outside `## Frontmatter`
|
||||
and `## Template`) against the corresponding `types/<name>.guidance.md`:
|
||||
|
||||
- **Unchanged, or changed only in ways this instance is happy to lose:** proceed to step 3
|
||||
directly - the new guidance file already carries the improved version.
|
||||
- **Locally edited in a way worth keeping** (a house style note, an extra rule specific to
|
||||
this corpus): that edit has to move somewhere before the old prose is dropped. Either fold
|
||||
it into a local copy of the guidance file this instance then owns for itself (any path is
|
||||
valid for `guidance:`, not only the shipped one), or keep it in the type-spec's own body
|
||||
instead of adding `guidance:` at all - both are legitimate; declining the stack default for
|
||||
one type is not an error.
|
||||
|
||||
3. **Add `guidance: types/<name>.guidance.md` to the type-spec's frontmatter** - by hand, the same
|
||||
way any other type-spec frontmatter field is written (a type-spec is machinery, not a `kb/`
|
||||
page, so this is not a `wikitool touch` call). Do not remove `## Frontmatter` or `## Template`;
|
||||
only the generic prose around them is what the guidance file now carries.
|
||||
|
||||
4. **Delete the now-duplicated prose from the type-spec**, keeping the H1, a short pointer to the
|
||||
guidance file (`types/entity.md`'s own current text is the worked example), `## Frontmatter`
|
||||
and `## Template`. Where step 2 found a local edit worth keeping and it lives in the
|
||||
type-spec's own body rather than a private guidance file, leave that part exactly where it is.
|
||||
|
||||
5. **Verify:**
|
||||
|
||||
```bash
|
||||
tools/wikitool types describe <name>
|
||||
```
|
||||
|
||||
The output must read the same as it did before this migration - the guidance prose composed
|
||||
ahead of the type-spec's own body, in one answer. A diff against the pre-migration output of
|
||||
the same command, restricted to wording, is expected only where step 2 found something to
|
||||
drop or fold in; the structure (frontmatter fields, template block) must be byte-identical.
|
||||
|
||||
6. **Record it:**
|
||||
|
||||
```bash
|
||||
tools/wikitool migrate done 6.0.0 --pages 0
|
||||
```
|
||||
|
||||
`--pages 0` because no `kb/` page changes - this migration touches machinery under `types/`
|
||||
only. This does **not** advance `kb_version`, per `obligation: offered` above; it only marks
|
||||
the offer as taken so `migrate status` stops listing it.
|
||||
|
||||
## How to tell a migrated type-spec from an unmigrated one
|
||||
|
||||
`grep -L '^guidance:' types/*.md` (excluding `.guidance.md` files themselves, which never carry
|
||||
the field) lists every `root: kb` type-spec that has not taken the offer yet.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **A type this instance wrote entirely for itself?** No `types/<name>.guidance.md` exists for
|
||||
it and none should be authored to match this migration artificially - `guidance:` is for
|
||||
receiving a *stack* default, and a self-written type has none to receive. Leave it as it is.
|
||||
- **Local prose worth keeping, but no interest in maintaining a private guidance file?** Skip
|
||||
`guidance:` for that one type-spec. Nothing forces uniformity across an instance's own types.
|
||||
|
||||
## Scope
|
||||
|
||||
For `types/` machinery, not `kb/` content - the one migration document in this directory that
|
||||
is. No page's frontmatter or body changes, `sources coverage`/`lint`/`kb_version` are all
|
||||
unaffected, and `migrate done`'s `--pages` is `0` for exactly that reason.
|
||||
@@ -89,9 +89,16 @@ and ready for its first ingest.
|
||||
|
||||
Under `types/` this covers exactly the type-specs with `root: kb` - `entity`, `concept`,
|
||||
`source`, `comparison` - along with their `.schema.yaml`. They describe pages *this*
|
||||
instance writes, so they belong to it: prose, template and language may all be rewritten.
|
||||
`instruction`, `lint-report` and `type-spec` describe stack artifacts and arrive
|
||||
unchanged.
|
||||
instance writes, so they belong to it: frontmatter, template and language may all be
|
||||
rewritten. `instruction`, `lint-report`, `type-spec` and `type-guidance` describe stack
|
||||
artifacts and arrive unchanged - the glob above never matches them because none of them
|
||||
ships as a `.template` in the first place.
|
||||
|
||||
A `root: kb` type-spec's generic authoring guidance (when to use the type, when not to)
|
||||
is not part of this adoption at all: it lives in a sibling `types/<name>.guidance.md`
|
||||
this instance never renames, the same as `instruction.md` - it ships verbatim and a later
|
||||
`dist upgrade` improves it directly, without the type-spec that links it needing to be
|
||||
touched. `types/type-spec.md` § "Anatomy of a type" has the shape.
|
||||
|
||||
2. Ask the user for the KB language. `kb/CONVENTIONS.md.template` defaults to **English**;
|
||||
[kb-profiles.md](kb-profiles.md) additionally holds a complete German profile, whose full
|
||||
|
||||
Reference in New Issue
Block a user