Skip to main content

ADR-0001: Use ADRs to Record Significant Decisions

Accepted

Context​

As an open source project, Ideal needs a way to document significant decisions — architectural choices, design directions, and policy changes — so that contributors can understand not just what was decided, but why. Without a structured record, the reasoning behind past decisions is lost, and the same ground gets covered repeatedly as the project and its community grow.

Decision​

Significant decisions will be recorded as Architecture Decision Records (ADRs): short Markdown files stored in community/decisions/, submitted and reviewed as patches through ideal-devel like any other contribution. Each ADR captures the context, the decision, the alternatives considered, and the consequences.

Both accepted and rejected proposals result in a merged ADR, so the record reflects not just what was chosen but also what was considered and set aside.

Alternatives Considered​

Mailing list archives only. Discussion threads on ideal-devel are already archived and publicly accessible. However, mailing list archives are hard to search, lack structured metadata, and do not provide a clear index of what was decided. They are a good discussion medium, not a decision record.

A separate RFC repository. Some projects maintain a dedicated repository for proposals, separate from the main documentation. This adds coordination overhead with no benefit at Ideal's current scale.

Consequences​

  • Significant decisions have a permanent, structured, version-controlled record.
  • The reasoning behind past decisions is accessible to new contributors.
  • Contributors must be comfortable with git send-email to submit ADRs, which is already required for patches.