-
Notifications
You must be signed in to change notification settings - Fork 44
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
10 changed files
with
140 additions
and
137 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| # Contributing to adr.github.io | ||
|
|
||
| To improve this page, head to <https://github.com/adr/adr.github.io>, edit `index.md` or `_tabs/*.md`, and submit a pull request. | ||
| To improve this page, head to <https://github.com/adr/adr.github.io>, edit `_posts/*.md`, and submit a pull request. | ||
|
|
||
| See [Chirpy's Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/) post for information on possible styling. | ||
| The [source](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/_posts/2019-08-08-text-and-typography.md?plain=1) shows the respective Markdown source. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| --- | ||
| title: AD Practices | ||
| toc: true | ||
| --- | ||
|
|
||
| > The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. | ||
| {: .prompt-info } | ||
|
|
||
| [Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page. | ||
|
|
||
| ## AD Making | ||
|
|
||
| The [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book, feature an AD making and capturing activity, which is positioned as one of the essential activities in DPR. | ||
|
|
||
| [Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. | ||
|
|
||
| ## Good ADRs --- and How to Get to Them | ||
|
|
||
| ### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: | ||
|
|
||
| 1. [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html), suggesting five criteria abbreviated as START. | ||
| 2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) | ||
| 3. [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns. | ||
| 4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) | ||
| 5. [A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) proposes five criteria and a checklist to decide when it is time to set the status of a single decision to "done": evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the 'D' in *ecADR*. | ||
| 6. Context, background and examples of good and bad justifications can be found in [this blog post](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html). | ||
| 7. [How to review ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html) has good practices, anti-patterns, review check list | ||
| 8. [An Adoption Model for Architectural Decision Making and Capturing](https://ozimmer.ch/practices/2023/04/21/ADAdoptionModel.html) | ||
|
|
||
| Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr). | ||
|
|
||
| ### Third-party articles | ||
|
|
||
| - [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser | ||
| - More will be featured in future versions of this page, suggestions are welcome! | ||
| - *to be continued* | ||
|
|
||
| ## From Architectural Decisions to Design/Any Decisions | ||
|
|
||
| [From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| --- | ||
| title: Decision Capturing Tools | ||
| toc: true | ||
| --- | ||
|
|
||
| > The following lists are rather inclusive and sorted alphabetically. | ||
| > Please find out about the status and the maturity of the list entries for yourself by following the links. | ||
| > We are happy to include more candidate assets here. | ||
| {: .prompt-info } | ||
|
|
||
| ## Tooling to create and maintain decision files | ||
|
|
||
| ### Any template | ||
|
|
||
| - [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR). | ||
|
|
||
| ### MADR template | ||
|
|
||
| | Name | MADR Version | Comment | | ||
| | ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | ||
| | [adr-log](https://github.com/adr/adr-log?tab=readme-ov-file#adr-log-) | 2.1.2 | CLI to keep an `index.md` file updated with all ADRs | | ||
| | [ADR Manager](https://adr.github.io/adr-manager/) | 2.1.2 | Web-based UI connecting to GitHub to directly edit ADRs in a form-based way | | ||
| | [ADR Manager VS Code Extension](https://github.com/adr/vscode-adr-manager) | 2.1.2 | Visual Studio Code (VS Code) extension | | ||
| | [Backstage ADR plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) | 2.1.2 and 3.x | plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos | | ||
| | [Hugo Markdown ADR Tools](https://github.com/butonic/adr-tools) | 2.1.2. | CLI to create and update ADRs | | ||
| | [Log4brains](https://github.com/thomvaill/log4brains) | 2.1.2 without numbers in the filename | Supports both nice rendering of ADRs and creation of ADRs in a command line. | | ||
| | [pyadr](https://github.com/opinionated-digital-center/pyadr) | 2.1.2 | CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/deprecation/superseding) | | ||
|
|
||
| ### Nygard template | ||
|
|
||
| - [adr-tools](https://github.com/npryce/adr-tools) - bash scripts to manage ADRs in the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html). [example](https://github.com/npryce/adr-tools/blob/master/doc/adr/0002-implement-as-shell-scripts.md). | ||
| - Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools) | ||
| - C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli) | ||
| - Go rewrite: [adr](https://github.com/marouni/adr) | ||
| - Java rewrite: [adr-j](https://github.com/adoble/adr-j) | ||
| - ESM Node.js port: [adr-tools](https://github.com/meza/adr-tools) | ||
| - Node.js rewrite: [adr](https://github.com/phodal/adr) | ||
| - PHP version: [phpadr](https://github.com/globtec/phpadr) | ||
| - Powershell module: [adr-ps](https://github.com/rdagumampan/adr-ps) | ||
| - Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/) | ||
| - Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords) | ||
| - Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs) | ||
| - [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs. | ||
| - [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes. | ||
| - [Loqbooq](https://loqbooq.app): Commerical Web App with Slack integration to record ADR-inspired decision logs | ||
| - [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types. | ||
|
|
||
| ## Tooling close to the code | ||
|
|
||
| - [(Java) Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations. | ||
|
|
||
| ## Tooling related to architecture management | ||
|
|
||
| - [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture | ||
| - [docToolchain](https://doctoolchain.github.io/docToolchain/): docToolchain is an implementation of the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach for software architecture plus some additional automation. | ||
| - [Structurizr](https://www.structurizr.com/): Structurizr is a collection of tooling to help you visualise, document and explore your software architecture using the [C4 model](https://c4model.com/). | ||
|
|
||
| ## Interesting, but unmaintained tooling | ||
|
|
||
| - [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs. | ||
| - [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/) | ||
| - [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions. | ||
| - [SE Repo](https://github.com/adr/serepo): Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,41 +1,5 @@ | ||
| --- | ||
| icon: fas fa-check-circle | ||
| order: 1 | ||
| order: 2 | ||
| title: AD Practices | ||
| --- | ||
|
|
||
| > The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. | ||
| {: .prompt-info } | ||
|
|
||
| [Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page. | ||
|
|
||
| ## AD Making | ||
|
|
||
| The [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book, feature an AD making and capturing activity, which is positioned as one of the essential activities in DPR. | ||
|
|
||
| [Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. | ||
|
|
||
| ## Good ADRs --- and How to Get to Them | ||
|
|
||
| ### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: | ||
|
|
||
| 1. [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html), suggesting five criteria abbreviated as START. | ||
| 2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) | ||
| 3. [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns. | ||
| 4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) | ||
| 5. [A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) proposes five criteria and a checklist to decide when it is time to set the status of a single decision to "done": evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the 'D' in *ecADR*. | ||
| 6. Context, background and examples of good and bad justifications can be found in [this blog post](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html). | ||
| 7. [How to review ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html) has good practices, anti-patterns, review check list | ||
| 8. [An Adoption Model for Architectural Decision Making and Capturing](https://ozimmer.ch/practices/2023/04/21/ADAdoptionModel.html) | ||
|
|
||
| Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr). | ||
|
|
||
| ### Third-party articles | ||
|
|
||
| - [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser | ||
| - More will be featured in future versions of this page, suggestions are welcome! | ||
| - *to be continued* | ||
|
|
||
| ## From Architectural Decisions to Design/Any Decisions | ||
|
|
||
| [From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. |
Oops, something went wrong.