diff --git a/README.md b/README.md index 13cd6fde..b1223f11 100644 --- a/README.md +++ b/README.md @@ -216,6 +216,19 @@ To customize the book: 1. Create the directory: `mkdir -p book/minibook-templates` 2. Create your custom template at `book/minibook-templates/custom.html.jinja2`. +## 📝 Architecture Decision Records + +This project maintains Architecture Decision Records (ADRs) to document important architectural and design decisions. + +ADRs help preserve the reasoning behind key decisions, making it easier for current and future contributors to understand why the project is structured the way it is. + +**Browse ADRs**: See [docs/adr/](docs/adr/) for all architecture decisions. + +**Key decisions documented:** +- [ADR-0001: Use Architecture Decision Records](docs/adr/0001-use-architecture-decision-records.md) + +For more information about the ADR format and how to create new records, see the [ADR README](docs/adr/README.md). + ## 📁 Available Templates This repository provides a curated set of reusable configuration templates, organised by purpose. diff --git a/docs/adr/0000-adr-template.md b/docs/adr/0000-adr-template.md new file mode 100644 index 00000000..4b4cbde8 --- /dev/null +++ b/docs/adr/0000-adr-template.md @@ -0,0 +1,19 @@ +# [NUMBER]. [TITLE] + +Date: [YYYY-MM-DD] + +## Status + +[Proposed | Accepted | Deprecated | Superseded by [ADR-XXXX](XXXX-title.md)] + +## Context + +What is the issue that we're seeing that is motivating this decision or change? + +## Decision + +What is the change that we're proposing and/or doing? + +## Consequences + +What becomes easier or more difficult to do because of this change? diff --git a/docs/adr/0001-use-architecture-decision-records.md b/docs/adr/0001-use-architecture-decision-records.md new file mode 100644 index 00000000..5b521376 --- /dev/null +++ b/docs/adr/0001-use-architecture-decision-records.md @@ -0,0 +1,65 @@ +# 1. Use Architecture Decision Records + +Date: 2026-01-01 + +## Status + +Accepted + +## Context + +As the Rhiza project grows and evolves, we need a systematic way to document important architectural and design decisions. Team members (both current and future) need to understand: + +- Why certain approaches were chosen over alternatives +- What constraints or requirements influenced past decisions +- The expected consequences of architectural choices +- The historical context behind the current system design + +Without such documentation, we risk: +- Repeating past mistakes or debates +- Making inconsistent decisions across the project +- Losing institutional knowledge when team members change +- Spending time explaining the same decisions repeatedly + +## Decision + +We will maintain Architecture Decision Records (ADRs) for architecturally significant decisions in the project. + +**Key aspects:** + +1. **Location**: ADRs will be stored in `docs/adr/` directory +2. **Format**: Each ADR will follow the template defined in `0000-adr-template.md` +3. **Naming**: Files will be named `XXXX-title-with-hyphens.md` with sequential 4-digit numbering (e.g., `0002-example-decision.md`) +4. **Index**: The `docs/adr/README.md` will maintain an index of all ADRs +5. **Immutability**: Once accepted, ADRs should not be modified; instead, create new ADRs that supersede old ones +6. **Review**: ADRs should be reviewed and discussed before being marked as "Accepted" + +**What qualifies as an ADR-worthy decision:** + +- Changes to the project structure or organization +- Technology or tool adoption/removal +- Significant changes to development workflows or processes +- Design patterns or architectural approaches +- Changes to build, test, or deployment strategies + +## Consequences + +### Positive + +- **Knowledge preservation**: Important decisions and their rationale are documented for future reference +- **Better onboarding**: New contributors can understand why things work the way they do +- **Reduced debate**: Past decisions are clearly documented, reducing repetitive discussions +- **Audit trail**: Clear history of architectural evolution +- **Better decision-making**: Forces thoughtful consideration of context and consequences + +### Neutral + +- **Process overhead**: Contributors need to write ADRs for significant decisions (but this is offset by reduced future confusion) +- **Learning curve**: Team members need to learn when and how to write ADRs + +### Negative + +- **Initial setup time**: Creating the ADR system and first records requires upfront effort +- **Maintenance**: The ADR index needs to be kept up-to-date + +Overall, the benefits of maintaining ADRs far outweigh the minimal overhead required to keep them up-to-date. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 00000000..ea26e036 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,37 @@ +# Architecture Decision Records + +This directory contains Architecture Decision Records (ADRs) for the Rhiza project. + +## 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. + +## ADR Format + +Each ADR follows a consistent format defined in [0000-adr-template.md](0000-adr-template.md): + +- **Title and Number**: Sequential numbering with descriptive title +- **Date**: When the decision was made +- **Status**: Current state (Proposed, Accepted, Deprecated, Superseded) +- **Context**: The issue or situation that motivates the decision +- **Decision**: The change or approach being taken +- **Consequences**: What becomes easier or harder as a result + +## ADR Index + +| Number | Title | Status | Date | +|--------|-------|--------|------| +| [0001](0001-use-architecture-decision-records.md) | Use Architecture Decision Records | Accepted | 2026-01-01 | + +## Creating a New ADR + +1. Copy the template: `cp docs/adr/0000-adr-template.md docs/adr/0002-your-title.md` +2. Use the next available 4-digit number (e.g., 0002, 0003, 0004) +3. Fill in all sections with relevant information +4. Update this README to add your ADR to the index +5. Submit via pull request for review + +## Resources + +- [ADR GitHub Organization](https://adr.github.io/) +- [Michael Nygard's article on ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)