Skip to content

Commit

Permalink
doc: add adr for new adr process
Browse files Browse the repository at this point in the history
  • Loading branch information
@jrschumacher
jrschumacher committed Aug 29, 2024
1 parent e0bc183 commit d5bcbff
Showing 1 changed file with 44 additions and 0 deletions.
44 changes: 44 additions & 0 deletions adr/0000-use-adr-dir-for-adr.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
status: accepted
date: 2024-08-29
decision: Use ADRs in the `adr` directory of the repo to document architectural decisions

Check failure on line 4 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "ADRs".
Suggested alternatives: "Ad Rs", "AD's", "Ads", "Rads", "Airs", "Adds", "Ad's", "Ad-rs", "Adas", "Sadr"
If you want to ignore this message, add ADRs to the ignore file at ./.github/spellcheck.ignore

Check failure on line 4 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "repo".
Suggested alternatives: "rope", "rep", "reps", "redo", "rep o", "pore"
If you want to ignore this message, add repo to the ignore file at ./.github/spellcheck.ignore
author: '@jakedoublev'

Check failure on line 5 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "jakedoublev".
Suggested alternatives: "doublespeak"
If you want to ignore this message, add jakedoublev to the ignore file at ./.github/spellcheck.ignore
deciders: ['@ryanulit', '@jrschumacher']

Check failure on line 6 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "ryanulit".
Suggested alternatives: "granularity"
If you want to ignore this message, add ryanulit to the ignore file at ./.github/spellcheck.ignore

Check failure on line 6 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "jrschumacher".
Suggested alternatives: "meerschaum"
If you want to ignore this message, add jrschumacher to the ignore file at ./.github/spellcheck.ignore
---

# Use a ADR storage format that make diffs easier to read

Check failure on line 9 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "ADR".
Suggested alternatives: "AD", "SADR", "RAD", "ADS", "AIR", "ARR", "ADO", "ADD", "ADV", "AD R", "AFR", "AR", "ADAR", "ADA", "ADM"
If you want to ignore this message, add ADR to the ignore file at ./.github/spellcheck.ignore

## Context and Problem Statement

We've been using Github Issues to document ADR decisions, but it's hard to read the diffs when changes are made. We need a better way to store and manage ADRs. ADRs sometimes get updated and it's hard to track the changes and decision using the edit history dropdown or the comments section.

Check failure on line 13 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "Github".
Suggested alternatives: "GitHub", "Git hub", "Git-hub"
If you want to ignore this message, add Github to the ignore file at ./.github/spellcheck.ignore

Check failure on line 13 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "ADR".
Suggested alternatives: "AD", "SADR", "RAD", "ADS", "AIR", "ARR", "ADO", "ADD", "ADV", "AD R", "AFR", "AR", "ADAR", "ADA", "ADM"
If you want to ignore this message, add ADR to the ignore file at ./.github/spellcheck.ignore

Check failure on line 13 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "ADRs".
Suggested alternatives: "Ad Rs", "AD's", "Ads", "Rads", "Airs", "Adds", "Ad's", "Ad-rs", "Adas", "Sadr"
If you want to ignore this message, add ADRs to the ignore file at ./.github/spellcheck.ignore

Check failure on line 13 in adr/0000-use-adr-dir-for-adr.md

View workflow job for this annotation

GitHub Actions / spellcheck

Misspelled word 

Misspelled word "ADRs".
Suggested alternatives: "Ad Rs", "AD's", "Ads", "Rads", "Airs", "Adds", "Ad's", "Ad-rs", "Adas", "Sadr"
If you want to ignore this message, add ADRs to the ignore file at ./.github/spellcheck.ignore

## Decision Drivers

- **Low barrier of entry**: A primary goal of our ADR process is to ensure decisions are captured.
- **Ease of management**: Make it easy to manage the ADRs.
- **Ensure appropriate tracking and review**: Make it easy to track and review the changes in the ADRs.

## Considered Options

1. Use Github Issues
2. Use Github Discussions
3. Use a shared ADR repository
4. Use an `adr` directory in the repo

## Decision Outcome

It was decided to use an `adr` directory in the repo to store ADRs. This approach provides a low barrier of entry for developers to document decisions and ensures that the decisions are tracked and reviewed appropriately.

Additionally, this change does not impact other teams or repositories, and it is easy to manage and maintain. We can experiment with this decision and if it works promote it to other repositories.

### Consequences

- **Positive**:
- Low barrier of entry for developers to document decisions.
- Easy to manage and maintain.
- Ensures appropriate tracking and review of decisions via git history and code review.
- **Negative**:
- Requires developers to be aware of the ADR process and where to find the ADRs.
- May require additional tooling to manage and maintain the ADRs.
- May require additional training for developers to understand the ADR process and how to use it effectively.

0 comments on commit d5bcbff

Please sign in to comment.