zosstorage/docs/adr

Architectural Decision Records (ADR) Index

Purpose

• Central place to list and navigate all ADRs.
• Naming scheme: NNNN-title.md (zero-padded sequence).

Index

• 0001: Modular Development Workflow with Grep-able Contracts and Regions

Conventions

• Location: docs/adr/
• Create new ADRs incrementally with next number (e.g., 0002-<short-title>.md).
• Each ADR should include:
  • Status (Proposed/Accepted/Deprecated)
  • Context
  • Decision
  • Consequences
  • Links to related docs (e.g., docs/ARCHITECTURE.md, docs/API-SKELETONS.md)

Workflow

1. Propose an ADR when a design decision impacts architecture or module boundaries.
2. Add the ADR file under docs/adr/ with the next sequence number.
3. Append the ADR to this index under “Index”.
4. Optionally add a short “Architectural Decisions” section to docs/ARCHITECTURE.md summarizing the latest ADRs.

Template

# ADR NNNN: Title

Status
- Proposed | Accepted | Deprecated
- Date: YYYY-MM-DD

Context
- Brief background and forces at play.

Decision
- The choice made; bullet any alternatives considered.

Consequences
- Pros/cons, impacts on modules, tests, build, etc.

Links
- [docs/ARCHITECTURE.md](../ARCHITECTURE.md)
- Related ADRs

Validation ideas (optional future work)

• Add a CI step or cargo xtask adr-check to verify:
  • Files match NNNN-title.md
  • All ADRs are listed in this README
  • Sequence numbers are contiguous