{"id":31598267,"url":"https://github.com/endjin/dotnet-adr","last_synced_at":"2025-10-06T05:38:37.671Z","repository":{"id":48314101,"uuid":"230424449","full_name":"endjin/dotnet-adr","owner":"endjin","description":"A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADRs).","archived":false,"fork":false,"pushed_at":"2025-07-23T02:49:42.000Z","size":211,"stargazers_count":118,"open_issues_count":12,"forks_count":15,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-09-26T15:02:06.126Z","etag":null,"topics":["architectural-decision-records","architecture","documentation","dotnet","dotnet-adr","dotnet-global-tool","endjin","nuget","tools"],"latest_commit_sha":null,"homepage":"https://endjin.com","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/endjin.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,"zenodo":null}},"created_at":"2019-12-27T10:32:11.000Z","updated_at":"2025-09-25T00:05:41.000Z","dependencies_parsed_at":"2024-03-26T12:47:55.546Z","dependency_job_id":"85cad531-c13e-41db-b888-ddaa17d4ae01","html_url":"https://github.com/endjin/dotnet-adr","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/endjin/dotnet-adr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endjin%2Fdotnet-adr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endjin%2Fdotnet-adr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endjin%2Fdotnet-adr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endjin%2Fdotnet-adr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/endjin","download_url":"https://codeload.github.com/endjin/dotnet-adr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endjin%2Fdotnet-adr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278562483,"owners_count":26007196,"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","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["architectural-decision-records","architecture","documentation","dotnet","dotnet-adr","dotnet-global-tool","endjin","nuget","tools"],"created_at":"2025-10-06T05:38:35.088Z","updated_at":"2025-10-06T05:38:37.657Z","avatar_url":"https://github.com/endjin.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dotnet adr - Make Future You Thank Past You\n\nA cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR).\n\n[![Build Status](https://github.com/endjin/dotnet-adr/actions/workflows/build.yml/badge.svg)](https://github.com/endjin/dotnet-adr/actions/workflows/build.yml/)\n[![#](https://img.shields.io/nuget/v/adr.svg)](https://www.nuget.org/packages/adr/) \n[![IMM](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/total?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/total?cache=false)\n[![GitHub license](https://img.shields.io/badge/License-Apache%202-blue.svg)](https://raw.githubusercontent.com/endjin/dotnet-adr/master/LICENSE)\n\n## TLDR;\n\nArchitectural Decision Records (ADRs) are simple Markdown documents used to record technical choices for a project by summarizing the context, the decision, and the consequences. dotnet `adr` is a tool and a bundle of the most common ADR templates you can use to create and maintain ADRs in your solution. \n\nInstall using:\n\n`dotnet tool install -g adr`\n\nInstall the default ADR templates using:\n\n`adr templates package set adr.templates`\n\n`adr templates package install`\n\nCreate a new ADR using:\n\n`adr new \u003cTITLE\u003e`\n\n## Table of Contents\n\n- [dotnet adr - Make Future You Thank Past You](#dotnet-adr---make-future-you-thank-past-you)\n  - [TLDR;](#tldr)\n  - [Table of Contents](#table-of-contents)\n  - [What are Architectural Decision Records?](#what-are-architectural-decision-records)\n  - [Why we adopted ADRs](#why-we-adopted-adrs)\n  - [Why create another ADR tool?](#why-create-another-adr-tool)\n  - [Getting Started](#getting-started)\n    - [Installing dotnet adr](#installing-dotnet-adr)\n    - [Using dotnet adr](#using-dotnet-adr)\n    - [Configure the default ADR location in your repo](#configure-the-default-adr-location-in-your-repo)\n  - [ADR Templates and ADR Template Packages](#adr-templates-and-adr-template-packages)\n    - [Example ADRs](#example-adrs)\n    - [Which ADR templates are available out of the box?](#which-adr-templates-are-available-out-of-the-box)\n      - [Alexandrian Pattern](#alexandrian-pattern)\n      - [Business Case Pattern](#business-case-pattern)\n      - [Markdown Architectural Decision Records (MADR)](#markdown-architectural-decision-records-madr)\n      - [Merson Pattern](#merson-pattern)\n      - [Nygard Pattern](#nygard-pattern)\n      - [Planguage Pattern](#planguage-pattern)\n      - [Tyree and Akerman Pattern](#tyree-and-akerman-pattern)\n    - [Custom ADR Templates and ADR Template Packages](#custom-adr-templates-and-adr-template-packages)\n    - [Create your own custom ADR Template Package](#create-your-own-custom-adr-template-package)\n      - [Store template file locally](#store-template-file-locally)\n  - [Local System Details](#local-system-details)\n  - [DevOps](#devops)\n  - [Packages](#packages)\n  - [Community Contributions](#community-contributions)\n  - [Licenses](#licenses)\n  - [Project Sponsor](#project-sponsor)\n  - [Acknowledgements](#acknowledgements)\n  - [Code of conduct](#code-of-conduct)\n  - [IP Maturity Model (IMM)](#ip-maturity-model-imm)\n  - [IP Maturity Model Scores](#ip-maturity-model-scores)\n\n## What are Architectural Decision Records?\n\nContext drives intent, which manifests as code. This is the socio-technical contract of modern software development. If over time, code is the only remaining archeological artefact, we are simply left with *effect* without knowing the *cause*.\n\nOver the last decade we have found immense value in [Gherkin](https://specflow.org/learn/gherkin/) based [Executable Specifications](https://gojko.net/books/specification-by-example/) to describe the behaviour (or intent) of a system; in fact the Gherkin ([Specflow](https://specflow.org/)) feature files have often outlived the original code and have been used to re-implement the system using a more modern language or framework.\n\nNow we have the code, and the intent, but we're still missing an artefact that captures the context. Architectural Decision Records (ADRs) fill this requirement exceedingly well. ADRs are simple text documents (our preferred format is Markdown) which [précis](https://www.merriam-webster.com/dictionary/pr%C3%A9cis) some or all of the following aspects of a decision:\n\n- Context\n- Assumptions\n- Options\n- Rationale\n- Decision\n- Consequences\n\nThe 1st [Law of Simplicity](http://lawsofsimplicity.com/) is \"Reduce\", and much like Bezos' infamous [6-page memo format](https://www.cnbc.com/2018/04/23/what-jeff-bezos-learned-from-requiring-6-page-memos-at-amazon.html), brevity is the key to the power of ADRs. Rather than a heavyweight functional specification, ADRs have much more in common with minutes from a meeting. The meeting may take hours, but reading the minutes, should take... minutes.\n\nGood code comments don't explain what the code does, they explain what the developer was thinking when they wrote the code, what assumptions they were making, and what they were trying to achieve. This allows anyone reviewing the code to spot any faults with logic, assumptions that proved to be incorrect, or requirements which have evolved. ADRs operate on the same principle. Anyone can review the ADRs and quickly grok the context, the assumptions, the rationale, the decision, and the consequences, without being bogged down in detail.\n\nWith modern cloud native solutions, recording context takes on a nuanced significance; cloud services vary from IaaS to PaaS to SaaS, as a consumer you are not in control of the feature set, the scale characteristics, or the price point. When making an architectural decision you may be constrained by a missing feature, a financial budget, or a performance target. The speed of cloud innovation means that any of these constraints can change on a monthly basis. [Keeping track](https://azureweekly.info) of [feature announcements](https://powerbiweekly.info) and re-evaluating the context of previously made decisions is an engineering practice you should adopt as part of the ADR process.  \n\nThe principles of ADRs are straightforward, but the implementation can be simple or as complex as your team or organization requires. The out-of-the-box default template is the [Nygard Pattern](#nygard-pattern), but this tool and repo contains a number of alternative [templates](#which-adr-templates-are-available-out-of-the-box) you can choose from, or you can [create your own](#create-your-own-custom-adr-template-package). If you want to read some real ADRs, check out these [examples](#example-adrs) from our own OSS projects.\n\nWe find ADRs to be most effective when they are co-located with the code, in the same repo. We've worked on projects where \"all documentation lives in Wiki / Confluence / SharePoint\" because not all stakeholders have access to source control repos, but we find this approach to be high friction for all parties involved. This tool, `adr`, is designed to encapsulate our recommended practices. \n\n## Why we adopted ADRs\n\nSeveral years ago we worked on a very complex project which required R\u0026D, technical spikes, benchmarking, load-testing, performance tuning cycles, and further benchmarking in order to find the optimal solution. This process worked incredibly well and we delivered orders of magnitude performance improvements over the existing solution.\n\nDuring the end-of-project retrospective we identified two sub-optimal outcomes; firstly we felt that while we had worked minor miracles in our technical solutions, the customer never seemed particularly impressed by the improvements. Secondly, the customer hired a new architect just as we finished delivering the solution, and as part of their onboarding process reviewed the solution and criticized almost every aspect with \"I wouldn't have done it that way. At my last job we approached it like X and found it to be best\".\n\nWe realized that the two issues were related. For the first problem, we concluded that we had failed to follow the most basic instruction you're given at school; \"show your workings\". We had hidden all the hard work, all the complexity, all of the hypothesis-testing experiments, and just presented the results *Fait Accompli*. The second problem had the same root cause. Because we had not recorded all of our experiments in a systematic way, we had no evidence to show that the approach the architect considered \"best\" was actually the first approach we took, but when we benchmarked and load-tested the approach it couldn't handle the data throughput at the price-point required by the customer. \"Best\" is entirely based on situational context. What's \"best\" in one situation is inappropriate in another.\n\nWe embrace evidence-based-decision-making as part of our experimental approach, and wanted to find a process that would allow us to document this in a formalized way. We did some research and discovered Architectural Decision Records. They have now become a fundamental part of our software and data engineering processes.\n\nAs a fully-remote organization, a secondary benefit from adopting ADRs has been how it allows us to enable distributed and asynchronous evidence gathering, discussions, decision making, and onboarding. This benefit manifests in a number of different ways; firstly, the process of drafting and evolving an ADR as a working group. Secondly, once the ADR reaches its \"proposed status\" it's very easy for senior decision makers to quickly grok the summary of the decision and provide input. Thirdly, any new contributor can get up to speed by using the collection of ADRs, AKA an Architecture Decision Log (ADL), to understand all the historical decisions that have been made, and most importantly what the situational context was at the point the decisions were made.\n\n## Why create another ADR tool?\n\nOne of the reasons for \"re-inventing the wheel\" with `adr` when there are so many ADR tools already in existence, is that almost all of those existing tools are opinionated to the point of embedding the ADR templates into the tooling.\n\nSince we adopted ADRs in 2018, we've changed our default template a number of times. Thus, with `adr` we wanted to decouple the tool from the templates, and make use of NuGet content packages as a mechanism to enable the ecosystem to build / use / share their own templates internally (using Azure DevOps or GitHub private package feeds), or publicly using [nuget.org](https://www.nuget.org/packages?q=Tags%3A%22dotnet-adr%22).\n\n## Getting Started\n\n### Installing dotnet adr\n\n`adr` is a [.NET global tool](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools), which means once installed, it's available on the PATH of your machine.\n\nTo install the `adr` global tool use the following command:\n\n`dotnet tool install -g adr`\n\nTo install a specific version, use:\n\n`dotnet tool install -g adr --version \u003cversion-number\u003e`\n\nTo update to the latest version of the tool, use:\n\n`dotnet tool update -g adr`\n\nTo uninstall the tool, use:\n\n`dotnet tool uninstall -g adr`\n\nTo list all the global tools installed on your machine, open a command prompt and type:\n\n`dotnet tool list -g`\n\n### Using dotnet adr\n\nHere is a detailed list of the available `adr` commands:\n\n`adr new \u003cTITLE\u003e` - Creates a new Architectural Decision Record, from the current default ADR Template, from the current ADR Template package.\n\n`adr new \u003cTITLE\u003e -i \u003cRECORD NUMBER\u003e` - Creates a new Architectural Decision Record, superseding the specified ADR record, which will have its status updated to reflect to point to this newly created ADR.\n\n`adr new \u003cTITLE\u003e -p \u003cPATH\u003e` - Creates a new Architectural Decision Record, from the current default ADR Template, from the current ADR Template package, for the Architecture Knowledge Management (AKM) folder located at the specified path.\n\n`adr new \u003cTITLE\u003e -i \u003cRECORD NUMBER\u003e -p \u003cPATH\u003e` - Creates a new Architectural Decision Record, for the Architecture Knowledge Management (AKM) folder located at the specified path, superseding the specified ADR record, which will have its status updated to reflect to point to this newly created ADR.\n\n`adr templates` - Manipulate ADR Templates \u0026 ADR Template Packages. Root command for template operations. Will list available sub-commands.\n\n`adr templates show` - Displays the detailed metadata of the current default ADR Template.\n\n`adr templates show --id-only` - Displays the id of the current default ADR Template.\n\n`adr templates set \u003cTEMPLATE ID\u003e` - Sets the default ADR Template. The `\u003cTEMPLATE ID\u003e` can be obtained from `adr templates show`\n\n`adr templates list` - Displays a table containing the detailed metadata of all ADR Templates contained in the current default ADR Template Package.\n\n`adr templates list --ids-only` - Displays the ids of all ADR Templates contained in the current default ADR Template Package.\n\n`adr templates list --format-list` - Displays a list of the detailed metadata of all ADR Templates contained in the current default ADR Template Package.\n\n`adr templates package install` - Installs the latest version of the currently set ADR Templates Package.\n\n`adr templates package update` - Updates to the latest version of the currently set ADR Templates Package.\n\n`adr templates package set \u003cPACKAGE ID\u003e` - Sets the default NuGet ADR Template Package. Use `adr.templates`.\n\n`adr templates package show` - Displays the default NuGet ADR Template Package.\n\n`adr environment` - Manipulate the dotnet-adr environment. Root command for environment operations. Will list available sub-commands.\n\n`adr environment init \u003cPATH\u003e` - Initializes a new Architecture Knowledge Management (AKM) folder. If `\u003cPATH\u003e` is omitted, it will create `docs\\adr` in the current directory.\n\n`adr environment reset` - Resets the `adr` environment back to its default settings.\n\n### Configure the default ADR location in your repo\n\nWhile `adr` is quite flexible in allowing you to specify were to create or update an ADR, either in the current directory, or by specifying a custom path using `adr new \u003cTITLE\u003e -p \u003cPATH\u003e`, sometime it's better to create a \"pit of quality\" and standardize the Architecture Knowledge Management (AKM) folder location for all users of the tool.\n\nTo support this requirement you can create a file in the root of your repo called `adr.config.json` which must have the following format:\n\n```json\n{\n    \"path\": \"./Docs/Adr\"\n}\n```\n\nWhere the value of `path` is relative to the root of the repo.\n\n## ADR Templates and ADR Template Packages\n\n### Example ADRs\n\nIt's always hard to write a document starting from scratch; this is why the default ADR templates contain guidance in the form of headings and notes. Real-world examples are always much more helpful, so below is a list of some publicly available ADRs from our [Open Source projects](https://endjin.com/what-we-do/open-source/). If you explore the repos, you can find more examples:\n\n- [Updating Rx.NET Build for .NET 7.0 era Tooling](https://github.com/dotnet/reactive/blob/main/Rx.NET/Documentation/adr/0001-net7.0-era-tooling-update.md)\n- [Implementation of client-side Claims Evaluation](https://github.com/marain-dotnet/Marain.Claims/blob/main/Documentation/ADRs/0001-client-side-claims-evaluation.md)\n- [Corvus.Tenancy will not create storage containers automatically](https://github.com/corvus-dotnet/Corvus.Tenancy/blob/main/docs/adr/0003-no-automatic-storage-container-creation.md)\n- [Multitargeting .NET Standard 2.0 and 2.1](https://github.com/menes-dotnet/Menes/blob/main/docs/adr/0002-multitargeting-.net-standard-2.0-and-2.1.md)\n- [Integration of an Event Store for audit and \"change feed\" purposes](https://github.com/marain-dotnet/Marain.Workflow/blob/master/docs/adr/0001-integration-of-event-store.md)\n\n### Which ADR templates are available out of the box?\n\nWe have collected a number of popular ADR templates.\n\n\u003e NOTE: the status of the Open Source License for some of the templates is unclear. See each template for more details.\n\n#### Alexandrian Pattern\n\nADR using the Alexandrian [Pattern Language Approach](https://en.wikipedia.org/wiki/Pattern_language) coined by Architect Christopher Alexander et. al in 1977, which distils the decision record into the following headings:\n\n- Prologue (Summary)\n- Discussion (Context)\n- Solution (Decision)\n- Consequences (Results)\n\nSource [Joel Parker Henderson](https://github.com/joelparkerhenderson/architecture-decision-record/), see this [issue about licensing](https://github.com/joelparkerhenderson/architecture-decision-record/issues/30).\n\nSet as the default template using `adr templates set alexandrian`\n\n#### Business Case Pattern\n\nEmphasizes creating a business case for a decision, including criteria, candidates, and costs, [created by Joel Parker Henderson](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-for-business-case/index.md), which distils the decision record into the following headings:\n\n- Title\n- Status\n- Evaluation criteria\n- Candidates to consider\n- Research and analysis of each candidate\n  - Does/doesn't meet criteria and why\n  - Cost analysis\n  - SWOT analysis\n  - Opinions and feedback\n- Recommendation\n\nSource [Joel Parker Henderson](https://github.com/joelparkerhenderson/architecture-decision-record/), see this [issue about licensing](https://github.com/joelparkerhenderson/architecture-decision-record/issues/30).\n\nSet as the default template using `adr templates set business-case`\n\n#### Markdown Architectural Decision Records (MADR)\n\nArchitectural Decisions using Markdown and Architectural Decision Records, by [Oliver Kopp](https://adr.github.io/madr/), which distils the decision record into the following headings:\n\n- Title\n- Status\n- Context and Problem Statement\n- Decision Drivers\n- Considered Options\n- Decision Outcome\n  - Positive Consequences\n  - Negative Consequences\n- Pros and Cons of the Options\n  - [option 1]\n  - [option 2]\n  - [option 3]\n- Links\n\n[Available](https://adr.github.io/madr/) as dual-license under [MIT](https://opensource.org/licenses/MIT) and [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/). You can choose between one of them if you use this work.\n\nSet as the default template using `adr templates set madr`\n\n#### Merson Pattern\n\nAn adaptation of the [Nygard pattern](#nygard-pattern), by [Paulo Merson](https://github.com/pmerson/ADR-template) which adds the rationale behind the decision. It distils the decision record into the following headings:\n\n- Title\n- Status\n- Decision\n- Rationale\n- Consequences\n\n[Available](https://github.com/pmerson/ADR-template) under the [MIT License](https://github.com/pmerson/ADR-template/blob/master/LICENSE).\n\nSet as the default template using `adr templates set merson`\n\n#### Nygard Pattern\n\nA simple, low-friction \"Agile\" ADR approach by [Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions), which distils the decision record into the following headings:\n\n- Title\n- Status\n- Context\n- Decision\n- Consequences\n\n[Available](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) under [CC0 1.0 Universal (CC0 1.0) Public Domain Dedication](https://creativecommons.org/publicdomain/zero/1.0/).\n\nSet as the default template using `adr templates set nygard`\n\n#### Planguage Pattern\n\nA Quality Assurance oriented approach by [John Terzakis](http://www.iaria.org/conferences2012/filesICCGI12/Tutorial%20Specifying%20Effective%20Non-func.pdf), which distils the decision record into the following headings:\n\n- Title\n- Status\n- Tag\n- Gist\n- Requirement\n- Rationale\n- Priority\n- Stakeholders\n- Owner\n- Author\n- Revision\n- Date\n- Assumptions\n- Risks\n- Defined\n\nSource [Joel Parker Henderson](https://github.com/joelparkerhenderson/architecture-decision-record/), see this [issue about licensing](https://github.com/joelparkerhenderson/architecture-decision-record/issues/30).\n\nSet as the default template using `adr templates set planguage`\n\n#### Tyree and Akerman Pattern\n\nADR approach by [Jeff Tyree and Art Akerman](https://personal.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf), Capital One Financial, which distils the decision record into the following headings:\n\n- Title\n- Status\n- Issue\n- Decision\n- Group\n- Assumptions\n- Constraints\n- Positions\n- Argument\n- Implications\n- Related decisions\n- Related requirements\n- Related artifacts\n- Related principles\n- Notes\n\nSource [Joel Parker Henderson](https://github.com/joelparkerhenderson/architecture-decision-record/), see this [issue about licensing](https://github.com/joelparkerhenderson/architecture-decision-record/issues/30).\n\nSet as the default template using `adr templates set tyree-ackerman`\n\n### Custom ADR Templates and ADR Template Packages\n\nADR Templates are simply markdown files which contain headings and guidance for the end users. The only hard requirement is that they contains `# Title` and `## Status` headings as `adr` uses Regular Expressions to find and replace these values to power the `adr new \u003cTITLE\u003e` and `adr new -s \u003cRECORD NUMBER\u003e \u003cTITLE\u003e` commands.\n\nThe default ADR Templates are contained in the `Endjin.Adr.Templates` project, which contains NuGet configuration elements in `Endjin.Adr.Templates.csproj` to create a NuGet \"content\" package, which is available via nuget.org as `adr.templates`.\n\n### Create your own custom ADR Template Package\n\nWhile we use [MADR](#markdown-architectural-decision-records-madr) as the default template, because it has a nice balance of simplicity and power, it doesn't mean that it's the best template for you, your team, and your organization. First check-out [the different templates](#which-adr-templates-are-available-out-of-the-box) which are available out of the box. If none of these are suitable then it's easy to make your own!\n\nThis repo contains an example extensibility \"Third Party\" ADR template example located in `/Solutions/ThirdParty.Adr.Templates`, this is also available via [nuget.org as thirdparty.adr.templates](https://www.nuget.org/packages/thirdparty.adr.templates/).\n\nThere are straightforward conventions for creating a customer ADR template package:\n\n1. Create a folder which matches the name of the template, using [kebab-case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). i.e. `my-custom-adr-template`\n2. Inside that folder create a `template.md` file\n3. Add the following front-matter and mandatory headings to `template.md`:\n\n```yaml\n---\nTitle: \nDescription: \nAuthors: \nEffort: \nMore Info: \nVersion: \nLast Modified: YYYY-MM-DD HH:MM\n---\n# Title \n\n## Status\n```\n\n4. Create a `.csproj` file which contains the following properties:\n\n```xml\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n\n  \u003cPropertyGroup\u003e\n    \u003cAssemblyName\u003ethirdparty.adr.templates\u003c/AssemblyName\u003e\n    \u003cTargetFramework\u003enet8.0\u003c/TargetFramework\u003e\n    \u003cIncludeBuildOutput\u003efalse\u003c/IncludeBuildOutput\u003e\n    \u003cSuppressDependenciesWhenPacking\u003etrue\u003c/SuppressDependenciesWhenPacking\u003e\n    \u003c!-- https://learn.microsoft.com/en-us/dotnet/core/tutorials/creating-app-with-plugin-support --\u003e\n    \u003cEnableDynamicLoading\u003etrue\u003c/EnableDynamicLoading\u003e\n  \u003c/PropertyGroup\u003e\n\n  \u003cPropertyGroup\u003e\n    \u003cPackageLicenseExpression\u003eApache-2.0\u003c/PackageLicenseExpression\u003e\n    \u003cPackageDescription\u003eAn example demonstrating how a 3rd Party could create a dotnet-adr template package.\u003c/PackageDescription\u003e\n    \u003cPackageTags\u003edotnet-adr dotnet-adr-template architecture tools endjin\u003c/PackageTags\u003e\n    \u003cPackageReleaseNotes\u003e\u003c/PackageReleaseNotes\u003e\n  \u003c/PropertyGroup\u003e\n\n  \u003cItemGroup\u003e\n    \u003cContent Include=\"my-custom-adr-template\\template.md\"\u003e\n      \u003cPackagePath\u003econtent\\my-custom-adr-template\u003c/PackagePath\u003e\n      \u003cPack\u003etrue\u003c/Pack\u003e\n    \u003c/Content\u003e\n  \u003c/ItemGroup\u003e\n\n\u003c/Project\u003e\n```\n\n5. When the solution is built, a `thirdparty.adr.templates.nupkg` NuGet package will be created. Publish this to nuget.org\n\nTo swap between the packages use the following `adr` commands:\n\n`adr templates package set thirdparty.adr.templates`\n\nNext, to download the latest version of 'thirdparty.adr.templates` use the command:\n\n`adr templates install`\n\nTo see the currently set default package, use:\n\n`adr templates package show`\n\nTo see the id of the currently set default template, use:\n\n`adr templates show`\n\nTo revert to the \"official\" ADT Template Package you can either, reset the environment:\n\n`adr environment reset`\n\nor:\n\n`adr templates package set adr.templates`\n\nThen:\n\n`adr templates install`\n\n#### Store template file locally\n\nOptionally, store the template file file inside the repository, and specify the TemplatePath in the `adr.config.json` file.\n\n```json\n{\n    \"templatePath\": \"./Docs/adr-template.md\"\n}\n```\n\n## Local System Details\n\n`adr` stores various configuration files and packages in an application profile folder created in:\n\n`%%UserProfile%%\\AppData\\Roaming\\endjin\\dotnet-adr`\n\nTemplates are stored in:\n\n`templates\\`\n\nConfiguration in:\n\n`configuration\\`\n\nThe templates NuGet package is cached in `%%UserProfile%%\\.nuget\\packages`. \n\n## DevOps\n\nThe project is [hosted on GitHub](https://github.com/endjin/dotnet-adr) and uses a [GitHub Actions workflow](https://github.com/endjin/dotnet-adr/blob/main/.github/workflows/build.yml) and [Endjin.RecommendedPractices.Build](https://www.powershellgallery.com/packages/Endjin.RecommendedPractices.Build/) to manage the full DevOps lifecycle.\n\n## Packages\n\nThe NuGet packages for the project, hosted on NuGet.org are:\n\n- [adr](https://www.nuget.org/packages/adr)\n- [adr.templates](https://www.nuget.org/packages/adr.templates)\n- [thirdparty.adr.templates](https://www.nuget.org/packages/thirdparty.adr.templates)\n\nIf you want to [Create your own custom ADR Template Package](#create-your-own-custom-adr-template-package), please add `dotnet-adr` to the `PackageTags` element.\n\n## Community Contributions\n\n- 2023-07-19 - [James Broome](https://twitter.com/jamesbroome_) provides an [overview of ADRs](https://endjin.com/blog/2023/07/architecture-decision-records) and some examples.\n- 2023-06-23 - [Rodrigo Juarez](https://twitter.com/rodrigojuarez) provides an overview of ADRs for .NET Developers and shows you how to get started with `adr`: [What Are Architecture Design Records (ADR), and How Can You Get Started as a .NET Developer?](https://trailheadtechnology.com/what-are-architecture-design-records-adr-and-how-can-you-get-started-as-a-net-developer/)\n- 2021-08-09 - [Christopher Laine](https://medium.com/@domingoladron) wrote a nice blog post about ADRs and dotnet adr: [Architectural Decision Records (ADR) with dotnet-adr](https://medium.com/it-dead-inside/architectural-decision-records-adr-with-dotnet-adr-9fa76104bcd7)\n\n## Licenses\n\nThis project is available under the Apache 2.0 open source license.\n\n[![GitHub license](https://img.shields.io/badge/License-Apache%202-blue.svg)](https://raw.githubusercontent.com/endjin/dotnet-adr/master/LICENSE)\n\nFor any licensing questions, please email [\u0026#108;\u0026#105;\u0026#99;\u0026#101;\u0026#110;\u0026#115;\u0026#105;\u0026#110;\u0026#103;\u0026#64;\u0026#101;\u0026#110;\u0026#100;\u0026#106;\u0026#105;\u0026#110;\u0026#46;\u0026#99;\u0026#111;\u0026#109;](\u0026#109;\u0026#97;\u0026#105;\u0026#108;\u0026#116;\u0026#111;\u0026#58;\u0026#108;\u0026#105;\u0026#99;\u0026#101;\u0026#110;\u0026#115;\u0026#105;\u0026#110;\u0026#103;\u0026#64;\u0026#101;\u0026#110;\u0026#100;\u0026#106;\u0026#105;\u0026#110;\u0026#46;\u0026#99;\u0026#111;\u0026#109;)\n\n## Project Sponsor\n\nThis project is sponsored by [endjin](https://endjin.com), a UK based Technology Consultancy which specializes in Data, AI, DevOps \u0026 Cloud, and is a [.NET Foundation Corporate Sponsor](https://dotnetfoundation.org/membership/corporate-sponsorship).\n\n\u003e We help small teams achieve big things.\n\nWe produce two free weekly newsletters:\n\n- [Azure Weekly](https://azureweekly.info) for all things about the Microsoft Azure Platform\n- [Power BI Weekly](https://powerbiweekly.info) for all things Power BI, Microsoft Fabric, and Azure Synapse Analytics\n\nKeep up with everything that's going on at endjin via our [blog](https://endjin.com/blog), follow us on [Twitter](https://twitter.com/endjin), [YouTube](https://www.youtube.com/c/endjin) or [LinkedIn](https://www.linkedin.com/company/endjin).\n\nWe have become the maintainers of a number of popular .NET Open Source Projects:\n\n- [Reactive Extensions for .NET](https://github.com/dotnet/reactive)\n- [Reaqtor](https://github.com/reaqtive)\n- [Argotic Syndication Framework](https://github.com/argotic-syndication-framework/)\n\nAnd we have over 50 Open Source projects of our own, spread across the following GitHub Orgs:\n\n- [endjin](https://github.com/endjin/)\n- [Corvus](https://github.com/corvus-dotnet)\n- [Menes](https://github.com/menes-dotnet)\n- [Marain](https://github.com/marain-dotnet)\n- [AIS.NET](https://github.com/ais-dotnet)\n\nAnd the DevOps tooling we have created for managing all these projects is available on the [PowerShell Gallery](https://www.powershellgallery.com/profiles/endjin).\n\nFor more information about our products and services, or for commercial support of this project, please [contact us](https://endjin.com/contact-us). \n\n## Acknowledgements\n\n- [Patrik Svensson](https://twitter.com/firstdrafthell) for his help, support, feature requests, and amazing work on [Spectre.Console](https://github.com/spectreconsole/spectre.console), and [Covenant](https://github.com/patriksvensson/covenant)\n- [Joel Parker Henderson](https://github.com/joelparkerhenderson) for [collating the various ADR templates](https://github.com/joelparkerhenderson/architecture_decision_record) we make use of.\n- [David Glick](https://daveaglick.com/) for his incredibly [useful blog series](https://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-1) on the NuGet v3 SDK API.\n- [Martin Björkström](https://twitter.com/mholo65) for his [excellent gist](https://gist.github.com/mholo65/ad5776c36559410f45d5dcd0181a5c64) that does the heavy lifting of downloading and extracting NuGet packages.\n\n## Code of conduct\n\nThis project has adopted a code of conduct adapted from the [Contributor Covenant](http://contributor-covenant.org/) to clarify expected behaviour in our community. This code of conduct has been [adopted by many other projects](http://contributor-covenant.org/adopters/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [\u0026#104;\u0026#101;\u0026#108;\u0026#108;\u0026#111;\u0026#064;\u0026#101;\u0026#110;\u0026#100;\u0026#106;\u0026#105;\u0026#110;\u0026#046;\u0026#099;\u0026#111;\u0026#109;](\u0026#109;\u0026#097;\u0026#105;\u0026#108;\u0026#116;\u0026#111;:\u0026#104;\u0026#101;\u0026#108;\u0026#108;\u0026#111;\u0026#064;\u0026#101;\u0026#110;\u0026#100;\u0026#106;\u0026#105;\u0026#110;\u0026#046;\u0026#099;\u0026#111;\u0026#109;) with any additional questions or comments.\n\n## IP Maturity Model (IMM)\n\nThe [IP Maturity Model](https://github.com/endjin/Endjin.Ip.Maturity.Matrix) is endjin's IP quality assessment framework, which we've developed over a number of years when doing due diligence assessments of 3rd party systems. We've codified the approach into a [configurable set of rules](https://github.com/endjin/Endjin.Ip.Maturity.Matrix.RuleDefinitions), which are committed into the [root of a repo](imm.yaml), and a [Azure Function HttpTrigger](https://github.com/endjin/Endjin.Ip.Maturity.Matrix/tree/main/Solutions/Endjin.Ip.Maturity.Matrix.Host) HTTP endpoint which can evaluate the ruleset, and render an svg badge for display in repo's `readme.md`.\n\n## IP Maturity Model Scores\n\n[![Shared Engineering Standards](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/74e29f9b-6dca-4161-8fdd-b468a1eb185d?nocache=true)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/74e29f9b-6dca-4161-8fdd-b468a1eb185d?cache=false)\n\n[![Coding Standards](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/f6f6490f-9493-4dc3-a674-15584fa951d8?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/f6f6490f-9493-4dc3-a674-15584fa951d8?cache=false)\n\n[![Executable Specifications](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/bb49fb94-6ab5-40c3-a6da-dfd2e9bc4b00?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/bb49fb94-6ab5-40c3-a6da-dfd2e9bc4b00?cache=false)\n\n[![Code Coverage](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/0449cadc-0078-4094-b019-520d75cc6cbb?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/0449cadc-0078-4094-b019-520d75cc6cbb?cache=false)\n\n[![Benchmarks](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/64ed80dc-d354-45a9-9a56-c32437306afa?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/64ed80dc-d354-45a9-9a56-c32437306afa?cache=false)\n\n[![Reference Documentation](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/2a7fc206-d578-41b0-85f6-a28b6b0fec5f?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/2a7fc206-d578-41b0-85f6-a28b6b0fec5f?cache=false)\n\n[![Design \u0026 Implementation Documentation](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/f026d5a2-ce1a-4e04-af15-5a35792b164b?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/f026d5a2-ce1a-4e04-af15-5a35792b164b?cache=false)\n\n[![How-to Documentation](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/145f2e3d-bb05-4ced-989b-7fb218fc6705?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/145f2e3d-bb05-4ced-989b-7fb218fc6705?cache=false)\n\n[![Date of Last IP Review](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/da4ed776-0365-4d8a-a297-c4e91a14d646?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/da4ed776-0365-4d8a-a297-c4e91a14d646?cache=false)\n\n[![Framework Version](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/6c0402b3-f0e3-4bd7-83fe-04bb6dca7924?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/6c0402b3-f0e3-4bd7-83fe-04bb6dca7924?cache=false)\n\n[![Associated Work Items](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/79b8ff50-7378-4f29-b07c-bcd80746bfd4?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/79b8ff50-7378-4f29-b07c-bcd80746bfd4?cache=false)\n\n[![Source Code Availability](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/30e1b40b-b27d-4631-b38d-3172426593ca?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/30e1b40b-b27d-4631-b38d-3172426593ca?cache=false)\n\n[![License](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/d96b5bdc-62c7-47b6-bcc4-de31127c08b7?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/d96b5bdc-62c7-47b6-bcc4-de31127c08b7?cache=false)\n\n[![Production Use](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/87ee2c3e-b17a-4939-b969-2c9c034d05d7?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/87ee2c3e-b17a-4939-b969-2c9c034d05d7?cache=false)\n\n[![Insights](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/71a02488-2dc9-4d25-94fa-8c2346169f8b?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/71a02488-2dc9-4d25-94fa-8c2346169f8b?cache=false)\n\n[![Packaging](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/547fd9f5-9caf-449f-82d9-4fba9e7ce13a?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/547fd9f5-9caf-449f-82d9-4fba9e7ce13a?cache=false)\n\n[![Deployment](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/edea4593-d2dd-485b-bc1b-aaaf18f098f9?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/edea4593-d2dd-485b-bc1b-aaaf18f098f9?cache=false)\n\n[![OpenChain](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/66efac1a-662c-40cf-b4ec-8b34c29e9fd7?cache=false)](https://imm.endjin.com/api/imm/github/endjin/dotnet-adr/rule/66efac1a-662c-40cf-b4ec-8b34c29e9fd7?cache=false)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fendjin%2Fdotnet-adr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fendjin%2Fdotnet-adr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fendjin%2Fdotnet-adr/lists"}