adr

Architecture Decision Records (ADR)

This directory contains Architecture Decision Records (ADRs) for the uContract.NET project.

---

Table of Contents

1. What is an ADR?
2. When to Write an ADR
3. ADR Format and Template
4. Maintenance Workflow
5. ADR Index

---

What is an ADR?

An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

Key principles:

• Immutable: The text of an accepted ADR is not edited. A correction, or a later decision that leaves the ADR's main decision standing, is added to it as an Amendment
• Contextual: Records WHY a decision was made, not just WHAT was decided
• Traceable: Indexed in this README for easy reference
• Versioned: A decision that replaces an ADR's main decision gets a new ADR that supersedes the old one

---

When to Write an ADR

Create an ADR when making decisions about:

Requires ADR

• Framework and tooling choices (e.g., .NET version, test framework)
• Core API design (e.g., static class vs instance, naming conventions)
• Architectural patterns (e.g., configuration mechanism, serialization approach)
• Dependencies (e.g., adding external packages, zero-dependency policy)
• Breaking changes (e.g., API redesign, major refactoring)
• Performance trade-offs (e.g., compile-time vs runtime checks)

May Not Need ADR

• Minor bug fixes
• Documentation updates
• Code formatting changes
• Internal refactoring without API impact

---

ADR Format and Template

File Naming Convention

NNNN-short-title.md

• NNNN: 4-digit sequence number (e.g., 0001, 0002, 0003)
• short-title: Kebab-case descriptive title

ADR Template

See ADR.template.md for the standard template.

---

Maintenance Workflow

After Implementation

1. Agree the decision before work starts, and record it in the issue or pull request
2. Once the change is implemented, write the ADR (use ADR.template.md, set Status to "Accepted"), including what the implementation turned up
3. Update this README's ADR Index

Amending an accepted ADR

Use an amendment for a correction, or for a later decision that leaves the ADR's main decision standing. Do not edit the accepted text. The ADR's status stays Accepted. Add three parts:

1. In the Status block, add a line - **Amended**: <date> — <one line> saying what changed and where the detail is
2. At the end of Implementation Notes, before References, add a section ### Amendment (<date>): <title> that gives the detail
3. In Revision History, add a row with status Amended and a short note

An ADR can be amended more than once. Each amendment adds its own three parts, and amendments only add lines: earlier ones stay as written. See ADR-0004 and ADR-0020 for examples. If the new decision replaces the main decision, write a new ADR that supersedes the old one instead.

---

ADR Index

Accepted

First Priority (Core Architecture):

• ADR-0001: Target Framework - .NET 8 — 2025-10-18
• ADR-0002: Project Naming and Structure — 2025-10-18
• ADR-0003: API Design - Static Class Pattern — 2025-10-18
• ADR-0004: Runtime Configuration via Environment Variables — 2025-10-18
• ADR-0020: Contracts Enabled by Default — 2026-10-04
• ADR-0005: Generics, Type Constraints, and Nullable Reference Types — 2025-10-18

Second Priority (Implementation Details):

• ADR-0007: Reflection and Field Comparison for EnsureAssignable() — 2025-10-18
• ADR-0008: Exception Hierarchy Design — 2025-10-18
• ADR-0009: Thread Safety and Async/Await Support — 2025-10-18
• ADR-0021: Postcondition Helpers under Trimming and Native AOT — 2026-10-04
• ADR-0022: Faithful Old() Copies and Robust EnsureAssignable() Comparison — 2026-10-07

Third Priority (Publishing and Maintenance):

• ADR-0010: Testing Framework - xUnit — 2025-10-18
• ADR-0011: Zero-Dependency Principle — 2025-10-18
• ADR-0017: Embedded PDB and Source Link — 2026-04-19

Fourth Priority (Cross-Language Considerations):

• ADR-0012: .NET Improvements Over Java Implementation — 2025-10-19
• ADR-0016: No TypeReference Overload for Old() — 2026-04-19
• ADR-0018: Optional Description via CallerArgumentExpression — 2026-04-19

Fifth Priority (Design Constraints from Root Contracting Paper):

• ADR-0013: No Subcontracting Support — 2025-10-29

Sixth Priority (Diagnostics):

• ADR-0014: Diagnostic Logging via EventSource — 2026-04-07

Seventh Priority (Tooling and Quality):

• ADR-0015: Code Quality Tooling — 2026-04-18
• ADR-0019: Public API Baseline Tracking — 2026-04-19

Superseded

• ADR-0006: Serialization and Deep Copy Mechanism for Old() — 2025-10-18; superseded by ADR-0022 on 2026-10-07

---

Notes for Maintainers

Adding a New ADR

1. Copy ADR.template.md to NNNN-your-title.md (increment number)
2. Fill in all sections
3. Set initial Status to "Proposed" or "Accepted"
4. Update this README's ADR Index

Best Practices

• Write ADRs after implementation, so they record what the implementation turned up; the decision itself is agreed before work starts
• Keep ADRs concise but complete (1-2 pages max)
• Focus on WHY, not just WHAT
• Include alternatives considered to avoid future repetition
• Link to related ADRs to build decision graph