Propose an ADR and open a pull request

When to write an ADR

Write an ADR when the change affects architecture, naming, interfaces, workflows, or another decision that should stay understandable after the implementation details change.

For a new proposal, start with status: proposed.

Draft the ADR

Choose the next numbered filename in docs/decisions/ and use a short kebab-case slug.

Example:

032-example-decision.md

Keep title in frontmatter. The docs pipeline uses it as the canonical page title.

The format is based on Structured MADR frontmatter, but the Dataverket author-facing contract for required fields, allowed values, and relationship conventions is documented in ADR frontmatter.

Use this minimal skeleton:

---
title: "Short decision title"
description: "One-sentence summary of the proposal."
type: adr
project: dataverket
category: architecture
tags:
  - example
status: proposed
created: 2026-04-06
updated: 2026-04-06
author: Your Name
---

## Status

Proposed on 2026-04-06 by Your Name.

## Context

Describe the problem, constraints, and why the current state is not good enough.

## Decision

State the proposed change clearly and concretely.

## Consequences

### Positive

- What gets better.

### Negative

- What becomes more expensive, riskier, or harder.

### Neutral

- Secondary effects that are worth recording.

## Decision Outcome

Proposed. Pending review.

## Audit

- 2026-04-06: ADR proposed.

If the proposal depends on another ADR, add a related field in frontmatter. Use ADR frontmatter when you need the exact relationship guidance, including how Dataverket models supersession through status plus related.

Write it as a proposal

Keep the proposal specific enough that reviewers can agree or disagree with it.

  • Explain the actual problem, not just the preferred solution.
  • Show the main tradeoffs.
  • Name the decision you want approved.
  • Keep accepted-state wording out of Status and Decision Outcome until the ADR is actually accepted.

If useful, add short sections such as ## Decision Drivers, ## Considered Options, or ## Related Decisions.

Open the pull request

Create a branch, commit the ADR, push it, and open a pull request against the repo default branch.

Example:

git switch -c adr/propose-example-decision
git add docs/decisions/032-example-decision.md
git commit -m "docs: propose ADR 032 example decision"
git push -u origin HEAD

In the pull request description, include:

  • the problem the ADR is trying to solve
  • the proposed decision
  • the main alternatives or tradeoffs
  • the people who should review it

Verify before review

ADR validation is enforced by the aggregated docs pipeline in docs-builder. Use ADR frontmatter for the author-facing contract and ADR validation for validator behavior and section enforcement details.

Before asking for review, verify that the ADR still passes the current rules:

cd ../docs-builder
task validate

If you also want to check the rendered site output, run:

task build