The kickoff for this repository asks that every architecture decision is written
down with its reasons before anything depends on it. Nothing here says what a
written decision looks like, so ten of them written on ten different days would
answer ten different sets of questions, and a reader could not tell a decision
from an opinion.
This is the first issue on the board that produces a file, and every other
decision issue depends on the shape it fixes.
What the format has to carry
The decision itself in one sentence. The reasons, stated as what would have gone
wrong without it. The alternatives that were considered and what each one cost.
What would reverse the decision, written concretely enough that a reader can tell
whether it has happened. The date it was taken. Records are added and superseded,
never edited in place, so a superseded record keeps its text and gains a pointer
to the one that replaced it.
Done when
docs/decisions/0001-decision-records.md exists, states those required sections,
and is itself written in that shape. docs/decisions/README.md lists every
record by number and title. A reader can open the index and reach every record
from it.
The kickoff for this repository asks that every architecture decision is written
down with its reasons before anything depends on it. Nothing here says what a
written decision looks like, so ten of them written on ten different days would
answer ten different sets of questions, and a reader could not tell a decision
from an opinion.
This is the first issue on the board that produces a file, and every other
decision issue depends on the shape it fixes.
What the format has to carry
The decision itself in one sentence. The reasons, stated as what would have gone
wrong without it. The alternatives that were considered and what each one cost.
What would reverse the decision, written concretely enough that a reader can tell
whether it has happened. The date it was taken. Records are added and superseded,
never edited in place, so a superseded record keeps its text and gains a pointer
to the one that replaced it.
Done when
docs/decisions/0001-decision-records.mdexists, states those required sections,and is itself written in that shape.
docs/decisions/README.mdlists everyrecord by number and title. A reader can open the index and reach every record
from it.