ADR practice
Purpose
Section titled “Purpose”Architecture decisions (ADR index) holds the template and starter decisions (ADR-001–004). This page defines operating rules so ADRs accumulate cleanly as the team and codebase grow.
When to add an ADR
Section titled “When to add an ADR”Create a new ADR (do not only edit narrative docs) when:
- Integration style changes (e.g. webhook-first vs poll-first, OAuth storage).
- Adding/removing DocType overrides of core ERPNext behavior.
- Material changes to guest APIs, auth flows, or webhook verification.
- Scheduler frequency, idempotency, or data retention policy changes in a way that affects operations or compliance.
Small bug fixes and copy edits do not need an ADR.
Numbering
Section titled “Numbering”| Rule | Detail |
|---|---|
| Sequence | ADR-NNN — three digits, monotonic (005, 006, …). |
| Title | Short noun phrase: ADR-005 — Stripe webhook idempotency keys. |
| Status | Proposed → Accepted → optionally Superseded by ADR-XXX. |
Where to store content
Section titled “Where to store content”| Mode | Location | When |
|---|---|---|
| Single file (current default) | Append to Architecture decisions under “Indexed decisions”. | Few decisions per quarter. |
| Split files (optional) | One file per ADR under docs/src/content/docs/reference/adr/ e.g. adr-005-stripe-idempotency.md | Many decisions; easier PR review. |
If you split: replace the long “Indexed decisions” section on the index page with links only (keep template and “Purpose” on the index).
Supersession
Section titled “Supersession”When replacing a decision:
- Add
Superseded by ADR-NNNto the old entry’s Status. - New ADR’s Context should cite the old ADR and why reality changed.
- Link PRs or issues in the new ADR’s Consequences or Code pointers section.
Pull requests
Section titled “Pull requests”- Prefer one ADR per PR when the decision is the main change.
- If the PR implements the decision, add “ADR: ADR-NNN” to the PR title or description for traceability.