Skip to content

ADR-000: ADR Status Guidelines

Status

Accepted

Context

Our Architecture Decision Records (ADRs) have been using "Accepted" as the final status, but this makes it difficult to track which decisions have actually been implemented in production versus those that have been approved but not yet built.

Decision

We will use the following status progression for ADRs:

Status Lifecycle

  1. Proposed - Initial state when an ADR is created and under discussion
  2. Accepted - The decision has been approved and is ready for implementation
  3. Implemented - The decision has been fully implemented and is in production
  4. Partially Implemented - Some aspects are in production, others pending
  5. Superseded - Replaced by a newer ADR (should reference the new ADR number)
  6. Deprecated - No longer relevant but kept for historical reference
  7. Rejected - Proposal was not accepted

Status Format

Each ADR should have its status clearly indicated at the top of the document:

## Status
Implemented

Or for inline format: 

**Status:** Implemented

Implementation Tracking

When marking an ADR as "Implemented" or "Partially Implemented", include: - Implementation date or date range - Link to primary PR(s) if available - Brief note on what was implemented (for partial implementations)

Example: 

## Status
Implemented - June 2024
- Primary PR: #245 (Email sync with Cloud Tasks)
- Deployed to production: 2024-06-15

Verification Criteria

An ADR can be marked as "Implemented" when: 1. Core functionality described in the Decision section is in production 2. Tests exist and pass for the implemented features 3. Documentation has been updated to reflect the implementation 4. The implementation is being used in production

Consequences

Positive

  • Clear visibility into what architectural decisions are actually in production
  • Better tracking of technical debt (Accepted but not Implemented)
  • Easier onboarding for new team members
  • More accurate system documentation

Negative

  • Requires regular auditing of ADR statuses
  • Additional maintenance overhead to keep statuses current
  • May reveal gaps between decisions and implementation

Implementation Notes

  1. Conduct initial audit of all existing ADRs
  2. Update statuses based on code inspection and deployment history
  3. Establish quarterly reviews to keep statuses current
  4. Include status updates in PR reviews when implementing ADRs