Every day developers will make an uncountable number of decisions while working or run into past decisions that we do not fully understand. How can we organize all this content and simplify the sharing of architectural knowledge?
Let's explore ADRs and how they can support decision making and sharing on various levels.
11. “Decisions are shaped based on the context,
understanding that context allows you to understand
those decisions and make better ones.”
12. We did it this way because of <<reason>>, if
<<condition>> happened we can now get rid of this code.
Otherwise, consider this <<consequence>> of doing it this
way.
📷 olia danilevich
15. Context
• Describe facts
• Outline the forces at play
• What is happening?
• What are the motivations to make a decision?
• What kind of pressure or conflicting priorities are at play?
• Political, social and technological
16. When creating the new platform, time pressure forced us to take some
shortcuts when it came to the design of our RESTful APIs (APIs from here on).
This ADR tries to rectify that, realign us and create a guideline for all future
APIs.
We subscribe to the Richardson Maturity Model for APIs. We are currently
comfortably floating somewhere near level 2 and are wondering if the effort
involved to get to level 3 is worth it.
To better support and decouple the Backend development from the Frontend
development, we want to introduce the Backend for Frontend (BFF)
architectural pattern in the form of a GraphQL component. That component will
serve all Frontend requests and talk to the backend microservices. Our
preferred implementation for that component is Apollo (Javascript). Apollo
currently reaps no benefits from having a maturity level 3 API since all relations
need to be defined by hand and are not deduced from HATEOAS.
Historical and political context
Technical context
Context
ADR0025 - RESTful API standards
17. Decision
• Use the active voice: “We will…”
• Explain the response to the forces described in the context
• Be clear about what the decision entails
18. Decision
{
"someProperty": "with a value",
"channels": [
"web-passive",
"web-active"
]
}
We will adopt a new JSON naming structure.
• properties should follow camelCase
• constant values should use kebab-case
Clear decision in active voice
Easy to read examples
ADR0013 - Use standard case for all json payloads
19. Consequences
• What the context will be after the decision is applied
• Side effects of decision
• Positive
• Negative
• Neutral
• What will not be possible anymore?
• What other decisions will be influenced?
20. Projects implementing this convention should not need to migrate downwards
anymore. Thus it is unnecessary, from a production environment perspective,
to have a down migration.
Any down migration may be kept in repositories for development purposes,
allowing tests to migrate back and forth speeding up the test suite in general.
However, the down migrations should never be part of deploy or
rollback process and should never be executed in production environments.
Consequences, positive.
Exceptions and how to handle them
Consequences
ADR0005 - Always ensure non-breaking migrations
21. Other formats
• Micheal Nygard Standard
Simple, straight forward, complete
https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• MADR
Long, with many details: drivers, alternatives, pro/cons
https://adr.github.io/madr/
• Y-Statements
In the context of <use case/user story u>, facing <concern c> we decided for <option o> to achieve
<quality q>, accepting <downside d>.
https://www.infoq.com/articles/sustainable-architectural-design-decisions/
25. Context
Decision
Consequences
ADR0001 - Record Decisions
Date: 2020-12-01
Status
Approved
When will we pay Tech Debt?
What was product’s restrictions?
Which other features are blocked now?