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.

1. Como chegamos aqui?
@rdohms
Um guia para Architectural Decision Records
📷 pixabay

2. “Precisamos desta funcionalidade para Sexta!”
— Produto, sempre.

3. “Vamos fazer uma gambiarra, semana que vem
arrumamos”
— Desenvolvedor 1, o otimista.

4. “Quem fez isso? Porque desse jeito? PQP!?”
— Desenvolvedor 1, um ano depois.

5. “Ah, claro, eu lembro porque!”
— Desenvolvedor 1, depois do git blame.

6. Alguém já passou por isso antes?
📷 negative space

7. Rafael Dohms
• Pai da Chloe
• Palestrante
• Aquele cara chato do Object Calisthenics
Architect @ GetFeedback Platform
by SurveyMonkey
@rdohms

8. Sustainable Architectural Design Decisions (InfoQ)
“Capturar o pensamento de cada decisão é difícil, e
tem um custo alto”

9. “Projetos sustentáveis dependem de conhecimento
Arquitetural”
Sustainable Architectural Design Decisions (InfoQ)

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

13. ADRArchitectural Decision Record
Registro de Decisão Arquitetural

14. Context (Contexto)
Decision (Decisão)
Consequences (Consequências)
ADR0001 - Registrar Decisões
Date: 2020-12-01
Status
Approved

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/

22. Your DecisionDesigning Implementing
Escrever antes ou depois do fato?

23. “ADRs são ótimas plataformas de discussão”

24. “ADRs são ótimas para catalogar débito técnico”

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?

26. Quando e para oque escrever ADRs?

27. Mudanças
impactantes
Quando e para oque escrever ADRs?

28. Mudanças
impactantes
Más
decisões
Quando e para oque escrever ADRs?

29. Mudanças
impactantes
Más
decisões
Débito
técnico
Quando e para oque escrever ADRs?

30. Mudanças
impactantes
Más
decisões
Débito
técnico
Implementações
fora do comum
Quando e para oque escrever ADRs?

31. Velha Decisão
Superseded by
Nova Decisão
Podemos mudar uma ADR?
Replaced by

32. Proposed Accepted
Deprecated
Superseded: by 0002
Amended: by 0002
*: by 0002

33. /docs/adr
Onde colocar ADRs?

34. acme/user-managment acme/billing acme/content-creator acme/…

35. acme/user-managment acme/billing acme/content-creator acme/…
ADR-0003: Do not implement authentication layer for MVP

36. acme/user-managment acme/billing acme/content-creator acme/…
acme/backend-chapter acme/frontend-chapter
ADR-0003: Do not implement authentication layer for MVP

37. acme/user-managment acme/billing acme/content-creator acme/…
acme/backend-chapter acme/frontend-chapter
ADR-0003: Do not implement authentication layer for MVP
ADR-0005: Adopt the Doctrine Coding Standard

38. acme/user-managment
acme/architecture-chapter
acme/billing acme/content-creator acme/…
acme/backend-chapter acme/frontend-chapter
ADR-0003: Do not implement authentication layer for MVP
ADR-0005: Adopt the Doctrine Coding Standard

39. acme/user-managment
acme/architecture-chapter
acme/billing acme/content-creator acme/…
acme/backend-chapter acme/frontend-chapter
ADR-0003: Do not implement authentication layer for MVP
ADR-0005: Adopt the Doctrine Coding Standard
ADR-0007: All API dates should be formatted in RFC3339

40. adr-tools
https://github.com/npryce/adr-tools

41. Demo

42. @rdohms
https://doh.ms
Obrigado!
We are hiring!
https://grnh.se/d9197e541
https://grnh.se/9ccf65331us
Ottawa / Amsterdam
https://www.surveymonkey.com/r/adr-phpconf