1.6 KiB
History —
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.