Decisions

Purpose: How to decide on architecture decisions with a structured, bias-aware process.

Audience: Developers and Architects

Status: Draft

Rationale

Decisions are easily influenced by group thinking, confirmation bias, and premature convergence on solutions. This workflow helps to avoid common pitfalls and to get technically sound decisions by:

  • Separating problem definition from solution exploration
  • Ensuring all stakeholders understand the problem before proposing solutions
  • Exploring multiple alternatives before committing to one
  • Making the decision-making process transparent and reviewable

Quick Reference

Decision Lifecycle Overview

This document describes all steps a decision can run through:

flowchart LR
  s((Start)) --> Drafts --> prob(Problem Clear) --> alt(Solutions Clear) --> review(In Review) -- merge --> Decided
    -- merge --> part(Partially Implemented) --> Implemented
  %% Shortcuts:
  s --> Decided
  Drafts -- merge --> Decided
  prob -- merge --> Decided
  alt -- merge --> Decided
  Decided -- merge --> Implemented

Key Points:

  • The label merge on edges means a decision MR must be merged before targeting the next step
  • Decisions not yet "Decided" may become "Drafts", "Rejected" or "Postponed" at any point
  • The first MR for a decision usually creates it in "Drafts" state, but can advance further during review

Quick Rules

  1. First MR: Create decision as "Drafts" (recommended), "Problem Clear", "Solutions Clear" or "Decided"
  2. To merge as "Decided", the MR must:
    • Only contain changes to one decision
    • Already start with the decision as "Decided"
    • Have clearly stated problem and all solutions fully explored
    • Only contain discussions about choosing between solutions or details
    • If direction changes, move back to at least "In Review"
  3. After "Decided": Can be moved to "Partially Implemented" or "Implemented" by any MR

Workflow Steps

1. Drafts

This step is highly recommended and required if the problem is not yet clear to all core developers.

Who: Decider (person proposing the decision)

When: When there is a problem that needs a decision and the solution cannot easily be changed afterwards, such as:

  • Which library to use
  • Which architectural patterns to use
  • Whether frontend or backend is responsible for a feature
  • Which programming language to use

Actions:

  • Create a new MR which copies the decision template doc/decisions/TEMPLATE.md
  • Use the MR template for decisions
  • Fill out at least the "Problem" section
  • Add optional backlinks from related decisions

Result: A merged MR where the problem is documented and solutions are explored, but no decision is made yet.

Details:

This step is brainstorming for completely new ideas. The MR should contain:

  • One decision with at least "Problem" filled out
  • "Decision", "Rationale" and "Implications" are not yet filled out
  • Optional backlinks from related decisions

No agreement about anything is needed to merge decisions in this stage.

2. Problem Clear

Who: Decider and core developers

When: After the problem has been documented in Drafts

Actions:

  • Clarify the importance of the problem: Why should we spend time and energy on this instead of another problem?
  • Clarify the scope of the decision
  • Clarify relation to other problems
  • Ensure everyone can describe an experiment or test case that shows if a solution fixes the problem

Result: Everyone agrees that the problem exists and is worth solving.

Details:

This step is very important for smooth progress in later stages. Key points:

  • Don't have a fixed mindset about a preferred solution from the beginning
  • Focus on understanding the problem deeply without prejudice
  • Establish clear criteria for what would constitute a solution

Everyone must agree that the problem exists and is worth solving before a "Problem Clear" MR can be merged. A problem is clear if everyone can describe an experiment or test case that shows if a solution fixes the problem.

3. Solutions Clear

This step is recommended if it is not yet clear to core developers which solution is the best.

Who: Decider with input from core developers and reviewers

When: After the problem is clear

Actions:

  • Ensure problem, constraints and assumptions are well-explained and sound
  • Create links from/to related decisions
  • Describe several alternative solutions, each with:
    • Proposal
    • Rationale
    • Implications (optional at this stage)
  • Explore trade-offs, combinations and pros/cons of solutions
  • Keep "Decision", "Rationale" and "Implications" sections not filled out

Result: All reviewers understand the given solutions and cannot come up with better alternatives. The solution space is clear.

Details:

The decision should describe multiple solutions, not just one. For each solution provide:

  • A proposal for the solution
  • Rationale for why it could work
  • Optionally, implications of choosing it

The solutions are clear if all reviewers understand them and no reviewer can come up with better solutions. The solution space is clear when trade-offs, combinations and pros/cons are explored. Decision author and reviewers are satisfied that every useful solution is present.

4. In Review

Who: Decider and reviewers

When: After solutions are clear and one has been chosen

Actions:

  • Add the chosen decision to the "Decision" section
  • Polish the last details of the chosen decision
  • Verify consistency with other decisions
  • Check links from/to related decisions
  • Fully fill out "Decision", "Rationale" and "Implications" sections

Result: A decision ready to be marked as "Decided" after one more review cycle.

Details:

Without merges in between, this is the last step reachable for a decision MR that started in "Drafts".

5. Decided

This step is mandatory. There must be a dedicated decision MR that puts the decision into "Decided".

Who: Decider and reviewers

When: After "In Review" and all concerns are addressed

Actions:

  • Finalize "Decision", "Rationale" and "Implications" according to reviews
  • Ensure only a single decision is modified in the MR (except backlinks)
  • Create or reference implementation MR(s)

Result: An approved architectural decision that is ready to implement.

Details:

  • Decisions that need an update (e.g., because assumptions changed) sometimes directly start with "Decided"
  • Usually, decisions at this step already have an implementation MR

In this step, decision MRs only modify a single decision. Only exceptions like backlinks from other decisions are allowed.

6. Partially Implemented

Who: Implementer

When: During incremental implementation

Actions:

  • Implement part of the decision
  • Update the "Implications" section to clearly state how much is implemented
  • Create issues for remaining pieces

Result: Partial implementation with clear tracking of what remains.

Details:

We want to avoid this step; ideally MRs fully implement decisions. Nevertheless, this can be useful for decisions that need to be done for every module, plugin, or library where only a few not-so-important modules are missing.

7. Implemented

This step is mandatory. There must be a decision MR that puts the decision into "Implemented".

Who: Implementer and documenter

When: After the decision is fully implemented

Actions:

  • Strip details from the decision and move them to the documentation
  • Add link from documentation to the decision
  • Add link from decision to the new documentation
  • Update decision status to "Implemented"

Result: Decision is fully implemented and documented.

Details:

In this step, decision MRs only modify a single decision. More exceptions are allowed here; in particular, documentation updates are okay.

Special Cases

Postponed Decisions

When: Used for decisions that:

  • Would be useful contributions but nobody currently has time to focus on the problem
  • Have been neglected because decision authors focused on something more important

Purpose: Keep the "Drafts" folder clean by moving decisions that won't progress immediately.

Actions:

  • Update status to "Postponed"
  • Add explanation for why it's being postponed
  • Can be revisited when circumstances change

Rejected Decisions

When: Used for decisions where:

  • Status quo wins
  • Consensus exists that the decision should not be taken right now
  • No decision is actually needed

Purpose: Keep the "Drafts" folder clean and document what was considered but not pursued.

Actions:

  • Update status to "Rejected"
  • Document why it was rejected
  • Note: Can be revisited if circumstances change

Examples

Example 1: New Library Selection

Step 1 (Drafts): Create MR with problem "Need date formatting library"
Step 2 (Problem Clear): Team agrees date formatting is important and current solution is inadequate
Step 3 (Solutions Clear): Explore date-fns, dayjs, and moment.js with pros/cons
Step 4 (In Review): Choose date-fns, document rationale and implications
Step 5 (Decided): Merge decision to use date-fns
Step 6 (Implemented): Replace all date formatting code, update documentation
Result: Consistent date formatting across codebase

Example 2: Fast-Track Decision

Step 1 (Decided): Create MR directly as "Decided" for updating an existing decision due to changed assumptions
Step 2 (Implemented): Implement changes and update documentation
Result: Updated decision reflects new reality

Troubleshooting

Common Issues

Problem: MR contains multiple decisions and cannot be merged as "Decided" Solution: Split into separate MRs, one per decision. Only the final "Decided" MR requires single-decision constraint.

Problem: Reviewers keep suggesting new solutions during "In Review" Solution: Move back to "Solutions Clear" to properly explore the solution space before continuing.

Problem: Problem definition keeps changing during solution exploration Solution: Move back to "Problem Clear" to establish consensus on what problem is being solved.

Problem: Decision has been in "Drafts" for months with no progress Solution: Move to "Postponed" to keep drafts clean, or to "Rejected" if no longer relevant.

Open Points

  • Define specific criteria for what constitutes "core developer agreement"
  • Create examples of good vs. poor problem statements
  • Establish guidelines for when to skip steps (fast-track decisions)

Notes