46 lines
1.6 KiB
Markdown
46 lines
1.6 KiB
Markdown
|
# History — <Project>
|
||
|
|
|
||
|
|
```
|
||
|
|
Status: Current
|
||
|
|
Owner: <who maintains this>
|
||
|
|
Last reviewed: <YYYY-MM-DD>
|
||
|
|
Governs: the narrative of how this project got to where it is
|
||
|
|
Review trigger: A decision reversed, a direction abandoned, or a rewrite
|
||
|
|
```
|
||
|
|
|
||
|
|
## What this is for
|
||
|
|
|
||
|
|
<The story, in prose: what was tried, what was abandoned, and why. A reader
|
||
|
|
arriving in six months wants to know which walls have already been walked into,
|
||
|
|
and that is not something a commit log tells them.>
|
||
|
|
|
||
|
|
**This is a record of *then*, never a description of *now*.** That distinction is
|
||
|
|
what makes it safe to leave alone as the project changes — a history document
|
||
|
|
that gets edited to stay current is not a history, it is a second and competing
|
||
|
|
description of the present.
|
||
|
|
|
||
|
|
If you find yourself updating a sentence here because the code changed, the
|
||
|
|
sentence belongs somewhere else.
|
||
|
|
|
||
|
|
## Decisions and their reasons
|
||
|
|
|
||
|
|
<One entry per decision that would otherwise look arbitrary later. The reason
|
||
|
|
matters more than the decision: "we chose X" ages badly, "we chose X because Y
|
||
|
|
was true at the time" survives Y stopping being true.>
|
||
|
|
|
||
|
|
| When | What was decided | Why, at the time |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| <> | <> | <> |
|
||
|
|
|
||
|
|
## What was tried and dropped
|
||
|
|
|
||
|
|
<The most useful section, and the one most often missing. An approach that was
|
||
|
|
abandoned for a good reason will be proposed again by somebody who does not know
|
||
|
|
it was tried — including you, in a year.>
|
||
|
|
|
||
|
|
## What this file is not
|
||
|
|
|
||
|
|
- **Not the plan.** That is `docs/planning/PROJECT_PLAN.md`.
|
||
|
|
- **Not the work list.** Open work lives in the tracker as milestones and issues.
|
||
|
|
- **Not a changelog.** Dated entries go in `docs/history/DEVELOPMENT_LOG.md`.
|