O documento discute a importância de registrar decisões arquiteturais (ADRs) para projetos de software sustentáveis. Apresenta exemplos de situações comuns que podem beneficiar do registro de ADRs, como mudanças impactantes, más decisões e débito técnico. Também discute onde armazenar os registros e como atualizá-los ao longo do tempo.
10. “Entender de onde você saiu é crucial para entender
quais são suas novas opções.”
11. “Decisões são formadas baseadas em seu contexto,
entender o contexto permite entender as decisões
passadas e tomar melhores no futuro.”
12. Fizemos isso desta forma por <<motivo>>, caso
<<condição>> aconteça podemos removes este código.
Caso contrário, considere essa <<consequência>> de fazer
isto dessa forma.
📷 olia danilevich
15. Contexto
• Descreva fatos
• Enumere as influencias atuando neste momento
• O que esta acontecendo?
• Quais os motivos e motivadores para tomar essa decisão?
• Que tipo de pressão ou conflito esta influenciando ela?
• Politica, social ou tecnológica
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.
Contexto politico e histórico
Contexto Técnico
Contexto
ADR0025 - RESTful API standards
17. Decisão
• Use a voz imperativa: “Nós vamos…”
• Explique como atenderam às influencias descritas anteriormente
• Seja claro sobre o que compõem a decisão
18. Decisão
{
"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
Descrição clara e na voz ativa
Exemplos fácies de ler
ADR0013 - Use standard case for all json payloads
19. Consequências
• Como ficará o contexto após a decisão ser aplicada
• Efeitos colaterais da decisão tomada:
• Positivos
• Negativos
• Neutros
• O que não será mais possível?
• Que outras decisões serão influenciadas
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.
Consequências, positivas.
Exceções, e como cuidar delas
Consequências
ADR0005 - Always ensure non-breaking migrations
21. Outros formatos
• Micheal Nygard Standard
Simples, direto e completo
https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• MADR
Longo com mais detalhes: motivadores, alternativas, 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
Quando vamos pagar o debito?
Quais as restrições
impostas pelo Produto
Que funcionalidades estão
bloqueadas agora?