RegelRecht

Appearance

RFC-000: RFC Process ​

Status: Accepted Date: 2025-11-19 Authors: regelrecht team

Context ​

As the regelrecht project grows, we need a structured way to document design decisions and architectural choices. Important decisions about law execution, article resolution, URI handling, and system architecture should be documented with their rationale for future reference.

Without a formal process, design decisions live in:

  • Pull request discussions (hard to discover)
  • Code comments (fragmented)
  • Institutional memory (lost when team members change)

We need a lightweight but structured approach to capture these decisions.

Decision ​

We adopt an RFC (Request for Comments) process where significant design decisions are documented as markdown files in docs/rfcs/.

RFC Template ​

markdown
# RFC-NNN: Title

**Status:** [Draft | Proposed | Accepted | Rejected | Superseded]
**Date:** YYYY-MM-DD
**Authors:** Name(s)

## Context
Why is this decision necessary? What problem does it solve?

## Decision
What was decided?

## Why
Benefits, tradeoffs, alternatives

Numbering Convention ​

  • RFC-000 is reserved for this process document
  • Subsequent RFCs are numbered sequentially: RFC-001, RFC-002, etc.
  • Once a number is assigned, it is never reused (even for rejected RFCs)

Status Values ​

  • Draft: Work in progress, not yet ready for discussion
  • Proposed: Under discussion, not yet decided
  • Accepted: Decision is made and should be followed
  • Rejected: Proposal was considered but not accepted
  • Superseded: Replaced by a newer RFC (reference the new RFC)

When to Write an RFC ​

Write an RFC for: ​

  • Law representation formats: Changes to YAML schema, article structure, machine_readable sections
  • Execution engine architecture: Changes to how the engine processes articles, resolves URIs, handles parameters
  • Integration patterns: How components interact (engine ↔ regulation files, API designs)
  • Cross-cutting design patterns: Decisions that affect multiple parts of the system

Skip RFC for: ​

  • Bug fixes: Unless they require architectural changes
  • Individual law implementations: Adding new YAML files following existing patterns
  • Routine implementation work: Following established patterns
  • Temporary workarounds: Meant to be replaced soon

When in doubt, ask: "Would someone maintaining this code in 6 months benefit from understanding why we made this decision?"

Why ​

Benefits ​

  • Future contributors understand why decisions were made
  • Writing forces clear problem articulation
  • Decisions don't live only in people's heads
  • RFCs evolve alongside code in version control
  • One place to find architectural decisions

Tradeoffs ​

  • Adds process overhead for major decisions
  • Requires discipline to maintain
  • Can become outdated if not updated

We accept these tradeoffs because the benefits of documented decisions outweigh the cost of the process.

Alternatives Considered ​

  1. Code comments only: Hard to discover, fragmented across codebase
  2. Wiki/Confluence: Separate from code, unclear version control
  3. GitHub Issues: Good for discussions, but not structured for long-term documentation
  4. ADRs (Architecture Decision Records): Very similar to RFCs; we chose "RFC" terminology as it's more familiar in open source

References ​