├── .gitignore ├── ADR-template.md ├── ADR-template_es-ES.md ├── ADR-template_pt-BR.md ├── ADR-template_zh-CN.md ├── LICENSE └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | .idea/ 2 | *.iml -------------------------------------------------------------------------------- /ADR-template.md: -------------------------------------------------------------------------------- 1 | # ADR N: brief decision title 2 | Describe here the forces that influence the design decision, including technological, cost-related, and project local. 3 | 4 | ## Decision 5 | Describe here our response to these forces, that is, the design decision that was made. State the decision in full sentences, with active voice ("We will..."). 6 | 7 | ## Rationale 8 | Describe here the rationale for the design decision. Also indicate the rationale for significant *rejected* alternatives. This section may also indicate assumptions, constraints, requirements, and results of evaluations and experiments. 9 | 10 | ## Status 11 | [Proposed | Accepted | Deprecated | Superseded] 12 | If deprecated, indicate why. If superseded, include a link to the new ADR. 13 | 14 | ## Consequences 15 | Describe here the resulting context, after applying the decision. All consequences should be listed, not just the "positive" ones. 16 | -------------------------------------------------------------------------------- /ADR-template_es-ES.md: -------------------------------------------------------------------------------- 1 | # ADR N: título (breve) de la decisión 2 | Describa aquí las fuerzas que influyeron la decisión de diseño, incluyendo los aspectos tecnológicos, costos de proyecto. 3 | 4 | ## Decisión 5 | Describa aquí nuestra respuesta a estas fuerzas, es decir, la decisión de diseño que se tomó. Exprese la decisión en oraciones completas, con voz activa ("Nosotros haremos ..."). 6 | 7 | ## Justificación 8 | Describa aquí justificación de la decisión de diseño. Indique también la justificación de alternativas significativas que hayan sido rechazadas. Esta sección también puede indicar suposiciones, restricciones, requisitos y resultados de evaluaciones y experimentos. 9 | 10 | ## Estado 11 | [Propuesto | Aceptado | Obsoleto | Reemplazado] Si está obsoleto, indique por qué. Si se reemplaza, incluya un enlace al nuevo ADR. 12 | 13 | ## Consecuencias 14 | Describa aquí el contexto que resulta, después de aplicar la decisión. Todas las consecuencias deben enumerarse, no solo las consecuencias "positivas". Indique también las consecuencias "negativas". 15 | 16 | -------------------------------------------------------------------------------- /ADR-template_pt-BR.md: -------------------------------------------------------------------------------- 1 | # ADR N: título sucinto da decisão 2 | Descreva aqui as forças que influenciam a decisão, incluindo as tecnológicas, de custo, e específicas do projeto. 3 | 4 | ## Decisão 5 | Descreva aqui a nossa resposta a essas forças, isto é, a decisão de design tomada. Enuncie a decisão em sentenças completas e em voz ativa ("Nós iremos..."). 6 | 7 | ## Justificativa 8 | Descreva aqui a justificativa para a decisão de design. Indique também a justificativa para alternativas significativas que foram *rejeitadas*. Esta seção pode também listar premissas, restrições, requisitos e resultados de avaliações e experimentos. 9 | 10 | ## Status 11 | [Proposta | Aceita | Deprecada | Substituída] 12 | Se deprecada, indique o porquê. Se substituída, inclua um link para o novo ADR. 13 | 14 | ## Consequências 15 | Descreva aqui o contexto resultante após a aplicação da decisão. Todas as consequências devem ser listadas, não apenas as "positivas". 16 | 17 | -------------------------------------------------------------------------------- /ADR-template_zh-CN.md: -------------------------------------------------------------------------------- 1 | # 结构决策记录: 标题 2 | 描述影响决策的力量，包括技术、成本、及项目本身。 3 | 4 | ## 决策 5 | 描述面对这些力量，我们作出的决策是什么。用积极的声音，完整的句子陈述该决策，比如（“我们将...”）。 6 | 7 | ## 依据 8 | 描述促使作出这个决定的依据，也同时指出拒绝掉其它可行有效决策的依据。该部分还应该描述假设、约束、要求、及评估和实验的结果。 9 | 10 | ## 状态 11 | [已提出 | 已接受 | 已弃用 | 已取代] 12 | 13 | 如果已弃用，描述原因，如果已取代，贴出新的决策链接。 14 | 15 | ## 后果 16 | 描述下实施决策后的结果。决策带来的结果都应该给列出，不仅仅只是积极的一面。 17 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Paulo Merson 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ADR template 2 | 3 | Markdown template for Architecture Decision Records (ADRs). Here's the template... 4 | - [Template in English](ADR-template.md) 5 | - [Template in Spanish](ADR-template_es-ES.md) 6 | - [Template in Chinese](ADR-template_zh-CN.md) 7 | - [Template in Portuguese](ADR-template_pt-BR.md) 8 | 9 | ### Usage guidelines 10 | - Each ADR is a plain text, 1-2 page document 11 | - ADRs should be numbered 12 | - ADRs should be stored within each software project repo 13 | - Create a separate repo for crosscutting ADRs 14 | - Track ADRs in the backlog 15 | - Review ADRs 16 | - Create ADRs for *significant* design decisions 17 | - This template is a suggestion that you may want to adopt or adapt. In any case, establishing and sharing a template for ADRs in your team or organization is a good idea. 18 | 19 | ### Examples of ADRs using this template 20 | - [Use of the BFF pattern](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR003-bff-pattern.md) 21 | - [Use CQRS](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR005-cqrs-pattern.md) 22 | - [Use AWS as cloud provider](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR006-aws-as-cloud-provider.md) 23 | - [Use Payment Gateway in self-hosted mode](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR002-payment-gateway.md) 24 | - [Use the Wrapper pattern](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR004-wrapper-pattern.md) 25 | 26 | (These examples are project-specific, of course. The decision and rationale make sense in that project's context.) 27 | 28 | ### References 29 | This template is based on: 30 | - [Documenting Architecture Decisions](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). Blog post by Michael Nygard, 2011. 31 | - [Architecture Decision Records in Action](https://saturn2017.sched.com/event/9k2y/architecture-decision-records-in-action). SATURN 2017 presentation by Michael Keeling and Joe Runde. 32 | 33 | See also this [presentation by Ken Power at OOP](https://powerken.files.wordpress.com/2021/02/ken-power.oop-2021.adrs_.pdf). 34 | 35 | ### Why this template? 36 | - This template addresses a subtle yet fundamental deficiency of the [ADR structure originally proposed by Michael Nygard]((http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)): 37 | his proposed structure (Context; Decision; Status; Consequences) has no evident placeholder for the **rationale** 38 | behind the **design decision**. 39 | - The justification, the rationale, the "why" behind the design decision should stand out as a separate section in the 40 | template for at least three reasons: 41 | - It is remarkably important! (Authors cited further below agree.) 42 | - A separate section reminds the author of the ADR that that information must be captured. 43 | - The rationale section avoids cluttering other sections with rationale discussion. Devs may reference the ADRs several 44 | times to re-read the decision and consequences. They need to read the rationale just once, so rationale should not 45 | be mixed in the other sections. 46 | - Mark Richards and Neal Ford say "Why is more important than how" is the *Second Law of Software Architecture* ([Fundamentals of Software Architecture](https://learning.oreilly.com/library/view/fundamentals-of-software/9781492043447/)). 47 | - We say in our book "Record Rationale" is *Rule 5* of the *Seven Rules for Sound Documentation* ([Documenting Software Architectures, Second Edition](https://www.informit.com/store/documenting-software-architectures-views-and-beyond-9780321552686)). 48 | - George Fairbanks proposed *[Architecture Haiku](https://www.slideshare.net/matthewmccullough/architecture-haiku)*, 49 | which can be seen as an alternative approach to ADR. Haiku contents includes "design rationales". 50 | 51 | ### License 52 | 53 | MIT License 54 | 55 | Copyright (c) 2023 Paulo Merson 56 | 57 | Permission is hereby granted, free of charge, to any person obtaining a copy 58 | of this software and associated documentation files (the "Software"), to deal 59 | in the Software without restriction, including without limitation the rights 60 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 61 | copies of the Software, and to permit persons to whom the Software is 62 | furnished to do so, subject to the following conditions: 63 | 64 | The above copyright notice and this permission notice shall be included in all 65 | copies or substantial portions of the Software. 66 | 67 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 68 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 69 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 70 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 71 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 72 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 73 | SOFTWARE. 74 | 75 | --------------------------------------------------------------------------------