Fullsend

Appearance

1. Use ADRs for decision making ​

Date: 2026-03-20

Status ​

Accepted

Context ​

Fullsend is a design exploration repo with multiple problem documents that evolve independently. As thinking matures in these problem areas, we need a way to crystallize specific decisions without rushing to conclusions. The existing problem documents are good for exploring the space, but they don't clearly separate "options we're considering" from "decisions we've made."

We want a lightweight process that lets us:

  • Propose decisions that we know need to be made, even before we've chosen an answer.
  • Describe options and trade-offs in a structured way.
  • Record the final decision and its rationale once consensus forms.
  • Keep a clear history of what was decided and why.

Decision ​

We adopt Architecture Decision Records (ADRs), following the format described by Michael Nygard, adapted for this repo's needs.

ADRs live in docs/ADRs/ and follow the naming convention NNNN-short-description.md where NNNN is a unique four-digit number.

Each ADR has a Status field. Valid statuses are:

  • Accepted -- The decision has been made.
  • Deprecated -- The decision is no longer relevant.
  • Superseded -- The decision has been replaced by a later ADR.

Each ADR includes YAML frontmatter with structured metadata:

  • title -- The ADR title (required).
  • status -- Must match the ## Status section in the body (required).
  • relates_to -- A list of problem document names (filenames without .md from docs/problems/) that this ADR relates to. Use "*" for ADRs that apply broadly across all problem areas.
  • topics -- Free-form tags for discoverability.

This frontmatter makes it possible to discover which ADRs relate to a given problem area without manually maintaining cross-reference lists.

ADR linting is borrowed from the konflux-ci/architecture repo and runs in CI to validate statuses, number uniqueness, and frontmatter correctness (including cross-references to problem docs).

Consequences ​

  • Problem documents in docs/problems/ remain the place for open-ended exploration. ADRs are for when a specific decision point has been identified.
  • Contributors propose ADRs via pull requests for discussion before merging.
  • The linting ensures ADRs follow the expected format, catching mistakes early.
  • We inherit a proven format from the broader konflux-ci organization, making it familiar to contributors who work across repos.