Name the commit the knowledge base's records now come from, and link research with touches and decisions with rests-on (review of #312)
This commit is contained in:
@@ -23,8 +23,7 @@ README = "02-DECISIONS/README.md"
|
||||
|
||||
# A topic in the README's reading order, e.g.
|
||||
# 1. **What the mesh is** — `topic: the mesh`. What it is for, ...
|
||||
# The knowledge base (mesh-knowledge, reference.go) and the records module's `records_decisions` read the
|
||||
# same line, so the form is a contract.
|
||||
# The knowledge base (mesh-knowledge, reference.go) reads the same line, so the form is a contract.
|
||||
TOPIC_LINE = re.compile(r"^\d+\.\s+\*\*(?P<label>[^*]+)\*\*\s+—\s+`topic:\s*(?P<topic>[^`]+)`", re.M)
|
||||
|
||||
# What a stored list looks like: the old markers, or a line of the list index.py used to print.
|
||||
|
||||
@@ -20,8 +20,8 @@ is written with the knowledge base's verbs, never as a folder here.
|
||||
3. **Propose it.** `knowledge-base.propose` with `kind: research`, the `number` reserve gave, a one-line
|
||||
`title`, `status: active`, `date` (the day it began), and `sections`: its documents in order, each a
|
||||
`name` and its markdown `text`. The first is `00-overview.md`: **what** is being investigated, **why**,
|
||||
and **what it touches**. Name what it touches as `links` of kind `cites` (`"0276"`, `"research 045"`,
|
||||
`"issue 365"`, or a design's path), not only in prose.
|
||||
and **what it touches**. Name what it touches as `links` of kind `touches` (`"0276"`, `"research 045"`,
|
||||
`"issue 365"`, or a design's path), not only in prose, and what it names for another reason as `cites`.
|
||||
4. **Do the research** in further documents of the same effort: notes, option analyses, evidence, draft
|
||||
designs. Each change is `knowledge-base.propose` again with the effort whole and `why`, one line saying
|
||||
why this version. Every version is kept; `knowledge-base.history` lists them and gives the difference
|
||||
|
||||
@@ -48,7 +48,7 @@ clauses in force for a topic or a record).
|
||||
- `sections`: the reasoning, in order: `Context` (what was true, with evidence), `Considered Options`
|
||||
(numbered, each with why it was rejected), `Consequences` (what follows, including what got harder),
|
||||
`How it is checked` (a rule states how it is checked), `References`;
|
||||
- `links`: `extends` for a record it builds on, `supersedes` for one it replaces whole, `changes` with
|
||||
- `links`: `extends` for a record it builds on, `rests-on` for a decision it stands on, `supersedes` for one it replaces whole, `changes` with
|
||||
the clause it replaces part of (`"0276 §4"`, and `from` for the clause of this record that does it),
|
||||
`cites` for any record, effort, issue or design it names;
|
||||
- `homes`: the documents of this repository that cite it, such as the design's path;
|
||||
|
||||
Reference in New Issue
Block a user