Skip to main content

Adopting ADRs

Status: Accepted

Deciders: Michael White / Chris McCue / Tony Braasch / Willem Paul / Sharan Kandagatla / Scott Houser / Thomas Musengwa / Bailey Surowiec / Neil Patel / Alex Chen / Marcus Taugner / Dylan Surprise / Richard Plotkin

Date: 12/4/2023

Context​

As the preferred framework, Abyss plays a pivotal role in streamlining product development and user experience across the UHC/Optum/UHG ecosystems. As Abyss grows in scope and usage, the need for a structured, transparent decision-making process becomes crucial. The introduction of ADRs aims to capture the rationale behind key architectural choices, offering a clear, historical record that aligns with Abyss’s principles of user-first design, consistency, and provides a reference point for future decisions.

Decision​

We will adopt Architecture Decision Records (ADRs) as a formal mechanism for documenting architectural decisions made in the development of the Abyss framework. The decision to create an ADR should not solely hinge on the perceived scale of a decision's impact. Overall, there are no fixed rules on when to create an ADR but here are some additional guidelines to consider:

Does the decision...

  • Impact stakeholders and consuming teams?
  • Involve choices, trade-offs, and/or measurable changes?
  • Provide value in understanding and maintaining the system?
  • Provide a valuable point of reference that can be revisited in the future?

These ADRs will be stored as Markdown files in a dedicated directory, ensuring accessibility and version control alongside the codebase. This approach aligns with our ethos of maintaining a single source of truth and fostering an environment of open collaboration and continuous improvement.

Update on 12/6/2021​

Following team discussions, it was decided to incorporate an 'Alternatives' section in the ADR template to capture different options considered. We also discussed the use of a single template with optional fields versus separate long and short form templates. Given the diverse nature and varying complexity of decisions we encounter, a single, more versatile template was favored. This approach allows for tailored field selection, enabling each ADR to be more precisely crafted to suit the specific needs and intricacies of the decision at hand.

Update on 12/11/2023​

Following discussions, it was decided to further clarify that a decision does not need to have 'significant' impact in order to create an ADR, and offered some general guidelines to consider. Most importantly, we want to encourage an environment of open conversation that enhances collaboration and documents a thoughtful decision-making process that can be referenced into the future as Abyss continues to evolve.

Update on 01/26/2024​

In response to concerns regarding the ownership and maintenance of ADRs, we propose the following best practices to streamline the process and prevent confusion or conflicting edits:

Clear Ownership Per ADR​

  • Primary Owner: The individual who initiates an ADR will be designated as its primary owner.
  • Responsibilities:
    • Creating the “master” branch for the ADR.
    • Moving the conversation forward and driving consensus.
    • Consolidating contributions from all stakeholders.
    • Finalizing and merging the ADR, including resolving any merge conflicts.

Branching and Review Strategy​

  • Master Branch: Each ADR will have its own "master" branch within the ADR directory that follows the naming convention.

  • ADR Naming Convention: We adhere to a specific naming convention for our ADR files, detailed in our project's README. This includes a sequential numbering system and a descriptive title in kebab-case format.

  • Branch Naming for ADRs: To maintain alignment between ADR documents and their corresponding development branches, we follow a branch naming convention that mirrors the ADR naming structure, prefixed with adr/. This convention is also detailed in our project's README.

For the complete guidelines on naming conventions, please refer to the relevant section in the README of the project repository.

  • Contribution Process: Proposed updates or changes to an ADR should be made through a pull request (PR) on a separate branch that is based off the master ADR branch.
  • Collaboration: Team reviews and discussions regarding the ADR will occur through the review and commenting process on the PRs.

These practices are designed to ensure that each ADR has a clear point of responsibility, while also allowing for collaborative input and discussion from the entire team. This will streamline the ADR process, minimize conflicts, and maintain the quality and integrity of the decision records.

Consequences​

  • Enhanced Documentation: The ADRs will augment our existing documentation, providing deeper insights into the ‘why’ behind our architectural choices.
  • Enhanced Collaboration: ADRs will foster better team understanding and alignment on architectural decisions.
  • Historical Context: They will serve as a historical record, helping new team members and external collaborators understand why past decisions were made.
  • Decision-making Process: ADRs will encourage a more deliberate and thoughtful decision-making process for future architectural changes.

Future Considerations​

  • Integration of ADRs with the Abyss documentation site, making them more readily accessible to a broader audience.
  • Sub-categorize decision records as the volume grows and they become more categorically diverse.

Revision History​

  • 12/4/2023: Discussion on ADR templates and inclusion of an 'Alternatives' section.
  • 12/11/2023: Discussion on what constitutes a 'significant' enough impact to create an ADR.
  • 01/26/2024: Discussion on ownership, branching and review strategy.
Table of Contents