torben
eadc052f6c
Files changed: - CHANGES.md - INSTALL.md - VERSION - instructions/publish-cycle.md - instructions/setup-instance.md - tools/CONTRACT.md - tools/chemenu/commands/git_publish.py - tools/chemenu/tests/test_git_publish.py
65 lines
2.3 KiB
Markdown
65 lines
2.3 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: publish-cycle
|
|
description: Close out a change to the wiki - rebuild the provenance index and catalog, append the audit entry, and publish.
|
|
---
|
|
|
|
# Close out a change
|
|
|
|
Run after any change to pages under `kb/`, in this order. The order matters: the catalog is
|
|
built from page frontmatter, and the audit entry should describe a tree that is already
|
|
consistent.
|
|
|
|
## Steps
|
|
|
|
1. **Rebuild the provenance index** - after any change to a source page or an inline citation:
|
|
|
|
```bash
|
|
tools/wikitool sources rebuild-index
|
|
```
|
|
|
|
2. **Rebuild the catalog** - after any page was added, removed, renamed, or had its
|
|
summary/date changed:
|
|
|
|
```bash
|
|
tools/wikitool index rebuild
|
|
```
|
|
|
|
This regenerates `kb/index.md` and every `kb/**/INDEX.md`. Never edit those by hand.
|
|
|
|
3. **Append the audit entry** - one per operation:
|
|
|
|
```bash
|
|
tools/wikitool log append --op ingest|query|lint|create|update|delete|rename|move \
|
|
--title "<what>" --body "<outcome>"
|
|
```
|
|
|
|
This is the one non-idempotent step. If a previous run's outcome is uncertain, read the
|
|
tail of `kb/log.md` before repeating it.
|
|
|
|
4. **Publish:**
|
|
|
|
```bash
|
|
tools/wikitool publish --message "<op>: <description>"
|
|
```
|
|
|
|
## Decision points
|
|
|
|
- **Ten or more files changed?** `publish` exits 42. Show the user its output and stop; see
|
|
[gates.md](gates.md).
|
|
- **Remote unreachable or not configured?** `publish` ends with exit 1 before it commits:
|
|
nothing is staged, committed or pushed, and the message names the remote. Ask the user whether
|
|
to commit locally with `--no-push`, and run that only on their answer. Never push by hand
|
|
(AGENTS.md invariant 5): the next `publish` that reaches the remote sends the local commit
|
|
together with whatever is new. A local-only instance, which has no remote at all, passes
|
|
`--no-push` on every call ([setup-instance.md](setup-instance.md), step 4).
|
|
- **Query or lint pass?** Neither auto-publishes. Run `publish` only if asked to.
|
|
- **Nothing under `kb/` changed?** Skip steps 1 and 2; a change to `tools/` or `instructions/`
|
|
does not affect the catalog.
|
|
|
|
## Scope
|
|
|
|
This is the close-out for wiki *content*. Changes to skills also need
|
|
`tools/wikitool instructions sync` (see [bootstrap.md](bootstrap.md)), and changes to the CLI
|
|
or a contract need `tools/wikitool docs verify`.
|