From a905daa05f4ee65ff89c5d052ac1fdb1780cee1d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 1 Jan 2026 17:51:16 +0000 Subject: [PATCH 1/3] Initial plan From e76dc807e2a3bc76f8bbef75dea5164675878bda Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 1 Jan 2026 17:55:31 +0000 Subject: [PATCH 2/3] Add Architecture Decision Records (ADR) system to project Co-authored-by: tschm <2046079+tschm@users.noreply.github.com> --- README.md | 13 ++++ docs/adr/0000-adr-template.md | 19 ++++++ .../0001-use-architecture-decision-records.md | 65 +++++++++++++++++++ docs/adr/README.md | 37 +++++++++++ 4 files changed, 134 insertions(+) create mode 100644 docs/adr/0000-adr-template.md create mode 100644 docs/adr/0001-use-architecture-decision-records.md create mode 100644 docs/adr/README.md 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..f419303b --- /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-in-kebab-case.md` with sequential numbering +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..74b526f0 --- /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/XXXX-your-title.md` +2. Use the next available number (e.g., 0002, 0003) +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) From df5140f135a804d74b5986628294d403c2da1ad7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 1 Jan 2026 17:56:42 +0000 Subject: [PATCH 3/3] Clarify ADR naming conventions and use consistent examples Co-authored-by: tschm <2046079+tschm@users.noreply.github.com> --- docs/adr/0001-use-architecture-decision-records.md | 2 +- docs/adr/README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/adr/0001-use-architecture-decision-records.md b/docs/adr/0001-use-architecture-decision-records.md index f419303b..5b521376 100644 --- a/docs/adr/0001-use-architecture-decision-records.md +++ b/docs/adr/0001-use-architecture-decision-records.md @@ -29,7 +29,7 @@ We will maintain Architecture Decision Records (ADRs) for architecturally signif 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-in-kebab-case.md` with sequential numbering +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" diff --git a/docs/adr/README.md b/docs/adr/README.md index 74b526f0..ea26e036 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -25,8 +25,8 @@ Each ADR follows a consistent format defined in [0000-adr-template.md](0000-adr- ## Creating a New ADR -1. Copy the template: `cp docs/adr/0000-adr-template.md docs/adr/XXXX-your-title.md` -2. Use the next available number (e.g., 0002, 0003) +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