This directory contains Architecture Decision Records for the Rue project. ADRs document significant design decisions, providing historical context for why things are the way they are.
An ADR captures:
- Context: Why a decision was needed
- Decision: What we chose to do
- Consequences: Trade-offs and implications
ADRs are the historical record of "why did we do it this way?"
Write an ADR for large features that:
- Touch many files across multiple crates
- Have multiple implementation phases
- Add new runtime functions or IR instructions
- Introduce new type system concepts
- May span multiple development sessions
Do NOT write an ADR for small features like adding a single operator, fixing bugs, or simple refactoring. Those just need a Linear issue (team "Rue").
Rule of thumb: If it needs a preview feature gate, it needs an ADR.
proposal → accepted → implemented
| Status | Meaning |
|---|---|
proposal |
Under discussion, not yet approved |
accepted |
Design approved, implementation in progress |
implemented |
Feature complete, language parts in spec |
superseded |
Replaced by a newer ADR |
rejected |
Considered but deliberately not adopted, or rendered moot |
When a feature is implemented:
- Language semantics move to the specification
- The ADR becomes historical reference
- Status updates to
implemented
cp docs/designs/0000-template.md docs/designs/NNNN-<feature>.mdUse the next available 4-digit number.
---
id: 0006
title: Your Feature Title
status: proposal
tags: [types, syntax] # relevant tags
feature-flag: your-feature # for preview gating
created: 2025-01-15
accepted: # fill when accepted
implemented: # fill when implemented
spec-sections: [] # fill when language parts move to spec
superseded-by: # fill if superseded
---Summary: One paragraph overview
Context: Why is this needed? What problem does it solve?
Decision: Technical details - syntax, semantics, implementation approach
Implementation Phases: Break into independently-committable chunks
- [ ] **Phase 1: Core parsing** - RUE-NNN
- [ ] **Phase 2: Type checking** - RUE-NNNConsequences: Positive, negative, and neutral implications
Open Questions: Unresolved issues (for proposals)
Future Work: Out of scope for this ADR, but related
After the ADR is drafted, file the tracking issues in Linear (team "Rue") via the
Linear MCP tools — see the "Issue Tracking with Linear" section of the root
CLAUDE.md for the full workflow:
- Create a parent (epic) issue with
save_issue(team: "Rue"), linking the ADR in the description - Create a sub-issue per phase with
save_issue(parentId: <epic RUE-NN>)
Update the ADR with the resulting Linear issue IDs (RUE-NN).
In crates/rue-error/src/lib.rs:
pub enum PreviewFeature {
// ...
YourFeature,
}See 0000-template.md for the full template.
Required sections:
- Frontmatter (YAML)
- Status
- Summary
- Context
- Decision
- Implementation Phases
- Consequences
Optional sections:
- Open Questions (for proposals)
- Future Work
- References
Use tags to categorize ADRs:
| Tag | For |
|---|---|
types |
Type system changes |
syntax |
Language syntax |
semantics |
Runtime behavior |
compiler |
Compiler internals |
process |
Development process |
Tags are freeform - add new ones as needed.
ADRs and preview features are tightly coupled:
- Every ADR has a
feature-flagin its frontmatter - The flag gates the feature during development
- When the feature is complete, the gate is removed
- The ADR status changes to
implemented
See ADR-0005: Preview Features for details on the gating mechanism.
The table is generated from ADR frontmatter. Run
scripts/validate-adrs.py --write after adding or changing a record.
| ID | Title | Status | Tags |
|---|---|---|---|
| 0000 | ADR Title | Proposal | — |
| 0001 | The Never Type | Implemented | types |
| 0002 | Single-Pass Bidirectional Type Checking | Implemented | compiler |
| 0003 | Constant Expression Evaluation | Implemented | compiler |
| 0004 | Enum Types | Implemented | types, syntax |
| 0005 | Preview Features | Implemented | process |
| 0006 | Unified Zola Website | Implemented | tooling, documentation |
| 0007 | Hindley-Milner Type Inference | Implemented | types, compiler |
| 0008 | Affine Types and Mutable Value Semantics | Implemented | types, semantics, ownership |
| 0009 | Struct Methods | Implemented | types, syntax |
| 0010 | Destructors | Implemented | types, semantics, ownership, memory |
| 0011 | Runtime Heap | Implemented | runtime, memory, allocator |
| 0012 | Compiler Optimization Passes | Implemented | compiler, codegen |
| 0013 | Borrowing Modes | Implemented | types, semantics, ownership, borrowing |
| 0014 | Mutable Strings | Implemented | types, memory, strings |
| 0015 | Test Suite Optimization | Implemented | process, testing, compiler |
| 0016 | Preview Feature Infrastructure | Implemented | infrastructure, process |
| 0017 | Emitter Instruction Abstraction | Implemented | codegen, refactoring |
| 0018 | Tracing Infrastructure | Implemented | infrastructure, tooling |
| 0019 | Compiler Performance Dashboard | Implemented | tooling, website, performance |
| 0020 | Built-in Types as Synthetic Structs | Implemented | architecture, types, refactoring, strings |
| 0021 | Standard Input | Implemented | io, intrinsics, runtime |
| 0022 | Integer Parsing | Implemented | intrinsics, runtime, strings |
| 0023 | Multi-File Compilation | Superseded | architecture, compiler, scalability |
| 0024 | Type Intern Pool | Implemented | type-system, performance, parallelization |
| 0025 | Compile-Time Execution (comptime) | Implemented | compiler, type-system, generics |
| 0026 | Module System | Stable | architecture, compiler, modules, scalability |
| 0027 | Random Number Intrinsics | Implemented | intrinsics, runtime, semantics |
| 0028 | Unchecked Code and Raw Pointers | Implemented | types, semantics, stdlib, ffi |
| 0029 | Anonymous Struct Methods (Zig-Style) | Implemented | types, methods, comptime, generics |
| 0030 | Place Expressions for Memory Locations | Implemented | ir, codegen, performance |
| 0031 | Robust Performance Testing Infrastructure | Proposal | tooling, ci, performance |
| 0032 | Data Structure Selection for Small Collections | Implemented | performance, implementation |
| 0033 | Sema Pipeline Unification | Rejected | compiler, semantics, architecture |
| 0034 | Per-Target Runtime Archives for Cross-Compilation | Accepted | runtime, cross-compilation, build-system, targets |
| 0035 | String model: byte strings (conventionally UTF-8) with loud pragmatism | Accepted | strings, text, unicode, stdlib |
| 0036 | Behavior classification preference: prefer the most-defined category | Accepted | spec, conformance, safety, principle |
| 0037 | Exclusivity model: access-point-based, statically enforced (Hylo-style) | Accepted | ownership, exclusivity, borrows, semantics, principle |
| 0038 | Error handling: sum types, Result/Option, and must-check via linearity | Implemented | error-handling, enums, sum-types, linearity, pattern-matching |
| 0039 | @drop: the intentional-destroy intrinsic for linear (and affine) values |
Accepted | linearity, ownership, intrinsics, destructors |
| 0040 | Array layout is ascending; @ptr_offset is standard pointer arithmetic | Implemented | layout, arrays, pointers, codegen, abi |
| 0041 | Vec — a growable collection on unchecked raw pointers | Accepted | stdlib, collections, generics, ownership, unchecked |
| 0042 | Standard-library availability model (str/String split, prelude vs explicit std) | Accepted | stdlib, modules, strings, prelude, ergonomics, language-shape |
| 0043 | The collection & string type trio: fixed / slice / growable | Accepted | strings, collections, slices, arrays, vec, allocators, stdlib |
| 0044 | Optimization Levels (-O0/-O1/-O2/-O3) | Accepted | compiler, codegen, process |
| 0045 | Lazy semantic analysis (compile-on-reference) | Accepted | compiler, semantics, comptime, modules, stdlib, language-shape |
| 0046 | Delete flat multi-file mode (all cross-file references go through @import) | Accepted | modules, semantics, cli, language-shape, ergonomics |