Architectural Decision Record (ADR) Guide

An Architectural Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences. An ADR is a short document that is written collaboratively by the development team, ideally at the time of the decision. The ADR is a record of a decision that has been made, not a record of the options that were considered.

1. Category
2. References

1. Category

1.1. Procedure

Adopting ADRs is a process that can be done incrementally. The following steps are recommended:

stateDiagram-v2
    [*] --> s1
    s1 : Architecture Decision (AD)
    s1 --> s2
    s2 : Identify Owner of ADR
    s2 --> s3
    s3 : Create an ADR in Proposed state
    s3 --> s4
    s4 : Create a Merge Request
    s4 --> s5
    s5: ADR in Rejected state
    s5 --> [*]

    s4 --> s6
    s6 : Modify the ADR
    s6 --> s4
    s6 --> s7
    s7 : ADR in Accepted state
    s7 --> [*]

1.2. Rules

Naming Convention

The name of the ADR file should be kebab-case and end with the extension .md.
- Identifier
  
  The unique identifier is a sequential number, which ensures that each ADR has a unique filename.
```
[identifier]-adr-[title].md
```
- Data Format
  
  The date is written in the ISO 8601 format, which ensures that the files are sorted in chronological order.
```
[YYYYMMDD]-adr-[title].md
```

Project Layout

The ADRs should be stored in the docs/adr directory.

.
├── /docs
│   └── /decisions
│       ├── 001-adr-build-system.md
│       ├── 002-adr-dependency-manager.md
│       └── 003-adr-test-framework.md

1.3. Code Owner

The Code Owners file defines the owners of a file in a repository. The Code Owners file lives in the repository's root directory. The file must be named CODEOWNERS. The Code Owners file uses the same syntax as .gitignore files. Specify individual users and teams as owners, or add a wildcard * to indicate that all members of the organization are owners.

# All group members as Code Owners
[Project] @group-x
*

[Documentation]
  # All subgroup members as Code Owners
  /docs/adr/ @group-x/subgroup-y

1.4. Template

The template is a guide and should be adapted to the needs of the project.

# ADR [Title]

Architectural Decision Records (ADR) on <Topic> for <Purpose>.

## 1. State

- Author(s): [Author Name(s)]
- Date: [YYYY-0M-0D]
- Status: [Proposed | Accepted | Rejected | Deprecated | Superseded]
    - Proposed
      > The decision is under consideration but has not been accepted or implemented yet.
    - Accepted
      > The decision has been agreed upon and is expected to be implemented.
    - Rejected
      > The decision was not accepted, usually due to it being impractical or inappropriate for the current context.
    - Deprecated
      > The decision was once accepted but is no longer recommended for use, typically because the context has changed or better options have emerged.
    - Superseded
      > The decision has been replaced by a newer, superior alternative. This status is usually accompanied by a reference to the ADR that supersedes it.

## 2. Context

[Provide the context for the decision, including any relevant background information.]

## 3. Decision

- [Decision]
  > [Justification for the decision, provide the reasoning for the chosen option.]

## 4. Considered

1. <Option N>

    - Pros
      > <Advantages of Option N>

    - Cons
      > <Disadvantages of Option N>

## 5. Consequences

1. <Option N>

    <Consequences of choosing Option N>

## 7. References

- [Provide any relevant links or resources related to the implementation, including any technical details.]
- [List any relevant references or sources.]

2. References

GitHub ADR page.
GitHub MADR page.
GitLab Code Owners page.
Amazon ADR page.

sentenz / convention

Create a guideline for `Architectural Decision Record (ADR)` #281