Files changed: - AGENTS.md - CHANGES.md - INSTALL.md - README.md - VERSION - docs/knowledge-and-commitment.md - instructions/dev/doc-pull-through.md - instructions/setup-instance.md - instructions/upgrade-instance.md - tools/README.md
This commit is contained in:
1 parent
44909c9e47
commit
1d695f6536
10 files changed
+296
-24
No files matched your search
@@ -91,9 +91,14 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
|
||||
tools/wikitool dist upgrade <tarball> --dry-run
|
||||
```
|
||||
|
||||
`unchanged` / `new` / `locally changed` / `removed from the release`. The first two need no
|
||||
decision. `locally changed` is step 6. `removed` matters only if `--prune` is wanted, which is
|
||||
optional and never required.
|
||||
`unchanged` / `new` / `locally changed` / `removed from the release`. `unchanged` needs no
|
||||
decision. `new` needs one only in a single shape: a `<name>.template` for a page type or
|
||||
collection this instance does not have yet. `dist upgrade` writes the template and stops there
|
||||
- adopting it (copying it to the unsuffixed name) is the instance's own act, and where the
|
||||
stack *requires* that type the omission is what step 9's `docs verify` refuses. Step 2's
|
||||
**Breaking Change:** line says when a release is in that shape; step 9 has the repair.
|
||||
`locally changed` is step 6. `removed` matters only if `--prune` is wanted, which is optional
|
||||
and never required.
|
||||
|
||||
6. **Only if a file is reported as locally changed: decide whose file it is, then reconcile it.**
|
||||
The classification is against the sha256 the *installed* release recorded, so "locally
|
||||
@@ -149,9 +154,24 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
|
||||
A `docs verify` failure naming a missing or stale table of contents is repaired with
|
||||
`tools/wikitool docs toc --apply`, never by hand - a release that widened the set of files
|
||||
carrying a region will produce exactly that on files this instance adopted before the
|
||||
widening. Any other failure is read against step 2's **Breaking Change:** line: if the release
|
||||
predicted it, the notes also say what fixes it; if it did not, stop and report it rather than
|
||||
improvising.
|
||||
widening.
|
||||
|
||||
A failure naming a page type the stack requires, or the collection that type's `base_dir:`
|
||||
points at, is the other repairable shape - the `new` template from step 5 that nobody adopted.
|
||||
The fix is the ordinary adoption every `root: kb` type already needs, not a data migration:
|
||||
copy the shipped templates to their unsuffixed names, then fill the instance-owned parts
|
||||
(language, template text, any extra fields) the way step 5 of
|
||||
[setup-instance.md](setup-instance.md) describes for a fresh instance.
|
||||
|
||||
```bash
|
||||
cp types/<name>.md.template types/<name>.md
|
||||
cp kb/<collection>/COLLECTION.md.template kb/<collection>/COLLECTION.md
|
||||
```
|
||||
|
||||
The `.template` files stay where they are - they are the source for the next upgrade's
|
||||
comparison. Any other failure is read against step 2's **Breaking Change:** line: if the
|
||||
release predicted it, the notes also say what fixes it; if it did not, stop and report it
|
||||
rather than improvising.
|
||||
|
||||
10. **Publish the machinery swap.** A release swap is far above the Mass-Update Gate's threshold,
|
||||
so expect exit 42. That is not an error and not yours to clear: reproduce the file breakdown
|
||||
|
||||
Reference in new issue
Block a user