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 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 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)
|
- [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)
|
- [The consequence in practice](#the-consequence-in-practice)
|
||||||
<!-- /wikitool:toc -->
|
<!-- /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
|
checkout among possibly several and is gitignored for that reason, so its absence is a normal
|
||||||
state rather than a sign setup was skipped.
|
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
|
## The consequence in practice
|
||||||
|
|
||||||
An upgrade sorts every shipped path into three categories, not two - and the third one only
|
An upgrade sorts every shipped path into three categories, not two - and the third one only
|
||||||
|
|||||||
Reference in New Issue
Block a user