docs: ownership-and-templates benennt die gemischte Zustaendigkeit im Seiten-Type-Spec (Nachzug zu #99)
CI / verify (push) Successful in 48s
CI / verify (push) Successful in 48s
Files changed: - docs/ownership-and-templates.md
This commit is contained in:
@@ -16,6 +16,7 @@ overwriting them would silently erase a choice someone made on purpose.
|
||||
- [Why silent overwrite is the failure being designed against](#why-silent-overwrite-is-the-failure-being-designed-against)
|
||||
- [Why the boundary is a predicate rather than a list](#why-the-boundary-is-a-predicate-rather-than-a-list)
|
||||
- [Why a `.template`, not just an absent file](#why-a-template-not-just-an-absent-file)
|
||||
- [Where the file boundary strains](#where-the-file-boundary-strains)
|
||||
- [The consequence in practice](#the-consequence-in-practice)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
@@ -91,6 +92,31 @@ also why `ENVIRONMENT.md` only warrants a WARN rather than a FAIL when absent -
|
||||
checkout among possibly several and is gitignored for that reason, so its absence is a normal
|
||||
state rather than a sign setup was skipped.
|
||||
|
||||
## Where the file boundary strains
|
||||
|
||||
"The file itself already answers that" holds for every file above except one shape, and it is
|
||||
worth naming rather than discovering: a `root: kb` type-spec has two audiences inside one file.
|
||||
|
||||
Its authoring guidance - when to use this type, what each frontmatter field means, how to cite -
|
||||
is instruction to an agent. It reads like the stack's own prose because it *is* the stack's own
|
||||
prose: a later release that learns something about writing entity pages would want to improve it
|
||||
everywhere. Its `## Template` block and its `layout:` titles are the opposite: they become the
|
||||
literal headings of pages this instance writes, in the language this instance chose, and no
|
||||
release has any business touching them.
|
||||
|
||||
Ownership is per file, so the instance keeps both halves. The template half is correct that way.
|
||||
The guidance half pays for it: an instance that adopted its type-specs at setup will never
|
||||
receive an improvement to them again, because `dist upgrade` writes the `.template` beside the
|
||||
adopted file and never the file itself. Nothing breaks, and nothing reports it - the instance
|
||||
simply keeps reading the guidance it was handed the day it was created.
|
||||
|
||||
This is not an argument against the per-file boundary; the boundary is what makes an upgrade
|
||||
safe at all, and merging inside a shared file is the failure the whole section above is about.
|
||||
It is an argument that this particular file is cut in the wrong place. Splitting it - the
|
||||
template block into its own instance-owned file, the guidance staying stack-owned and shipping
|
||||
verbatim - would put the boundary back where the audiences actually divide, and would cost a
|
||||
migration for every instance that already adopted one.
|
||||
|
||||
## The consequence in practice
|
||||
|
||||
An upgrade sorts every shipped path into three categories, not two - and the third one only
|
||||
|
||||
Reference in New Issue
Block a user