Design & Specifications

Significant changes to Azure Service Operator should be captured by an ADR (architecture design record) in this folder. ADRs are listed chronologically by month, and should contain the following sections:

  • Context
  • Decision
  • Status
  • Consequences
  • Experience Report
  • References

Ideally, each ADR should run to one or two pages in length.

For complex changes that require more detail, the ADR should provide an overview. Additional detail (say, to list alternative solutions, detail complex edge cases, or present detailed diagrams) should be captured in a separate design document linked from the ADR.

For background information, check out this Cognitect blog entry.

ADR documents should be updated over time to keep them relevant, typically by updating the Experience Report section.