dotnet-adr
A .NET Global Tool for adopting and using Architectural Decision Records (ADR).
One of the reasons for "re-inventing the wheel" with dotnet-adr when there are so many ADR tools already in existance, is that almost all of those existing tools are opinionated to the point of embedding the ADR templates into the tooling. With dotnet-adr I 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 package feeds), or publicly using nuget.org.
See https://github.com/joelparkerhenderson/architecture_decision_record for a comprehensive overview of ADR.
dotnet-adr is built using Microsoft's System.CommandLine libraries. These packages, while still marked as experimental, are seeing lots of real-world usage, including tools such as BenchmarkDotNet.
A useful blog post for understanding System.CommandLine is Radu Matei's blog post "Building self-contained, single executable .NET Core 3 CLI tools".
dotnet global tools
adr is a .NET global tool, which means once installed, it's available on the PATH of your machine.
To list all the global tools installed on your machine, open a command prompt and type:
dotnet tool list -g
To install the adr global tool use the following command:
dotnet tool install -g adr
To install a specific version, use:
dotnet tool install -g adr --version <version-number>
To update to the latest version of the tool, use:
dotnet tool update -g adr
To uninstall the tool, use:
dotnet tool uninstall -g adr
dotnet-suggest
adr supports dotnet suggest, for tab based auto completion.
To install dotnet suggest:
dotnet tool install -g dotnet-suggest
Next check if you have a PowerShell profile configured, by opening a PowerShell prompt and typing the following:
echo $profile
You should see something like:
$ENV:USERPROFILE\Documents\PowerShell\Microsoft.PowerShell_profile.ps1
If you don't see such a file run the following command:
Invoke-WebRequest -Uri https://raw.githubusercontent.com/dotnet/command-line-api/master/src/System.CommandLine.Suggest/dotnet-suggest-shim.ps1 -OutFile $profile
Otherwise, copy the contents of the file above and paste it into your pre-existing profile.
ADR Commands
Once you have dotnet-suggest installed, you can use adr then TAB to explore the available commands. Here is a detailed list of the available commands:
adr init <PATH> - Initialises a new ADR repository. If <PATH> is omitted, it will create docs\adr in the current directory.
adr new <TITLE> - Creates a new Architectural Decision Record, from the current default ADR Template, from the current ADR Template package.
adr new -s <RECORD NUMBER> <TITLE> - Creates a new Architectural Decision Record, superseding the specified ADR record, which will have it's status updated to reflect this change.
adr templates - Manipulate ADR Templates & ADR Template Packages. Root command for template operations. Will list available sub-commands.
adr templates default show - Displays the detailed metadata of the current default ADR Template.
adr templates default show --id-only - Displays the id of the current default ADR Template.
adr templates default set <TEMPLATE ID> - Sets the default ADR Template. The <TEMPLATE ID> can be obtained from adr templates default show
adr templates list - Displays the detailed metadata of all ADR Templates contained in the current default ADR Template Package.
adr templates list --ids-only - Displays the ids of all ADR Templates contained in the current default ADR Template Package.
adr templates update - Updates to the latest version of the currently set ADR Templates Package.
adr templates package set <PACKAGE ID> - Sets the default NuGet ADR Template Package.
adr templates package show - Displays the default NuGet ADR Template Package.
adr environment - Manipulate the dotnet-adr environment. Root command for environment operations. Will list available sub-commands.
adr environment reset - Resets the dotnet-adr environment back to its default settings.
ADR Templates & ADR Template Packages
ADR 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 dotnet-adr uses Regular Expressions to find and replace these values to power the adr new <TITLE> and adr new -s <RECORD NUMBER> <TITLE> commands.
The 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.
To test extensibility, this solution contains a second "Third Party" ADR template example in ThirdParty.Adr.Templates, this is also available via NuGet.org as thirdparty.adr.templates.
To swap between the packages use the following dotnet-adr commands:
adr templates package set thirdparty.adr.templates
Next, to download the latest version of 'thirdparty.adr.templates` use the command:
adr templates update
To see the currently set default package, use:
adr templates package show
To see the id of the currently set default template, use:
adr templates default show
To revent to to the "official" ADT Template Package you can either, reset the environment:
adr environment reset
or:
adr templates package set adr.templates
Then:
adr templates update
System Details
An application profile folder is created in:
%%UserProfile%%\AppData\Roaming\endjin\dotnet-adr
Templates are stored in:
templates\
Configuration in:
configuration\
The templates NuGet package is cached in %%UserProfile%%\.nuget\packages.
CI / CD
The project is hosted on Azure DevOps under the endjin-labs org.
Packages
The NuGet packages for the project, hosted on NuGet.org are:
Licenses
This project is available under the Apache 2.0 open source license.
For any licensing questions, please email licensing@endjin.com
Project Sponsor
This project is sponsored by endjin, a UK based Microsoft Gold Partner for Cloud Platform, Data Platform, Data Analytics, DevOps, a Power BI Partner, and .NET Foundation Corporate Sponsor.
We help small teams achieve big things.
For more information about our products and services, or for commercial support of this project, please contact us.
We produce two free weekly newsletters; Azure Weekly for all things about the Microsoft Azure Platform, and Power BI Weekly.
Keep up with everything that's going on at endjin via our blog, follow us on Twitter, or LinkedIn.
Our other Open Source projects can be found on our website
Acknowledgements
- Joel Parker Henderson for collating the various ADR templates we make use of.
- David Glick for his incredibly useful blog series on the NuGet v3 SDK API.
- Martin Björkström for his excellent gist that does the heavy lifting of downloading and extracting NuGet packages.
- Radu Matei for his helpful blog post "Building self-contained, single executable .NET Core 3 CLI tools".
Code of conduct
This project has adopted a code of conduct adapted from the Contributor Covenant to clarify expected behavior in our community. This code of conduct has been adopted by many other projects. For more information see the Code of Conduct FAQ or contact hello@endjin.com with any additional questions or comments.
IP Maturity Matrix (IMM)
The IP Maturity Matrix is endjin's IP quality framework; it defines a configurable set of rules, which are committed into the root of a repo, and a Azure Function HttpTrigger which can evaluate the ruleset, and render an svg badge for display in repo's readme.md.
This approach is based on our 10+ years experience of delivering complex, high performance, bleeding-edge projects, and due diligence assessments of 3rd party systems. For detailed information about the ruleset see the IP Maturity Matrix repo.