ADR-NNN: Short noun phrase describing the decision¶
Status¶
Accepted — YYYY-MM-DD.
Context¶
State the forces in tension that made this decision necessary. A reader who knows nothing about the project should, after reading this section, understand why a decision had to be made at all. Two or three paragraphs is typical; more than a page is a warning sign that the ADR is doing too much.
Decision¶
State what was decided, in the imperative. One or two sentences. The decision should be extractable as an elevator pitch.
Expand with additional paragraphs only if the decision has internal structure — e.g., "A core X is defined as ...; a companion Y is defined as ...; the two are related by ...."
Consequences¶
List the effects of the decision. Positive, negative, and neutral. Be honest about the costs; ADRs are read by future contributors who will live with those costs.
- Positive consequence.
- Negative consequence.
- Neutral consequence (a fact that follows from the decision but is neither good nor bad).
Alternatives considered¶
Briefly list the other options that were on the table and the reason each was rejected. The purpose is not to re-argue the decision but to reassure readers that the rejected options were genuinely considered.
- Alternative A. Brief description. Rejected because …
- Alternative B. Brief description. Rejected because …
References¶
- Issue — link.
- Pull request — link.
- External discussion — link.
- Prior art — link.