ADR Process

This document describes the Architectural Decision Records (ADRs) process used in the Floxide framework.

What are ADRs?

Architectural Decision Records (ADRs) are documents that capture important architectural decisions made during the development of a software system. They provide a record of what decisions were made, why they were made, and what alternatives were considered.

Why Use ADRs?

ADRs serve several important purposes in the Floxide project:

  1. Documentation: They provide a clear record of architectural decisions.
  2. Context Preservation: They capture the context and reasoning behind decisions.
  3. Knowledge Sharing: They help new contributors understand the architecture.
  4. Decision Making: They provide a structured process for making and reviewing architectural decisions.

ADR Process in Floxide

In the Floxide framework, we follow a specific process for creating and managing ADRs:

ADR Creation and Process

  1. Numbering: ADRs are numbered sequentially with a four-digit number prefix (e.g., 0001, 0002).
  2. Format: ADRs are stored as Markdown files in the /docs/adrs/ directory.
  3. Naming Convention: ADR files are named with their number and a kebab-case title, e.g., 0001-adr-process-and-format.md.
  4. Creation Timing: ADRs must be created before implementing any architectural decision, not after.
  5. Incremental Creation: ADRs can be created incrementally as decisions are made throughout the project.

ADR Content Structure

Each ADR includes:

  1. Title: A clear, descriptive title following the format "ADR-NNNN: Title"
  2. Status: One of:
  3. Proposed: Initial state when the ADR is first drafted
  4. Accepted: Approved for implementation
  5. Rejected: Declined, with reasons documented
  6. Superseded: Replaced by a newer ADR (with reference to the new ADR)
  7. Amended: Modified after implementation
  8. Date: The date the ADR was last updated
  9. Context: The problem being addressed and relevant background information
  10. Decision: The architectural decision that was made and the reasoning
  11. Consequences: The results of the decision, both positive and negative
  12. Alternatives Considered: Other options that were evaluated and why they were not chosen

ADR Lifecycle Management

  1. Review Process: ADRs are reviewed before they are accepted.
  2. Amendments: Existing ADRs can be amended with additional information, but the core decisions should not be changed after implementation.
  3. Superseding: If a decision changes fundamentally, a new ADR should be created that supersedes the old one. The old ADR should be updated to reference the new one.
  4. Retrospective Updates: Consequences that were not anticipated can be added to ADRs after implementation to serve as a record for future reference.

ADR Index

An index of all ADRs is maintained in /docs/adrs/README.md to provide a central reference point. You can also view all ADRs in the ADRs section of the documentation.

Creating a New ADR

To create a new ADR:

  1. Identify an architectural decision that needs to be documented.
  2. Determine the next available ADR number.
  3. Create a new Markdown file in the /docs/adrs/ directory using the naming convention.
  4. Use the ADR template as a starting point.
  5. Fill in the sections of the ADR with the relevant information.
  6. Submit the ADR for review.

Conclusion

The ADR process is a critical part of the Floxide framework's development approach. By documenting architectural decisions in a structured way, we ensure that the project's architecture is well-understood, maintainable, and evolves in a controlled manner.