{"id":13452287,"url":"https://github.com/pmerson/ADR-template","last_synced_at":"2025-03-23T19:34:01.864Z","repository":{"id":47373683,"uuid":"127899650","full_name":"pmerson/ADR-template","owner":"pmerson","description":"A md template for Architecture Decision Records (ADRs)","archived":false,"fork":false,"pushed_at":"2023-10-21T02:54:22.000Z","size":16,"stargazers_count":62,"open_issues_count":1,"forks_count":34,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-07-31T07:18:39.851Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pmerson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-03T11:47:17.000Z","updated_at":"2024-07-15T13:32:34.000Z","dependencies_parsed_at":"2024-01-14T07:18:30.264Z","dependency_job_id":null,"html_url":"https://github.com/pmerson/ADR-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmerson%2FADR-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmerson%2FADR-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmerson%2FADR-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmerson%2FADR-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pmerson","download_url":"https://codeload.github.com/pmerson/ADR-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221900817,"owners_count":16898988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T07:01:19.550Z","updated_at":"2024-10-28T18:30:55.571Z","avatar_url":"https://github.com/pmerson.png","language":null,"funding_links":[],"categories":["Others"],"sub_categories":[],"readme":"# ADR template\n\nMarkdown template for Architecture Decision Records (ADRs). Here's the template...\n - [Template in English](ADR-template.md)\n - [Template in Spanish](ADR-template_es-ES.md)\n - [Template in Chinese](ADR-template_zh-CN.md)\n - [Template in Portuguese](ADR-template_pt-BR.md)\n\n### Usage guidelines \n - Each ADR is a plain text, 1-2 page document\n - ADRs should be numbered\n - ADRs should be stored within each software project repo\n - Create a separate repo for crosscutting ADRs\n - Track ADRs in the backlog\n - Review ADRs\n - Create ADRs for *significant* design decisions\n - 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.\n\n### Examples of ADRs using this template\n - [Use of the BFF pattern](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR003-bff-pattern.md)\n - [Use CQRS](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR005-cqrs-pattern.md)\n - [Use AWS as cloud provider](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR006-aws-as-cloud-provider.md)\n - [Use Payment Gateway in self-hosted mode](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR002-payment-gateway.md)\n - [Use the Wrapper pattern](https://github.com/miyagis-forests/farmacy-food-kata/blob/main/ADRs/ADR004-wrapper-pattern.md)\n\n(These examples are project-specific, of course. The decision and rationale make sense in that project's context.) \n \n### References\nThis template is based on: \n - [Documenting Architecture Decisions](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). Blog post by Michael Nygard, 2011.\n - [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.\n \nSee also this [presentation by Ken Power at OOP](https://powerken.files.wordpress.com/2021/02/ken-power.oop-2021.adrs_.pdf).  \n \n### Why this template?\n- 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)):  \nhis proposed structure (Context; Decision; Status; Consequences) has no evident placeholder for the **rationale** \nbehind the **design decision**. \n- The justification, the rationale, the \"why\" behind the design decision should stand out as a separate section in the\ntemplate for at least three reasons:\n    - It is remarkably important! (Authors cited further below agree.)\n    - A separate section reminds the author of the ADR that that information must be captured. \n    - The rationale section avoids cluttering other sections with rationale discussion. Devs may reference the ADRs several \n     times to re-read the decision and consequences. They need to read the rationale just once, so rationale should not \n     be mixed in the other sections.\n- 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/)).\n- 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)).\n- George Fairbanks proposed *[Architecture Haiku](https://www.slideshare.net/matthewmccullough/architecture-haiku)*, \nwhich can be seen as an alternative approach to ADR. Haiku contents includes \"design rationales\". \n\n### License\n\nMIT License\n\nCopyright (c) 2023 Paulo Merson\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmerson%2FADR-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpmerson%2FADR-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmerson%2FADR-template/lists"}