Introduction

This directory contains the Architecture Decision Records (ADRs) for the Abyss framework. ADRs are documents that capture architectural decisions made during the development and maintenance of Abyss. These records provide context, rationale, and a historical record of the evolution of our framework.

Purpose

The purpose of ADRs in Abyss is to ensure that architectural decisions are made transparently, collaboratively, and with a clear understanding of their implications. They serve as a reference for the team and stakeholders, facilitating consistent and informed decision-making.

Creating, Using, and Updating ADRs

• Creating ADRs: When an architectural decision is made, document it using the ADR template. The creation of an ADR is not limited to decisions with large-scale impacts. The emphasis is on fostering a practice of recording and conversing about the architectural decisions we make within Abyss. Use the template as a guide to mold the ADR to the complexity of the decision.

  • ADR Naming Convention: Each ADR file should be named using the following structure: adr-XXX-title-of-the-decision. Replace XXX with a zero-padded sequential number (e.g., 001, 002, 003, ...) and title-of-the-decision with a kebab-case summary of the ADR content (e.g., adopting-adrs-for-abyss). The number should increment by one with each new ADR, ensuring a unique and chronological identifier.

  • Branch Naming for ADRs: When creating a new branch for an ADR, use the same name as the ADR file, prefixed with adr/. For example, if the ADR is named adr-004-implementing-authentication, the branch name should be adr/adr-004-implementing-authentication. This ensures clarity and consistency between the ADR document and associated branches.

For more details on the process of creating and maintaining ADRs, refer to the ADR-001 in the project repository.

• Updating ADRs: ADRs should be living documents. Update them as new information arises or the context changes.
• Collaboration: Encourage discussions and collaborative drafting of ADRs. Submit a pull request for new or updated ADRs for team review.

For further details on the decision behind adopting ADRs please see ADR-001: Adopting Architecture Decision Records (ADRs) for Abyss.

ADR Template

We use a single, flexible ADR template with optional fields to cater to a variety of decision complexities. This approach ensures consistency while providing the necessary flexibility for different types of decisions.

Refer to the ADR template for guidance on creating a new ADR.

ADR List

Accepted ADRs can be found in Github

Contact

For any queries or discussions regarding ADRs, please contact the Abyss team through our Contact Us form.

Thank you for contributing to the documentation and evolution of Abyss!