This repository contains a collection of Architecture Decision Records (ADRs) that document important decisions made during the development of our project. ADRs help us maintain a historical record of our design choices, making it easier for both current and future team members to understand the rationale behind those decisions.
An Architecture Decision Record (ADR) is a concise document that captures a single decision and its context, including the problem statement, decision drivers, considered options, and the chosen solution. ADRs provide a way to communicate and preserve architectural decisions in a structured format, ensuring that the decision-making process remains transparent and easy to follow.
We use ADRs to document significant design choices that impact the overall architecture of our system. These decisions may include, but are not limited to:
- Selection of technologies or libraries
- Changes in data models or schemas
- Design patterns or architectural styles
- Adoption of new processes or methodologies
We aim to create ADRs as early as possible in the decision-making process, allowing for review and discussion by the entire team. ADRs are then committed to this repository, providing a historical record of our architectural decisions.
In addition to the conventional (i.e. manual) method, we are also experimenting with using large language models, such as OpenAI's GPT, to generate and refine ADR documents. These prompts are included in the ADRs directory which can help automate the process of creating ADRs, while still ensuring that the content is relevant and accurate.
To use the large language models for ADR generation, simply provide the necessary context and problem statement as input to the model, and it will generate a draft ADR based on the given information. The generated ADR can then be reviewed and refined by the team members to ensure its accuracy and completeness.
timeline
Previous Sprint(s): Existing ADR(s)
Creation: Research and/or design issue started
: ADR tracks the decision making separate from other outputs
: Other outputs (e.g. docs, code) may cite and/or implement an ADR
Observation: As the team surfaces additional, relevant information (e.g. conversations in discord, GitHub, etc.) over time, ADRs are appended to (format currently unspecified)
: Examples include things one might use `//CONSIDERATION`, `//IMPROVE`, or `//DISCUSS` for in code
Cleanup/consolidate (optional): consolidate accumulated additional information by regenerating a new ADR which obsoletes the current
Obsoletion: When an ADR conflicts with (a) prior one(s), the prior ADR's status MUST be set to "obsolete" with a reference to the newer ADR
: If there are aspects of the prior ADR which the conflicting ADR does not address they MUST be consolidated (regenerated) into an additional (new) ADR which also obsoletes the prior ADR(s). This should all surface during review, if not sooner
stateDiagram
state "In Review" as review
state "Changes Needed" as change
[*] --> Draft : Author opens a PR
Draft --> review : PR is marked 'Ready for Review'
review --> change : Reviewer requests changes
change --> review : Reviewer approves changes
change --> Withdrawn : PR is closed
review --> Accepted : PR is merged
Accepted --> Superseded : Superseding ADR becomes 'Accepted
Draft --> Withdrawn : PR is closed
review --> Withdrawn: PR is closed
review --> Unsuitable: PR is closed
To contribute a new ADR, please follow these steps:
- Author: Create a new branch for your ADR.
- Author: Copy the ADR template from
ADR_TEMPLATE.md
and create a new file with the next ADR number and title as an imperative mood verb phrase (e.g.,0003-adopt-multiaddr.md
) and save the copy in the/ADRs
directory. - Author: Fill in the necessary information in the new ADR file, following the template structure and removing placeholders.
- Author: Use the large language model prompts, if desired, to generate or refine the ADR content.
- Author: Submit a pull request to merge your ADR branch into the main branch, including a brief description of the problem and solution.
- Author: Add a reference to the ADR Index for your pull request with appropriate status.
- Author/Reviewer: Request a review from the team members, and address any feedback or suggestions provided.
- Author/Reviewer: Once approved, merge the pull request to update the repository with the new ADR.
- Author/Reviewer: If ADR is marked unsuitable or withdrawn...
- Update the document's status field as appropriate
- Append the
[WITHDRAWN]
suffix to the ADR's filename. - Update the status of the ADR in the ADR Index to match.